Email MCP Server

Сервер Model Context Protocol (MCP), обеспечивающий доступ к электронной почте через IMAP и SMTP. Позволяет ИИ-агентам и приложениям читать, искать, отправлять и управлять письмами через стандартизированный интерфейс HTTP/SSE.

Функции

9 инструментов для работы с почтой через MCP:
- list_folders — список всех почтовых ящиков/папок IMAP
- search_emails — поиск писем с фильтрами (отправитель, тема, диапазон дат, статус прочтения/флага)
- read_email — получение полного содержимого письма, включая тело и метаданные вложений
- mark_email — пометка писем как прочитанных/непрочитанных или с флагом/без флага
- move_email — перемещение писем между папками
- send_email — отправка новых писем (обычный текст или многокомпонентный HTML)
- reply_email — ответ на письма с сохранением заголовков цепочки
- download_attachment — загрузка вложений в рабочую директорию
- send_email_with_attachments — отправка писем с вложениями из рабочей директории
Архитектура, готовая к промышленному использованию:
- Асинхронный IMAP/SMTP с пулом соединений
- Конфигурация и валидация на основе Pydantic
- Комплексная обработка ошибок со структурированными исключениями
- Аутентификация по API-ключу через заголовок X-API-Key
- Файл службы systemd для развертывания на Ubuntu
Разработка через тестирование (TDD):
- 85+ модульных и интеграционных тестов
- 100% покрытие основного функционала
- Моки почтовых серверов для воспроизводимого тестирования

Установка с Claude Desktop (рекомендуется)

Самый простой способ использовать этот сервер — через пакет MCPB, однофайловый установщик для Claude Desktop.

1. Скачивание

Скачайте email_mcp.mcpb из последнего релиза.

2. Установка

Дважды щелкните email_mcp.mcpb. Claude Desktop откроет диалоговое окно установки.

3. Настройка

Введите учетные данные вашего почтового сервера при появлении запроса. Все значения сохраняются в связке ключей ОС (macOS Keychain / Linux Secret Service):

Поле	Описание	Пример
IMAP Host	Имя хоста IMAP-сервера	`imap.gmail.com`
IMAP Port	Порт IMAP-сервера	`993` (SSL) · `143` (STARTTLS)
IMAP Username	Ваш адрес электронной почты	`you@example.com`
IMAP Password	Пароль или пароль приложения	`xxxx xxxx xxxx xxxx`
IMAP SSL	Использовать SSL/TLS для IMAP	`true` (порт 993) · `false` (порт 143)
SMTP Host	Имя хоста SMTP-сервера	`smtp.gmail.com`
SMTP Port	Порт SMTP-сервера	`587` (STARTTLS) · `465` (SSL)
SMTP Username	Ваш адрес электронной почты	`you@example.com`
SMTP Password	Пароль или пароль приложения	`xxxx xxxx xxxx xxxx`
SMTP STARTTLS	Режим STARTTLS	`true` (порт 587) · `false` · `none` (авто)

Пользователи Gmail: Вы должны использовать пароль приложения, а не обычный пароль от учетной записи Google. Включите IMAP в настройках Gmail → Пересылка и POP/IMAP.

4. Использование

После установки Claude сможет получить доступ к вашей почте. Попробуйте:

"Список моих непрочитанных писем за эту неделю" "Поиск писем от alice@example.com по проекту" "Отправь письмо bob@example.com с темой 'Привет' и текстом 'Привет, Боб!'" "Скачай первое вложение из письма с UID 12345" "Отправь письмо с вложением report.pdf на адрес team@example.com"

Требования

Python 3.10+ (рекомендуется 3.13)
Доступ к IMAP и SMTP серверам
API-ключ для аутентификации MCP

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

1. Клонирование и настройка

git clone https://github.com/pzanna/email_mcp.git
cd email_mcp
python3 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install -r requirements.txt

2. Настройка окружения

cp .env.example .env
# Edit .env with your credentials

Необходимые переменные окружения:

# IMAP Configuration
IMAP_HOST=imap.gmail.com
IMAP_PORT=993
IMAP_USER=you@gmail.com
IMAP_PASSWORD=your-app-password
IMAP_SSL=true

# SMTP Configuration
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=you@gmail.com
SMTP_PASSWORD=your-app-password
# SMTP_STARTTLS mode: "none" (auto), "true" (force), "false" (disable)
SMTP_STARTTLS=true

# MCP Server Configuration
MCP_API_KEY=your-secret-api-key-here
MCP_HOST=127.0.0.1
MCP_PORT=8420
MCP_SERVER_NAME=email-mcp
MCP_BASE_URL=http://localhost:8420

# Optional
DEFAULT_FROM_NAME=Your Name
MAX_SEARCH_RESULTS=50
IMAP_POOL_SIZE=3

