ai-mail-mcp

Подключите частный почтовый ящик с собственным доменом к любому MCP-клиенту в качестве почтового сервиса. Поддерживает отправку (автоматическое добавление личной подписи / ссылки на страницу с описанием бренда), получение, чтение содержимого писем, проверку соединения.

Совместим с WorkBuddy, Claude Desktop, Cursor и другими инструментами, поддерживающими протокол MCP. Благодаря облачному развертыванию, WorkBuddy на ПК и мобильных устройствах может использовать один и тот же почтовый вход, обрабатывая свою почту с помощью естественного языка в любое время и в любом месте.

Особенности

• ✉️ send_email: отправка письма с автоматическим добавлением личной подписи "Отправлено xx через xx" (включая ссылку на страницу с описанием, которая может служить точкой входа для личного бренда)

• 📥 get_recent_emails: получение списка писем за последние N дней (тема / отправитель / время)

• 📖 get_email_content: чтение полного содержимого письма и информации о вложениях по UID

• 🔌 test_email_connection: проверка соединения SMTP/IMAP одним нажатием

• 🚀 Два способа передачи: stdio (локальная отладка) / SSE (облачное удаленное развертывание)

• 🔐 Аутентификация по Bearer Token на конечной точке, все учетные данные через переменные окружения, никакого жесткого кодирования

Архитектура

┌──────────────┐   HTTPS + Bearer   ┌──────────────────┐   SMTP/IMAP   ┌──────────────┐
│ WorkBuddy    │ ─────────────────▶ │ ai-mail-mcp      │ ────────────▶ │ 你的域名邮箱   │
│ 桌面端 / 移动端 │                   │ (云端 MCP Server) │               │ you@your.com │
└──────────────┘                   └──────────────────┘               └──────────────┘

Облачное развертывание — ключевой момент: одна HTTPS-конечная точка, доступная с ПК и мобильных устройств, локальная машина не должна быть включена.

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

1. Настройка переменных окружения

cp .env.example .env
# 编辑 .env，填入你的邮箱账号、授权码、SMTP/IMAP 地址、Bearer Token

2A. Локальная отладка (stdio)

npm install
MCP_TRANSPORT=stdio node server.js

2B. Облачное развертывание (SSE, рекомендуется)

Требуется сервер с публичным IP-адресом + домен (HTTPS).

cp .env.example .env   # 在服务器上填写真实配置
docker compose up -d

Затем используйте nginx в качестве обратного прокси + acme.sh/certbot для получения HTTPS-сертификата (в docker-compose.yml есть пример с комментариями), чтобы получить конечную точку вида https://mcp.your-domain.com/mail-mcp/sse.

3. Подключение к WorkBuddy (пользовательский коннектор)

Отредактируйте ~/.workbuddy/mcp.json:

{
  "mcpServers": {
    "ai-mail-mcp": {
      "type": "sse",
      "url": "https://mcp.your-domain.com/mail-mcp/sse",
      "headers": {
        "Authorization": "Bearer 你的随机Token"
      }
    }
  }
}

На странице управления коннекторами WorkBuddy нажмите Trust / Включить для этого коннектора и перезапустите сессию, после чего в диалоге можно:

• "Отправить письмо xx, тема…, текст…"

• "Посмотреть мои письма за последние 3 дня, подвести итог, на какие нужно ответить"

• "Каждое утро в 9:00 отправлять сводку вчерашних писем на мою почту"

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

Советы по безопасности

• MCP_BEARER_TOKEN обязательно должен быть достаточно длинной случайной строкой (сгенерированной с помощью openssl rand -hex 32) и храниться в надежном месте

• .env и реальные учетные данные не должны быть закоммичены ни в один репозиторий; в репозиторий этой документации коммитится только .env.example

• Для почты рекомендуется использовать отдельную учетную запись с минимальными правами (только отправка и получение, без прав на удаление/управление)

• Самостоятельное размещение означает, что данные писем полностью находятся на вашем сервере и не передаются третьим лицам

Лицензия

MIT