📬 yandex-mail-mcp

Научите вашего ИИ-агента работать с вашей почтой.

Обычный ChatGPT ничего не знает о вашей почте: не видит входящие, не найдёт письмо от бухгалтерии, не ответит и не отправит. И добраться до почты через промпт не выйдет — у модели нет инструмента, который её открывает.

Этот проект даёт ChatGPT такой инструмент. Он подключается как коннектор, один раз спрашивает код доступа — и дальше вы просто пишете в чате обычные слова: «что нового в почте», «найди письма от Иванова за сентябрь», «ответь, что всё оплачено».

Как я к этому пришёл. Кастомные MCP для обычного ChatGPT я открыл для себя относительно недавно — в том самом чате, которым пользуюсь каждый день. Первым был коннектор для «Пятёрочки», и я быстро понял, насколько это удобно: не надо копировать промпты, не надо заводить отдельного агента — просто включил коннектор в настройках и спрашиваешь обычными словами. Этот проект — второй такой коннектор. Первый научил ИИ ходить в магазин, второй учит его читать вашу почту.

✨ Что внутри

                  HTTPS
ChatGPT ──────────────────────────────┐
   │ OAuth 2.1 │                       ▼
   │◀─JSON-RPC─┼──────▶  reverse proxy (nginx / Caddy / …)
   │           │                       │ http
   │           │                       ▼
   └───────────┘         127.0.0.1:5180  yandex-mail-mcp
                                    │ IMAP / SMTP
                                    ▼
                         imap.yandex.ru / smtp.yandex.ru

Related MCP server: mcp-imap

📋 Содержание

• Что умеет

• Требования

• Установка

• Подключение к ChatGPT

• Инструменты

• Примеры запросов

• Тесты

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

• Важно про Яндекс OAuth

• Особенности реализации

• Обслуживание

• Связанные проекты

🎯 Что умеет

Чтение и поиск по всем папкам (входящие, отправленные, черновики, корзина, спам, архив) с поддержкой кириллицы, чтение писем с вложениями, отправка, ответ с сохранением цепочки, пересылка, черновики, перемещение, метки прочитано/важное/звезда, удаление. Плюс пара инструментов search/fetch — обёртка, без которой коннектор не работает в Deep Research.

📋 Требования

• Linux-сервер с Python 3.11+ (проверено на 3.12) и выходом в интернет

• Домен с валидным TLS-сертификатом: его видит ChatGPT, поэтому самоподписанный не подойдёт

• Аккаунт Яндекс Почты с включённым IMAP

Зависимости: только Flask. IMAP, SMTP, криптография и разбор MIME — из стандартной библиотеки.

🚀 Установка

1. Пароль приложения в Яндексе

У Яндекса нет OAuth-скоупа для почты (подробности ниже), поэтому единственный способ — пароль приложения:

1. Открыть https://id.yandex.ru/security/apppasswords

2. «Создать пароль приложения», назвать как угодно

3. Скопировать выданный пароль

4. Отдельно убедиться, что IMAP включён: mail.yandex.ru → Настройки → «Доступ по IMAP»

Пароль приложения не заменяет основной пароль и не даёт доступа к веб-интерфейсу. Отзывается там же.

2. Файлы и конфиг

sudo mkdir -p /opt/yandex-mail-mcp
sudo cp app.py mail.py oauth.py /opt/yandex-mail-mcp/
sudo cp config.example.json /opt/yandex-mail-mcp/config.json
sudo pip3 install 'Flask>=3.0,<4'

Заполнить /opt/yandex-mail-mcp/config.json:

{
  "access_code": "любой-длинный-случайный-код",
  "port": 5180,
  "public_url": "https://yandex-mail-mcp.example.com",
  "address": "your-mailbox@yandex.ru",
  "app_password": "пароль-из-шага-1",
  "imap_host": "imap.yandex.ru",
  "imap_port": 993,
  "smtp_host": "smtp.yandex.ru",
  "smtp_port": 465,
  "oauth_clients": []
}

access_code — код, который вводится на экране согласия при подключении ChatGPT. Сгенерировать можно так:

python3 -c "import secrets; print(secrets.token_urlsafe(24))"

Дальше — chmod 600 /opt/yandex-mail-mcp/config.json.

3. Автозапуск

sudo cp yandex-mail-mcp.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now yandex-mail-mcp
curl -s http://127.0.0.1:5180/healthz

4. Доступ снаружи

ChatGPT обращается к коннектору по обычному HTTPS, поэтому перед публикацией нужен домен с валидным сертификатом — Let's Encrypt или коммерческий.

Сам сервис слушает только 127.0.0.1:5180 и наружу не выходит, так что любой реверс-прокси подойдёт: nginx, Caddy, Traefik. Например, за nginx:

server {
    listen 443 ssl;
    http2 on;
    server_name mail.example.com;

    ssl_certificate     /etc/letsencrypt/live/mail.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/mail.example.com/privkey.pem;

    client_max_body_size 2m;

    location / {
        proxy_pass http://127.0.0.1:5180;
        proxy_http_version 1.1;
        proxy_set_header Host              $host;
        proxy_set_header X-Real-IP         $remote_addr;
        proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_read_timeout 120s;
    }
}

Почему так: сервис никогда не выходит в интернет сам и не занимает порт — это значит, что его нельзя случайно обнаружить сканированием, а доступ контролируется правилами прокси. Порт 443 на сервере при этом остаётся свободным для других служб.

🔗 Подключение к ChatGPT

1. Включить Developer Mode: https://platform.openai.com/docs/guides/developer-mode

