📬 yandex-mail-mcp (Docker / Cloud.ru Edition)

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

Об этом проекте

Этот репозиторий основан на проекте yandex-mail-mcp от dreamcatchered. Огромная благодарность автору за проделанную работу: логику работы с IMAP/SMTP, OAuth 2.1 и сами MCP-инструменты.

В этой версии код (app.py) адаптирован для развертывания в контейнерах Docker и на облачной платформе Cloud.ru (AI Factory / AI Agents). Добавлены поддержка переменных окружения, логирование в стандартный вывод (stdout) для облачных сред и настройка сетевого интерфейса 0.0.0.0.

✨ Что внутри

Related MCP server: yamail-mcp

📋 Требования

• Python 3.11+ — для локального запуска без Docker.

• Docker — для запуска в контейнере.

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

• Пароль приложения, созданный в настройках Яндекс ID.

🚀 Установка и запуск (Docker)

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

1. Перейдите в настройки паролей приложений Яндекс ID.

2. Нажмите «Создать пароль приложения», например для MCP-Server.

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

4. Убедитесь, что IMAP включён: Яндекс Почта → Настройки → Доступ по IMAP.

2. Клонирование репозитория

Склонируйте репозиторий на свой компьютер:

git clone https://github.com/mariakornet/yandex-mail-mcp.git
cd yandex-mail-mcp

сли у вас не установлен Git, вы можете скачать проект как ZIP-архив: нажмите зеленую кнопку Code на странице репозитория и выберите Download ZIP.

3. Сборка Docker-образа

Выполните команду в корне проекта:

docker build -t yandex-mail-mcp:local .

4. Запуск контейнера

Создайте файл .env в корне проекта или передайте переменные через параметр -e:

YANDEX_EMAIL=your-mailbox@yandex.ru
YANDEX_APP_PASSWORD=пароль-из-шага-1
ACCESS_CODE=любой-длинный-случайный-код
HOST=0.0.0.0
PORT=5180

Запустите контейнер:

docker run -d -p 5180:5180 --env-file .env --name yandex-mail-mcp yandex-mail-mcp:local

5. Проверка работоспособности

curl http://localhost:5180/healthz

Ожидаемый ответ содержит поле "status": "ok" и время работы сервера в uptime_s. Например:

{
  "status": "ok",
  "uptime_s": 42
}

☁️ Развертывание в Cloud.ru

Подробная документация Cloud.ru:

• Создание MCP-сервера.

• Работа с Artifact Registry.

1. Загрузка образа в Artifact Registry

В примере используется реестр yandex-mcp.cr.cloud.ru. Замените его адрес и значения <Key_ID> и <Key_Secret> на свои:

docker login yandex-mcp.cr.cloud.ru -u <Key_ID> -p <Key_Secret>
docker tag yandex-mail-mcp:local yandex-mcp.cr.cloud.ru/yandex-mail-mcp:v1
docker push yandex-mcp.cr.cloud.ru/yandex-mail-mcp:v1

2. Создание MCP-сервера

1. Перейдите в AI Factory → AI Agents → MCP-серверы.

2. Нажмите «Создать MCP-сервер» и выберите способ Artifact Registry.

3. Укажите порт 5180 и добавьте переменные окружения:

   • YANDEX_EMAIL;

   • YANDEX_APP_PASSWORD;

   • ACCESS_CODE.

4. Дождитесь статуса «Запущен».

5. Проверьте работу на вкладке «Тестирование».

Примечание: если тестирование через интерфейс нестабильно, проверьте логи сервера. Успешные запросы имеют код 200, ошибки авторизации — 401.

🛠️ Инструменты

Идентификатор письма — строка вида папка|uid, например INBOX|41703.

Папки можно называть по-русски или по-английски.

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

⚠️ Важно

В текущей версии для тестирования в Cloud.ru авторизация может быть отключена: функция is_authenticated возвращает True.

Перед промышленной эксплуатацией включите строгую проверку токена.

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

Особенности, отмеченные автором оригинального проекта:

• Кодировка папок. Имена папок используют modified UTF-7. Реализованы декодер и кодер по RFC 3501.

• Поиск по кириллице. Требуется CHARSET UTF-8. Без него команда SEARCH возвращает NO.

• Повторное использование соединения. IMAP-соединение переиспользуется, что сокращает задержки при подключении к Яндексу.

📄 Лицензия

Проект распространяется под лицензией MIT. Вы можете свободно использовать и дорабатывать код в соответствии с условиями лицензии.

Оригинальный проект: dreamcatchered/yandex-mail-mcp.