IMAP MCP Server — подключение почты к ИИ-агентам с шифрованием и пулом соединений

IMAP MCP Server — это MCP-сервер на TypeScript, который даёт ИИ-агентам полный доступ к вашей электронной почте по протоколам IMAP и SMTP. Он умеет читать и искать письма, отправлять, отвечать и пересылать, перемещать между папками, помечать, удалять и управлять папками. Главное — учётные записи хранятся зашифрованными, а соединениями управляет пул с автоматическим переподключением.

Требуется Node.js 22.12 или новее (Node 18 и 20 уже не поддерживаются зависимостями проекта).

Установка

Проще всего запустить сервер через npx, не клонируя репозиторий:

npx -y imap-mcp-server

Для быстрой установки на macOS/Linux:

curl -fsSL https://raw.githubusercontent.com/nikolausm/imap-mcp-server/main/install.sh | bash

Или вручную: клонировать репозиторий, выполнить npm install и npm run build.

Настройка аккаунтов

Учётные записи хранятся в зашифрованном виде в ~/.imap-mcp/accounts.json. Файл общий для всех способов запуска (npx, глобальная установка, локальный клон) — аккаунты настраиваются один раз.

Добавить аккаунт можно тремя способами:

1. Веб-мастер настройки — npm run setup (или imap-setup) запускает локальный веб-сервер с мастером, где есть пресеты под 15+ провайдеров.
2. Напрямую через ассистента — попросите его выполнить инструмент imap_add_account:

   «Add my IMAP account: host imap.gmail.com, port 993, user me@gmail.com, password …»

3. Через npx без установки — npx -p imap-mcp-server imap-setup.

Переопределение паролей через переменные окружения

Вместо хранения пароля в accounts.json можно указать его переменной окружения. Имена переменных формируются из имени аккаунта заглавными буквами с заменой небуквенных символов на _. Для аккаунта Work Gmail (ключ WORK_GMAIL):

Важные нюансы: переопределения применяются только к уже существующим аккаунтам, работают только в памяти (ничего не записывается в файл) и читаются один раз при старте сервера. Значения извлекаются из process.env и помещаются в зашифрованный in-memory кэш, чтобы секрет не протекал в дочерние процессы и диагностику. В мастере настройки у каждого поля пароля есть флажок «не сохранять в конфиг, задать переменной окружения» — тогда значение используется для проверки соединения, но не записывается.

Поддерживаемые провайдеры

Gmail / Google Workspace, Outlook / Hotmail / Live, Yahoo, Apple iCloud, GMX, WEB.DE, IONOS (1&1), ProtonMail (через Bridge), Fastmail, Zoho, AOL, mailbox.org, Posteo и произвольные IMAP-серверы.

Подключение к агенту

Claude Code (CLI)

Через npx (без сборки):

claude mcp add imap -- npx -y imap-mcp-server

Из локального клона:

claude mcp add imap -- node /absolute/path/to/imap-mcp-server/dist/index.js

Проверить подключение — claude mcp list, удалить — claude mcp remove imap.

Claude Desktop (GUI)

Добавьте в claude_desktop_config.json (~/Library/Application Support/Claude/ на macOS, %APPDATA%\Claude\ на Windows):

{
  "mcpServers": {
    "imap": {
      "command": "npx",
      "args": ["-y", "imap-mcp-server"],
      "env": {}
    }
  }
}

Ограничение доступа инструментов

По умолчанию доступны все инструменты. Двумя переменными окружения можно сузить их набор:

Пример read-only доступа:

{
  "mcpServers": {
    "imap": {
      "command": "npx",
      "args": ["-y", "imap-mcp-server"],
      "env": { "IMAP_MCP_READ_ONLY": "true" }
    }
  }
}

Инструменты

Управление аккаунтами

• imap_add_account — добавить аккаунт (host, port, user, password, tls, опционально sentFolder и defaultBcc).
• imap_update_account — обновить аккаунт: поправить SMTP-настройки, переименовать, сменить пароль, настроить копию в «Отправленные» и BCC по умолчанию.
• imap_list_accounts — список всех аккаунтов.
• imap_remove_account — удалить аккаунт.
• imap_connect / imap_disconnect — подключиться / отключиться.

