🔒 Mailbunker_MCP

Zero-Trust-verschlüsseltes E-Mail-Archiv, Echtzeit-IMAP-Push-Ingestion (IDLE), Obsidian-Vault-Generator und Model Context Protocol (MCP)-Server.

English • Deutsch

📖 Über Mailbunker

Mailbunker_MCP ist ein Open-Source-, datenschutzorientiertes E-Mail-Archivierungs- und semantisches Such-Bunker, das entwickelt wurde, um E-Mail-Chaos, Vendor-Lock-in und Abrufprobleme ein für alle Mal zu lösen.

Es verbindet sich mit beliebig vielen IMAP-E-Mail-Konten (Arbeit, Privat, iCloud, Gmail, Posteo, Hetzner, Mailbox.org, eigene Server), erfasst eingehende Nachrichten in Echtzeit über IMAP IDLE Push, schützt alles mit Zero-Trust-AES-256-GCM-Verschlüsselung, die aus Ihrem Master-Passwort mittels Argon2id abgeleitet wird, indexiert alle Nachrichten für Sub-Millisekunden-Volltextsuche (SQLite FTS5) und stellt standardmäßige Model Context Protocol (MCP)-Tools für Claude Desktop, Cursor und autonome KI-Agenten bereit.

Related MCP server: mailpouch

✨ Funktionen

• ⚡ Echtzeit-Push-Ingestion (IMAP IDLE):

  • Sofortige E-Mail-Erfassung ohne Verzögerung, sobald eine E-Mail Ihren Anbieter erreicht (RFC 2177). Kein verzögertes Cron-Polling erforderlich.

  • Robuste automatische Keepalive-Aktualisierung und exponentielles Backoff mit automatischer Wiederverbindung.

• 🛡️ Zero-Trust-Verschlüsselung im Ruhezustand:

  • Alle E-Mail-Inhalte (Markdown & HTML), rohe Header und binäre Anhänge (PDFs, Bilder, Dokumente) werden mit AES-256-GCM verschlüsselt.

  • Master-Schlüsselableitung über speicherintensives Argon2id (VAULT_PASSWORD), hochresistent gegen GPU/ASIC-Brute-Force-Angriffe.

  • Kein Klartext-Leak auf der Festplatte oder in Docker-Volumes.

• 🔍 Sub-Millisekunden-Volltextsuche (SQLite FTS5):

  • Durchsuchen Sie 100.000+ E-Mails in Millisekunden.

  • Unterstützt boolesche Operatoren (AND, OR, NOT), Präfix-Matching (tax*), Phrasensuche ("contract agreement") und strukturierte Filter (nach Absender, Datumsbereich, Konto, Ordner, Vorhandensein von Anhängen).

  • Umfangreiche kontextbezogene Snippet-Generierung mit Treffer-Hervorhebung.

• 📓 Obsidian-fähiges Markdown-Vault:

  • Konvertiert komplexe HTML-E-Mails in sauberes GitHub Flavored Markdown.

  • Vollständige YAML-Frontmatter-Metadaten (id, subject, from, to, date, account, folder, tags, attachments).

  • Native Obsidian-Wikilinks für E-Mail-Thread-Verfolgung ([[Parent Note]]).

  • Export auf Abruf (mailbunker export-vault) oder konfigurierbarer Live-Auto-Export.

• 🤖 Model Context Protocol (MCP)-Server:

  • Nativer FastMCP-Server mit High-Level-Tools: search_emails, get_email, list_accounts, list_mailboxes, sync_now, get_sync_status, export_obsidian_vault.

  • Nahtlose Integration mit Claude Desktop, Cursor IDE, Antigravity und jedem MCP-konformen KI-Assistenten.

• 🔑 Multi-Konto- & macOS-Keychain-Integration:

  • Einfache Einrichtung für 1 bis 5+ E-Mail-Konten über .env (MAIL_1_... bis MAIL_5_...).

  • Interaktiver macOS-Keychain-Erkennungsassistent (mailbunker keychain-import).

🏗️ Architektur

graph TD
    subgraph Email_Sources [Email Sources]
        A1[Account 1: IMAP IDLE Push]
        A2[Account 2: IMAP IDLE Push]
        A3[Account 3..N: .env / Config]
        KC[macOS Keychain Helper]
    end

    subgraph Mailbunker_Core [Mailbunker Core Engine]
        SM[Sync & IDLE Manager]
        MP[MIME & HTML to Markdown Parser]
        CE[Zero-Trust Crypto Engine: AES-256-GCM + Argon2id]
        FTS[SQLite Database + FTS5 Search Index]
        OV[Obsidian Vault Generator]
    end

    subgraph Interfaces [Interfaces & Consumers]
        MCP[MCP Server: FastMCP Tools & Resources]
        CLI[Rich CLI: start, sync, search, get, export]
        OBS[Decrypted Obsidian Vault]
        AI[AI Assistants / Claude / Cursor]
    end

    A1 --> SM
    A2 --> SM
    A3 --> SM
    KC -.-> A3
    SM --> MP
    MP --> CE
    CE --> FTS
    CE --> OV
    FTS --> MCP
    FTS --> CLI
    OV --> OBS
    MCP --> AI
    CLI --> OBS

