Mail.ru MCP starter — почта в ChatGPT

Персональный MCP-сервер на Python: подключает один ящик Mail.ru к ChatGPT через Google OAuth и работает с почтой по IMAP. Развёртывается на собственном сервисе Render; у каждого пользователя — свои учётные данные и свой сервер.

Главный шаг: создайте специальный пароль для внешнего приложения Mail.ru. Обычный пароль от ящика не работает. Выберите «Полный доступ к Почте» и сохраните полученный пароль только в MAILRU_APP_PASSWORD в Environment своего сервиса. Официальная инструкция Mail.ru.

Что умеет

Отправки, очистки корзины и безвозвратного удаления нет. Для восстановления используйте mail_move из корзины обратно в нужную папку. При чтении используются EXAMINE/BODY.PEEK, при перемещении — UID MOVE; общий EXPUNGE не вызывается.

Related MCP server: mcp4mail

Как повторить

1. Сделайте Fork этого репозитория.

2. Разрешите IMAP и создайте пароль внешнего приложения в Mail.ru.

3. Разверните Python Web Service на Render Free из своего Fork.

4. Создайте Google OAuth Client типа Web application с callback вашего сервиса.

5. Заполните секреты и разрешённый Google-аккаунт в Render Environment.

6. В ChatGPT → Plugins → «+» → Add custom MCP server добавьте https://YOUR-SERVICE.onrender.com/mcp, выберите OAuth/DCR и scope mail.access.

7. Войдите через Google и подтвердите перечисленные операции. Проверьте поиск, чтение, перемещение в корзину и восстановление на специально подготовленном письме.

Пошаговая инструкция: docs/SETUP_RU.md. В ней есть точные переменные, команды, контрольные результаты и разбор ошибок.

Схема

flowchart TD
    ChatGPT["ChatGPT"] -->|"OAuth + MCP / HTTPS"| Server["Ваш сервер на Render"]
    Server -->|"IMAP / TLS :993"| Mail["Ваш ящик Mail.ru"]
    Server <-->|"openid email: проверка владельца"| Google["Google OAuth"]

Google используется для входа в MCP, а не для доступа к Gmail. Ящик Mail.ru может иметь другой адрес. Запросы чтения передают выбранные заголовки и тексты писем в ChatGPT; сервер обрабатывает их в памяти. Картинки и ссылки из писем не загружаются.

Права без сюрпризов

Все пять команд используют один scope mail.access. Страница согласия заранее перечисляет чтение, перемещение и удаление в корзину. Это собственный scope данного сервера, а не разрешение Google или Mail.ru. Автоматического повышения старых read-only токенов в публичном шаблоне нет.

Разрешён только подтверждённый Google email из ALLOWED_GOOGLE_EMAIL. Токены проверяются по подписи, issuer, audience, сроку и scope. Письма — недоверенные данные: их текст не является поручением пользователю или агенту. Подробнее: SECURITY.md.

Переменные

Незаполненный пример: .env.example. Настоящие значения не добавляйте в Git, issue, скриншот или чат.

Тесты

python -m venv .venv
# Linux / macOS:
source .venv/bin/activate
# Windows PowerShell: .venv\Scripts\Activate.ps1
python -m pip install -r requirements-dev.txt
python -m pytest tests -q
python scripts/check_public.py

В публичной адаптации локально пройдены 47 тестов: авторизация, PKCE, callbacks, scope, UIDVALIDITY, IMAP-инъекции, MOVE, корзина и обрыв соединения. Тесты используют подмену IMAP и Google, не читают и не изменяют настоящий ящик. CI повторяет их при push/PR.

Что уже проверено и где границы

Исходная персональная интеграция проверена на реальном Mail.ru: поиск, чтение, перемещение выбранного письма в корзину с проверкой обеих папок. Этот публичный вариант очищен от персональных настроек и имеет другую, единую модель scope. Новое развёртывание из Fork требует собственной проверки по инструкции; 47 тестов не подменяют живую проверку Google/ChatGPT/Mail.ru.

Render Free засыпает после 15 минут простоя, пробуждение занимает около минуты. Данные на локальном диске сервиса не сохраняются. Здесь нет постоянной БД: незавершённую OAuth-сессию после перезапуска нужно начать заново. Это пример для одного владельца, не готовый многопользовательский почтовый сервис. Ограничения Render.

Файлы и лицензия

server.py — MCP и защита endpoint; mailbox_client.py — IMAP; oauth.py — персональный OAuth-сервер; render.yaml — Blueprint; docs/ — инструкция и разбор опыта; tests/ — проверки.

Сохранена выбранная владельцем лицензия репозитория MPL-2.0. Перенесённые и адаптированные файлы исходной реализации (server.py, oauth.py, mailbox_client.py, tests/, requirements.txt, render.yaml, .gitignore) сохраняют Apache-2.0; её текст — LICENSE-APACHE-2.0. Новые инструкции, примеры, CI и скрипт проверки относятся к MPL-2.0. Подробности — NOTICE. Независимый пример, не официальный продукт Mail.ru, Google, OpenAI или Render.