🔒 Mailbunker_MCP

Защищённый почтовый архив с нулевым доверием, приём входящих сообщений в реальном времени через IMAP Push (IDLE), генератор хранилища Obsidian и сервер Model Context Protocol (MCP).

English • Deutsch

📖 О проекте Mailbunker

Mailbunker_MCP — это открытый почтовый архив и семантический поисковый бункер, ориентированный на конфиденциальность, созданный для того, чтобы раз и навсегда решить проблемы почтового хаоса, привязки к вендору и сложностей с поиском.

Он подключается к любому количеству IMAP-аккаунтов (рабочих, личных, iCloud, Gmail, Posteo, Hetzner, Mailbox.org, собственных серверов), принимает входящие сообщения в реальном времени через IMAP IDLE Push, защищает всё с помощью шифрования Zero-Trust AES-256-GCM, созданного на основе вашего мастер-пароля с использованием Argon2id, индексирует все сообщения для полнотекстового поиска за миллисекунды (SQLite FTS5) и предоставляет стандартные инструменты Model Context Protocol (MCP) для Claude Desktop, Cursor и автономных ИИ-агентов.

Related MCP server: mailpouch

✨ Возможности

• ⚡ Приём Push-уведомлений в реальном времени (IMAP IDLE):

  • Мгновенный захват писем с нулевой задержкой, как только письмо достигает вашего провайдера (RFC 2177). Без задержек при периодическом опросе через cron.

  • Устойчивое автоматическое обновление keepalive и автоматическое переподключение с экспоненциальной задержкой.

• 🛡️ Шифрование при хранении с нулевым доверим:

  • Все тела писем (Markdown и HTML), необработанные заголовки и бинарные вложения (PDF, изображения, документы) шифруются с помощью AES-256-GCM.

  • Вывод мастер-ключа через устойчивый к памяти Argon2id (VAULT_PASSWORD), высокоустойчивый к атакам перебором на GPU/ASIC.

  • Ноль утечек открытого текста на диске или в Docker-томах.

• 🔍 Полнотекстовый поиск за миллисекунды (SQLite FTS5):

  • Поиск по 100 000+ писем за миллисекунды.

  • Поддержка булевых операторов (AND, OR, NOT), префиксного поиска (tax*), фразового поиска ("contract agreement") и структурированных фильтров (по отправителю, диапазону дат, аккаунту, папке, наличию вложений).

  • Генерация контекстных фрагментов с подсветкой совпадений.

• 📓 Готовый к Obsidian Markdown-хранилище:

  • Преобразование сложных HTML-писем в чистый GitHub Flavored Markdown.

  • Полные метаданные YAML frontmatter (id, subject, from, to, date, account, folder, tags, attachments).

  • Нативные вики-ссылки Obsidian для отслеживания цепочек писем ([[Parent Note]]).

  • Экспорт по запросу (mailbunker export-vault) или настройка автоматического экспорта в реальном времени.

• 🤖 Сервер Model Context Protocol (MCP):

  • Нативный сервер FastMCP, предоставляющий высокоуровневые инструменты: search_emails, get_email, list_accounts, list_mailboxes, sync_now, get_sync_status, export_obsidian_vault.

  • Бесшовная интеграция с Claude Desktop, Cursor IDE, Antigravity и любым MCP-совместимым ИИ-ассистентом.

• 🔑 Мультиаккаунт и интеграция с macOS Keychain:

  • Простая настройка от 1 до 5+ почтовых аккаунтов через .env (MAIL_1_... до MAIL_5_...).

  • Интерактивный помощник по импорту из macOS Keychain (mailbunker keychain-import).

🏗️ Архитектура

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

🚀 Быстрый старт

1. Установка

# 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. Конфигурация (.env)

Скопируйте предоставленный шаблон .env.example:

cp .env.example .env

Отредактируйте .env с вашими настройками:

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

Mailbunker поставляется с современным цветным терминальным CLI:

Примеры 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

🤖 Интеграция MCP (Claude Desktop / Cursor / Antigravity)

Добавьте Mailbunker в файл конфигурации MCP (например, claude_desktop_config.json или настройки 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"
      }
    }
  }
}

Доступные инструменты MCP

• search_emails(query, account, folder, start_date, end_date, limit): Быстрый поиск писем FTS5.

• get_email(email_id, format='markdown'|'json'|'text'): Получить полное расшифрованное сообщение.

• list_accounts(): Список настроенных аккаунтов, статусов и счётчиков.

• list_mailboxes(account_name): Список доступных папок почтового ящика.

• sync_now(account, folder): Немедленная синхронизация почтового ящика.

• get_sync_status(): Проверка статуса push-слушателя в реальном времени и статистики базы данных.

• export_obsidian_vault(target_path, password): Расшифровать и экспортировать хранилище.

🔒 Архитектура безопасности с нулевым доверим

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

• Ноль утечек открытого текста: Ни одно тело письма, необработанный заголовок или бинарное вложение никогда не хранится на диске в незашифрованном виде.

• Аутентифицированное шифрование: Теги проверки AES-256-GCM гарантируют целостность данных и обнаруживают подделку.

• Вывод ключа Argon2id: Параметры с высокой стоимостью памяти защищают от офлайн-взлома пароля GPU/ASIC.

🐳 Развёртывание в Docker

Запустите Mailbunker в изолированном Docker-контейнере:

docker compose up -d

🧪 Тестирование

Mailbunker включает в себя комплексный набор тестов:

source .venv/bin/activate
pytest -v

📄 Лицензия

Лицензия MIT — Copyright (c) 2026 cubetribe