2. ChatGPT → Settings → Connectors → Create

3. Заполнить:

   • Name — например, «Яндекс Почта»

   • URL — https://yandex-mail-mcp.example.com/mcp

   • Auth — OAuth

4. В чате: «+» или @ → выбрать коннектор → Sign in

5. Откроется экран согласия — ввести access_code из конфига

6. Вернуться в ChatGPT, коннектор подключён

Сразу после подключения стоит зайти в Settings → Plugins → приложение → Permissions и выбрать «Всегда спрашивать»: коннектор умеет отправлять письма твоим именем, и по умолчанию лучше подтверждать каждое действие.

🧰 Инструменты

Идентификатор письма — строка вида папка|uid, например INBOX|41703. Её возвращает search_emails и её же нужно передавать обратно в остальные инструменты; после перемещения письма идентификатор меняется, поэтому устаревший id даёт понятную ошибку, а не молчаливый «успех».

Папки можно называть по-русски или по-английски: INBOX/«Входящие», Sent/«Отправленные», Drafts/«Черновики», Trash/«Корзина», Junk/«Спам», Archive/«Архив».

💬 Примеры запросов

• «Что нового в почте?»

• «Найди непрочитанные от hr@company.ru за последнюю неделю»

• «Что в последнем письме от банка?»

• «Подготовь ответ: подтверждаю, спасибо» — создаст черновик, не отправляя

• «Отправь письмо vasya@mail.ru с текстом…»

• «Перешли последнее письмо о счёте в бухгалтерию»

• «Перемести все рассылки от рекламы в Корзину»

🧪 Тесты

Два независимых теста. Токен в обоих — из переменной окружения, в коде его нет.

# протокол: OAuth-цикл, PKCE, 401/WWW-Authenticate, tools/list, кэш и ротация
# токенов, revoke. Почту не трогает.
YCP_TOKEN=<код> python selftest.py https://yandex-mail-mcp.example.com

# боевая проверка на живом ящике. По умолчанию только чтение.
YCP_TOKEN=<код> python live_check.py https://yandex-mail-mcp.example.com

# добавить проверку записи (создаёт черновик и письмо самому себе)
YCP_TOKEN=<код> YCP_ADDRESS=your-mailbox@yandex.ru \
  python live_check.py https://yandex-mail-mcp.example.com --write

selftest.py — 61 проверка, закрывает весь OAuth-цикл, который повторит ChatGPT, включая негативные случаи.

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

Про выданные токены: /oauth/sessions по тому же access_code показывает счётчик активных токенов. Токен можно отозвать через /oauth/revoke или удалив oauth.json и перезапустив сервис.

Если доступ идёт через CDN или WAF, проверь, что он не режет небраузерные запросы: ChatGPT ходит с бот-агентом, и часть защит отсекает такие запросы по User-Agent. Лечится исключением для адреса коннектора.

⚠️ Важно про Яндекс OAuth

Часто встречается совет «сделать OAuth 2.1 с обменом токенов по RFC 8693, чтобы ИИ ходил в почту по токену Яндекса». Это невозможно, и вот почему:

• Яндекс OAuth поддерживает ровно два grant_type: authorization_code и refresh_token. Обмен токенов (RFC 8693) не реализован.

• Скоупа mail:imap / mail:smtp у Yandex ID не существует вообще. Есть login:* и API отдельных сервисов (Диск, Календарь, Переводчик). Поэтому XOAUTH2 для личной Яндекс Почты невозможен в принципе.

Следствие: сервер не хранит и не проксирует токен Яндекса. Он хранит пароль приложения и работает по IMAP/SMTP. Свой OAuth 2.1 нужен только для того, чтобы сам ChatGPT мог подключиться к этому серверу, — и это единственная роль, которую он здесь играет.

Сервисные приложения Яндекс 360 (для организаций с собственным доменом) — отдельная история, они требуют прав администратора организации.

🧠 Особенности реализации

Три места, где пришлось повозиться, и почему так:

Имена папок приходят в modified-UTF7. Яндекс отдаёт &BBAEQARFBDgEMg- вместо «Архив». Реализован декодер/кодер по RFC 3501. На провод уходит исходная форма, человеку — читаемая.

Поиск по кириллице требует CHARSET UTF-8. Без него SEARCH отвечает NO вместо результата — молча, без ошибки. Критерий с не-ASCII автоматически отправляется с CHARSET UTF-8.

IMAP-соединение переиспользуется. Яндекс отвечает на приветствие нового соединения с задержкой, которая после серии частых подключений доходит до 30 секунд. Все команды после LOGIN при этом выполняются за миллисекунды. Поэтому держится одно соединение, а папка выбирается повторно только при смене. Первый вызов после запуска может быть медленным, дальше — доли секунды.

🛠 Обслуживание

systemctl status yandex-mail-mcp
journalctl -u yandex-mail-mcp -f
tail -f /opt/yandex-mail-mcp/yandex-mail-mcp.log     # лог приложения
systemctl restart yandex-mail-mcp

Логи: yandex-mail-mcp.log с ротацией, 1 МБ × 2. Ошибки почты возвращаются клиенту как isError с понятным текстом, а не как HTTP 500.

Если сменишь пароль приложения — поправь config.json и перезапусти сервис.

🔗 Связанные проекты

Другие MCP-коннекторы для тех же ИИ-агентов:

• 🛒 pyaterochka-mcp-tool — MCP-сервер и AI-бот для каталога «Пятёрочки»: магазины, товары, акции и цены по всей России. Первый коннектор, с которого всё началось.

📄 Лицензия

MIT — можно использовать и дорабатывать свободно.