# Attachment Configuration
EMAIL_BASE_DIR=/path/to/workspace
MAX_ATTACHMENT_SIZE_MB=50

3. Запуск сервера

Локальная разработка (Mac/Linux):

source .venv/bin/activate
uvicorn main:app --host 127.0.0.1 --port 8420

Доступ к серверу:

MCP эндпоинт: http://localhost:8420/mcp
Проверка работоспособности: http://localhost:8420/health
Документация API: http://localhost:8420/docs

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

# Run all tests
pytest tests/ -v

# Run with coverage
pytest tests/ --cov=. --cov-report=html

# Run specific test file
pytest tests/test_integration.py -v

# Run specific test
pytest tests/test_send.py::test_send_email_plain_text -v

Все 85+ тестов должны пройти успешно.

Примеры использования

Аутентификация

Все MCP эндпоинты требуют заголовок X-API-Key:

curl -H "X-API-Key: your-secret-api-key-here" \
  http://localhost:8420/mcp/tools

Список доступных инструментов

curl -X GET http://localhost:8420/mcp/tools \
  -H "X-API-Key: your-secret-api-key-here"

Поиск писем

curl -X POST http://localhost:8420/mcp/call \
  -H "X-API-Key: your-secret-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "tools/call",
    "params": {
      "name": "search_emails",
      "arguments": {
        "from": "user@example.com",
        "subject": "invoice",
        "since": "2024-01-01",
        "limit": 10
      }
    }
  }'

Отправка письма

curl -X POST http://localhost:8420/mcp/call \
  -H "X-API-Key: your-secret-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "tools/call",
    "params": {
      "name": "send_email",
      "arguments": {
        "to": ["recipient@example.com"],
        "subject": "Test Email",
        "body": "This is a test email.",
        "from_name": "My Name"
      }
    }
  }'

Чтение письма

curl -X POST http://localhost:8420/mcp/call \
  -H "X-API-Key: your-secret-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "tools/call",
    "params": {
      "name": "read_email",
      "arguments": {
        "uid": "12345",
        "folder": "INBOX"
      }
    }
  }'

Загрузка вложения

curl -X POST http://localhost:8420/mcp/call \
  -H "X-API-Key: your-secret-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "tools/call",
    "params": {
      "name": "download_attachment",
      "arguments": {
        "uid": "12345",
        "attachment_index": 0,
        "folder": "INBOX",
        "filename_override": "renamed_file.pdf"
      }
    }
  }'

Загружает вложение в EMAIL_BASE_DIR/attachments/email/downloads/ с проверкой безопасности, чтобы файлы оставались внутри базовой директории.

Отправка письма с вложениями

curl -X POST http://localhost:8420/mcp/call \
  -H "X-API-Key: your-secret-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "tools/call",
    "params": {
      "name": "send_email_with_attachments",
      "arguments": {
        "to": ["recipient@example.com"],
        "cc": ["manager@example.com"],
        "subject": "Monthly Report",
        "body": "Please find the reports attached.",
        "body_html": "<p>Please find the <strong>reports</strong> attached.</p>",
        "from_name": "John Doe",
        "attachment_paths": [
          "attachments/email/uploads/report1.pdf",
          "attachments/email/uploads/report2.xlsx"
        ]
      }
    }
  }'

Прикрепляет файлы из рабочей директории с полной проверкой безопасности и ограничением размера.

Работа с вложениями

Email MCP сервер обеспечивает безопасную работу с вложениями через управление файлами в рабочей директории.

Структура рабочей директории

Все операции с вложениями ограничены настроенной рабочей директорией:

EMAIL_BASE_DIR/
└── attachments/
    └── email/
        ├── downloads/    # Downloaded email attachments
        └── uploads/      # Files ready to attach to outgoing emails

Функции безопасности

Изоляция рабочей директории: Все файловые операции ограничены EMAIL_BASE_DIR
Защита от обхода пути: Предотвращает доступ к файлам вне рабочей директории
Санитизация имен файлов: Удаляет опасные символы и обрабатывает зарезервированные имена
Ограничения размера: Настраиваемые лимиты на размер файла и общий объем вложений
Валидация типов файлов: Гарантирует, что пути к вложениям указывают на реальные файлы

Примеры рабочих процессов

Процесс «Загрузка → Отправка»:

Используйте download_attachment для сохранения вложений в downloads/
Переместите или скопируйте файлы в uploads/ по мере необходимости
Используйте send_email_with_attachments для отправки файлов из uploads/

Процесс «Прямая загрузка»:

Поместите файлы в директорию uploads/
Используйте send_email_with_attachments с путями относительно рабочей директории

Конфигурация

# Workspace directory (required for attachment operations)
EMAIL_BASE_DIR=/path/to/your/workspace

# Maximum attachment size per file (default: 50MB)
MAX_ATTACHMENT_SIZE_MB=50

Развертывание

