mail-mcp

Самодостаточная почтовая служба, не зависящая от провайдера. Подключите её к учётным данным IMAP/SMTP любого почтового ящика, и она предоставит:

• REST API, отражающий стандартные операции с почтовыми ящиками: список папок, список/получение/поиск сообщений, отправка, установка флагов, перемещение, удаление, квота (по возможности).

• Webhooks (message.received) через постоянный наблюдатель IMAP IDLE — отправляет HTTP POST (с секретным ключом Bearer для каждого вебхука) при поступлении новой почты, с повторными попытками с экспоненциальной задержкой (до 6 попыток) в случае сбоя принимающей конечной точки.

• MCP server (Streamable HTTP, POST /mcp) с теми же операциями в виде инструментов, так что любой MCP-совместимый агент может использовать их напрямую.

Мультипочтовость с самого начала: добавляйте столько учётных записей, сколько нужно, в config/accounts.json.

Тела запросов в REST API проверяются с помощью Zod (lib/schemas.js) — недопустимые данные получают ответ 422 ERR_VALIDATION_FAILED с ошибками на уровне полей, не доходя до почтового слоя. Подписки на вебхуки хранятся в SQLite (config/webhooks.sqlite, через better-sqlite3) вместо плоского JSON-файла. Сообщения размером больше MAIL_MCP_MAX_MESSAGE_SIZE (по умолчанию 25 МБ) возвращаются с bodyTruncated: true и без разобранного тела/вложений, чтобы избежать загрузки огромных сообщений в память.

Setup

npm install
cp .env.example .env   # fill in MAIL_MCP_API_TOKEN and one MAILMCP_PASS_<ID> per account

Скопируйте config/accounts.json.example в config/accounts.json (добавлен в .gitignore — паролей в этом файле тоже нет, они хранятся только в .env):

[
  {
    "id": "example",
    "user": "user@example.com",
    "imap": { "host": "imap.example.com", "port": 993, "secure": true },
    "smtp": { "host": "smtp.example.com", "port": 465, "secure": true }
  }
]

Пароль для учётной записи с id: "example" считывается из MAILMCP_PASS_EXAMPLE.

node index.js

По умолчанию работает на 127.0.0.1:4900 (см. MAIL_MCP_PORT). Если нужен доступ извне хоста, поместите его за обратный прокси-сервер с TLS.

Related MCP server: Agent Email

systemd

Пример блока находится в deploy/mail-mcp.service — скопируйте его в /etc/systemd/system/, настройте пути, и он будет загружать секреты из /root/mail-mcp/.env через EnvironmentFile.

Auth

Каждый REST и MCP запрос требует Authorization: Bearer <MAIL_MCP_API_TOKEN>.

Tests

npm test              # run once
npm run test:coverage # run with coverage report

Покрытие тестами охватывает чистые/логические модули (lib/schemas.js, lib/accounts.js, lib/webhooks-store.js). lib/mailclient.js и lib/idle-watcher.js взаимодействуют с реальными IMAP/SMTP-серверами и проверяются через ручное сквозное тестирование, а не модульными тестами — они исключены из значка покрытия, чтобы он не вводил в заблуждение.