🔒 Mailbunker_MCP

Archivo de correo electrónico cifrado de confianza cero, ingesta push IMAP en tiempo real (IDLE), generador de bóveda Obsidian y servidor de Protocolo de Contexto de Modelo (MCP).

English • Deutsch

📖 Acerca de Mailbunker

Mailbunker_MCP es un búnker de archivado y búsqueda semántica de correo electrónico de código abierto y centrado en la privacidad, diseñado para resolver de una vez por todas el desorden del correo, el bloqueo de proveedor y los desafíos de recuperación.

Se conecta a cualquier número de cuentas de correo IMAP (Trabajo, Personal, iCloud, Gmail, Posteo, Hetzner, Mailbox.org, servidores personalizados), ingiere los mensajes entrantes en tiempo real mediante IMAP IDLE Push, protege todo con cifrado de confianza cero AES-256-GCM derivado de tu contraseña maestra usando Argon2id, indexa todos los mensajes para búsqueda de texto completo en sub-milisegundos (SQLite FTS5) y expone herramientas estándar del Protocolo de Contexto de Modelo (MCP) para Claude Desktop, Cursor y agentes de IA autónomos.

Related MCP server: mailpouch

✨ Características

• ⚡ Ingesta push en tiempo real (IMAP IDLE):

  • Captura instantánea de correo sin demora en cuanto un correo llega a tu proveedor (RFC 2177). Sin necesidad de sondeos cron retrasados.

  • Refresco automático de keepalive resistente y reconexión automática con retroceso exponencial.

• 🛡️ Cifrado en reposo de confianza cero:

  • Todos los cuerpos de correo (Markdown y HTML), encabezados sin procesar y adjuntos binarios (PDF, imágenes, documentos) se cifran con AES-256-GCM.

  • Derivación de clave maestra mediante Argon2id de memoria intensiva (VAULT_PASSWORD), altamente resistente a ataques de fuerza bruta por GPU/ASIC.

  • Cero fugas de texto plano en disco o en volúmenes Docker.

• 🔍 Búsqueda de texto completo en sub-milisegundos (SQLite FTS5):

  • Busca entre más de 100,000 correos en milisegundos.

  • Soporta operadores booleanos (AND, OR, NOT), coincidencia de prefijos (tax*), búsqueda de frases ("contrato de acuerdo") y filtros estructurados (por remitente, rango de fechas, cuenta, carpeta, presencia de adjuntos).

  • Generación de fragmentos contextuales enriquecidos con resaltado de coincidencias.

• 📓 Bóveda Markdown lista para Obsidian:

  • Convierte correos HTML complejos en Markdown limpio de GitHub Flavored Markdown.

  • Metadatos completos en frontmatter YAML (id, subject, from, to, date, account, folder, tags, attachments).

  • Wikilinks nativos de Obsidian para seguimiento de hilos de correo ([[Nota Padre]]).

  • Exportación bajo demanda (mailbunker export-vault) o configura la exportación automática en vivo.

• 🤖 Servidor de Protocolo de Contexto de Modelo (MCP):

  • Servidor FastMCP nativo que proporciona herramientas de alto nivel: search_emails, get_email, list_accounts, list_mailboxes, sync_now, get_sync_status, export_obsidian_vault.

  • Se integra perfectamente con Claude Desktop, IDE Cursor, Antigravity y cualquier asistente de IA compatible con MCP.

• 🔑 Integración multi-cuenta y con Llavero de macOS:

  • Configuración sencilla para 1 a 5+ cuentas de correo mediante .env (MAIL_1_... hasta MAIL_5_...).

  • Asistente interactivo de descubrimiento del Llavero de macOS (mailbunker keychain-import).

🏗️ Arquitectura

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

🚀 Inicio rápido

1. Instalación

# 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. Configuración (.env)

Copia la plantilla .env.example proporcionada:

cp .env.example .env

Edita .env con tus ajustes:

# ==============================================================================
# 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

💻 Comandos CLI

Mailbunker viene con una CLI de terminal moderna y con colores:

Ejemplos CLI

# 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

🤖 Integración MCP (Claude Desktop / Cursor / Antigravity)

Añade Mailbunker a tu archivo de configuración MCP (por ejemplo, claude_desktop_config.json o Configuración de Cursor):

{
  "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"
      }
    }
  }
}

Herramientas MCP disponibles

• search_emails(query, account, folder, start_date, end_date, limit): Búsqueda rápida de correos con FTS5.

• get_email(email_id, format='markdown'|'json'|'text'): Recupera el mensaje completo descifrado.

• list_accounts(): Lista las cuentas configuradas, estados y recuentos.

• list_mailboxes(account_name): Lista las carpetas de buzón disponibles.

• sync_now(account, folder): Activa la sincronización inmediata del buzón.

• get_sync_status(): Inspecciona el estado del listener push en tiempo real y las estadísticas de la base de datos.

• export_obsidian_vault(target_path, password): Descifra y exporta la bóveda.

🔒 Arquitectura de seguridad de confianza cero

[ 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/... ]

• Cero fugas de texto plano: Ningún cuerpo de correo, encabezado sin procesar o adjunto binario se almacena sin cifrar en el disco.

• Cifrado autenticado: Las etiquetas de verificación AES-256-GCM garantizan la integridad de los datos y detectan manipulaciones.

• Derivación de clave Argon2id: Parámetros de alto costo de memoria protegen contra el descifrado de contraseñas por GPU/ASIC fuera de línea.

🐳 Despliegue con Docker

Ejecuta Mailbunker en un contenedor Docker aislado:

docker compose up -d

🧪 Pruebas

Mailbunker incluye un conjunto completo de pruebas:

source .venv/bin/activate
pytest -v

📄 Licencia

Licencia MIT — Copyright (c) 2026 cubetribe