Ubuntu Server с systemd

Скопируйте файлы на сервер:

scp -r email_mcp user@server:/home/user/

Настройте окружение Python:

ssh user@server
cd ~/email_mcp
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Настройте удаленный доступ: Отредактируйте .env:

MCP_HOST=0.0.0.0  # Allow remote connections
MCP_BASE_URL=http://<your-server-ip>:8420  # Your server IP

Установите службу systemd:

# Edit email-mcp.service to match your paths
sudo cp email-mcp.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable email-mcp
sudo systemctl start email-mcp

Проверьте статус:

sudo systemctl status email-mcp
sudo journalctl -u email-mcp -f  # View logs

Настройка MCP-клиента

Добавьте в конфигурацию вашего MCP-клиента:

{
  "mcpServers": {
    "email": {
      "url": "http://localhost:8420/mcp",
      "headers": {
        "X-API-Key": "your-secret-api-key-here"
      }
    }
  }
}

Для удаленного сервера используйте http://<your-server-ip>:8420/mcp (замените на IP вашего сервера).

Архитектура

email_mcp/
├── main.py                 # FastAPI application entry point (HTTP/SSE mode)
├── mcp_server.py           # Stdio MCP entry point (MCPB / Claude Desktop mode)
├── config.py               # Pydantic settings (env vars)
├── auth.py                 # API key authentication middleware
├── imap/
│   ├── client.py          # IMAP connection pool
│   ├── read.py            # list_folders, read_email
│   ├── search.py          # search_emails
│   ├── flags.py           # mark_email, move_email
│   └── attachments.py     # download_attachment
├── smtp/
│   ├── client.py          # send_email, reply_email
│   └── attachments.py     # send_email_with_attachments
├── tools/
│   ├── definitions.py     # MCP tool schemas
│   ├── handlers.py        # Tool request routing
│   └── mcp_routes.py      # MCP HTTP endpoints
├── utils/
│   └── attachment_utils.py # Secure file handling utilities
└── tests/                  # 85+ unit and integration tests

Ключевые паттерны проектирования

Пул соединений: asyncio.Semaphore ограничивает количество одновременных IMAP-соединений (по умолчанию: 3)
Обработка ошибок: Структурированные исключения отображаются на ответы об ошибках MCP
Цепочки писем: Заголовки In-Reply-To и References для цепочек ответов
Многокомпонентные сообщения: Обход дерева сообщений для извлечения текста/HTML/вложений
Без бинарной передачи: Вложения возвращают только метаданные (имя файла, размер, content_type)

Устранение неполадок

Настройка для Gmail

Включите IMAP: Настройки → Пересылка и POP/IMAP → Включить IMAP
Пароль приложения: Используйте пароль приложения вместо обычного пароля
Gmail SMTP: Используйте smtp.gmail.com:587 с STARTTLS

Проблемы с подключением

# Test IMAP connection
openssl s_client -connect imap.gmail.com:993

# Test SMTP connection
openssl s_client -starttls smtp -connect smtp.gmail.com:587

Распространенные ошибки

CONNECTION_TIMEOUT: Проверьте IMAP_HOST и IMAP_PORT
AUTH_FAILED: Проверьте учетные данные, используйте пароль приложения для Gmail
FOLDER_NOT_FOUND: Имена папок чувствительны к регистру (используйте list_folders для проверки)
MESSAGE_NOT_FOUND: UID может быть неверным или сообщение было удалено

SMTPException - Connection already using TLS: Установите SMTP_STARTTLS=none в .env для автоматического режима. Допустимые значения: none, true и false.

Разработка

Структура проекта

imap/ — IMAP-клиент и инструменты (чтение, поиск, флаги)
smtp/ — SMTP-клиент и инструменты (отправка, ответ)
tools/ — обработчики эндпоинтов MCP и схемы
tests/ — модульные и интеграционные тесты

Запуск в режиме разработки

# Auto-reload on file changes
uvicorn main:app --reload --host 127.0.0.1 --port 8420

# Debug mode with verbose logging
LOG_LEVEL=DEBUG uvicorn main:app --host 127.0.0.1 --port 8420

Добавление новых инструментов

Определите модели Pydantic для ввода/вывода в соответствующем модуле
Реализуйте асинхронную функцию с обработкой ошибок
Добавьте схему инструмента в tools/definitions.py
Подключите диспетчер в tools/mcp_routes.py
Напишите тесты, следуя подходу TDD

Лицензия

MIT

Участие в разработке

Вклад приветствуется! Пожалуйста:

Пишите тесты для всех новых функций
Соблюдайте существующий стиль кода (black, isort, mypy)
Обновляйте этот README при значительных изменениях
Убедитесь, что все тесты проходят перед отправкой PR

Поддержка

По вопросам, проблемам или предложениям, пожалуйста, создайте issue на GitHub.