🚀 Schnellstart

1. Installation

# Clone the repository
git clone https://github.com/cubetribe/Mailbunker_MCP.git
cd Mailbunker_MCP

# Create virtual environment and install dependencies
uv venv
source .venv/bin/activate
uv pip install -e .

2. Konfiguration (.env)

Kopieren Sie die bereitgestellte .env.example-Vorlage:

cp .env.example .env

Bearbeiten Sie .env mit Ihren Einstellungen:

# ==============================================================================
# Zero-Trust Master Password (REQUIRED)
# ==============================================================================
VAULT_PASSWORD=your-super-secure-master-password-here

# Base storage path for encrypted database and attachments
STORAGE_PATH=./data

# ==============================================================================
# Email Accounts (Configure Mail 1 through 5, or more)
# ==============================================================================
MAIL_1_ENABLED=true
MAIL_1_NAME=Work
MAIL_1_HOST=imap.example.com
MAIL_1_PORT=993
MAIL_1_USER=user@example.com
MAIL_1_PASSWORD=your_app_specific_password
MAIL_1_SSL=true
MAIL_1_FOLDERS=INBOX,Sent

MAIL_2_ENABLED=false
MAIL_2_NAME=Personal
MAIL_2_HOST=imap.posteo.de
MAIL_2_PORT=993
MAIL_2_USER=personal@posteo.de
MAIL_2_PASSWORD=your_password
MAIL_2_SSL=true
MAIL_2_FOLDERS=INBOX

💻 CLI-Befehle

Mailbunker wird mit einer modernen, farbigen Terminal-CLI geliefert:

CLI-Beispiele

# Sync all accounts immediately
mailbunker sync

# Search for 2026 invoices
mailbunker search "invoice 2026"

# Check bunker health and statistics
mailbunker status

# Decrypt and export into an Obsidian Vault folder
mailbunker export-vault --output ~/Documents/Obsidian/MailVault

🤖 MCP-Integration (Claude Desktop / Cursor / Antigravity)

Fügen Sie Mailbunker zu Ihrer MCP-Konfigurationsdatei hinzu (z. B. claude_desktop_config.json oder Cursor-Einstellungen):

{
  "mcpServers": {
    "mailbunker": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/Mailbunker_MCP",
        "run",
        "mailbunker-mcp"
      ],
      "env": {
        "VAULT_PASSWORD": "your-super-secure-master-password-here",
        "STORAGE_PATH": "/path/to/Mailbunker_MCP/data"
      }
    }
  }
}

Verfügbare MCP-Tools

• search_emails(query, account, folder, start_date, end_date, limit): Schnelle FTS5-E-Mail-Suche.

• get_email(email_id, format='markdown'|'json'|'text'): Vollständige entschlüsselte Nachricht abrufen.

• list_accounts(): Konfigurierte Konten, Status und Anzahl auflisten.

• list_mailboxes(account_name): Verfügbare Postfach-Ordner auflisten.

• sync_now(account, folder): Sofortige Postfach-Synchronisierung auslösen.

• get_sync_status(): Echtzeit-Push-Listener-Status & Datenbankstatistiken prüfen.

• export_obsidian_vault(target_path, password): Vault entschlüsseln und exportieren.

🔒 Zero-Trust-Sicherheitsarchitektur

[ Master Password: VAULT_PASSWORD ]
                 │
                 ▼ Argon2id KDF (16-byte Salt, 64MB RAM, 3 Iterations)
        [ 256-bit AES-GCM Key ]
                 │
  ┌──────────────┴──────────────┐
  ▼                             ▼
[ Email Payloads ]       [ Attachment Files ]
(Body, Headers, JSON)    (PDFs, Office Docs, Images)
  │                             │
  ▼ AES-256-GCM (IV + Tag)      ▼ AES-256-GCM (IV + Tag)
[ Encrypted SQLite DB ]  [ data/attachments/... ]

• Kein Klartext-Leak: Kein E-Mail-Inhalt, roher Header oder binärer Anhang wird jemals unverschlüsselt auf der Festplatte gespeichert.

• Authentifizierte Verschlüsselung: AES-256-GCM-Verifikationstags gewährleisten Datenintegrität und erkennen Manipulationen.

• Argon2id-Schlüsselableitung: Hohe Speicherkosten-Parameter schützen vor Offline-GPU/ASIC-Passwort-Cracking.

🐳 Docker-Bereitstellung

Führen Sie Mailbunker in einem isolierten Docker-Container aus:

docker compose up -d

🧪 Tests

Mailbunker enthält eine umfassende Testsuite:

source .venv/bin/activate
pytest -v

📄 Lizenz

MIT-Lizenz — Copyright (c) 2026 cubetribe