Для email- и папко-инструментов accountId опционален: можно передать accountName, а при единственном аккаунте опустить вовсе. С несколькими аккаунтами без селектора сервер вернёт понятную ошибку со списком вариантов.

Работа с письмами

• imap_search_emails — поиск по отправителю, теме, телу, дате, флагам и кастомным ключевым словам. Есть searchAllFolders для поиска по всем папкам сразу (пропускает Trash/Spam/Drafts) и includeBody, чтобы получить тело письма тем же вызовом (без N+1 запросов).
• imap_get_email — полное содержимое письма по UID.
• imap_get_latest_emails — последние письма папки.
• imap_mark_as_read / imap_mark_as_unread — изменить статус прочтения. Принимает массив UID: батч идёт одной IMAP STORE-операцией, атомарно на стороне сервера.
• imap_flag_email / imap_unflag_email — поставить / снять «звезду» (флаг \Flagged).
• imap_add_keyword / imap_remove_keyword — задать / снять произвольный кастомный IMAP-ключ (например, цветные метки $cl_1..$cl_10 в Open-Xchange).
• imap_delete_email — удалить письмо.
• imap_move_email — переместить письмо (или массив UID) между папками, при необходимости создав целевую папку.
• imap_find_thread_messages — найти письма из тех же переписок в другой папке (по заголовкам In-Reply-To / References).
• imap_download_attachment — скачать вложение (inline-картинки, извлечение текста из PDF).
• imap_bulk_delete — массовое удаление с чанкингом и автопереподключением.
• imap_bulk_delete_by_search — найти письма по критериям и удалить все. Требует хотя бы один конкретный критерий, чтобы случайно не вычистить всю папку; есть dryRun.

Отправка

• imap_send_email — отправить письмо с вложениями и inline-картинками через SMTP.
• imap_save_draft — сохранить черновик.
• imap_reply_to_email — ответить на письмо (в т.ч. replyAll).
• imap_forward_email — переслать письмо.

После отправки копия сохраняется в папку «Отправленные» (через sentFolder → флаг \Sent → список локализованных имён). Если аккаунту задан defaultBcc, он применяется к каждой отправке, ответу, пересылке и черновику.

Папки

• imap_list_folders — список папок с атрибутами и ролью specialUse (RFC 6154).
• imap_folder_status — статистика папки: всего/новых/непрочитанных, флаги, кастомные ключевые слова.
• imap_create_folder — создать папку (в т.ч. вложенные пути).
• imap_get_unread_count — число непрочитанных.

Безопасность

• Учётные данные шифруются AES-256-CBC, ключ хранится отдельно в ~/.imap-mcp/.key.
• Каталог хранилища, ключ и accounts.json записываются с правами владельца (0700/0600).
• Веб-мастер никогда не возвращает сохранённые пароли в браузер.
• Скачиваемые вложения ограничены каталогом загрузок — имена файлов от отправителя не могут выйти за его пределы.

Известная проблема: получатели в виде ["a@x.com","b@y.com"]

to, cc, bcc и uid принимают и одиночное значение, и массив. Некоторые MCP-клиенты отбрасывают anyOf из схемы, поле выглядит строковым, и модель сериализует массив в строку. Сервер теперь детектирует строковый массив и восстанавливает его при валидации и перед отправкой, логируя предупреждение. Если хотите обойти поведение клиента — передавайте получателей одной строкой через запятую: "Alice <alice@example.com>, Bob <bob@example.org>".

SMTP и типовые настройки

SMTP-настройки подставляются автоматически по IMAP-провайдеру. Типовые значения: Gmail — imap.gmail.com:993 (нужен пароль приложения); Outlook — outlook.office365.com:993; Yahoo — imap.mail.yahoo.com:993 (нужен пароль приложения).

Проект распространяется по лицензии MIT.