Практическая инструкция для клиента и его агента: подключить Gmail, дать доступ к архиву Яндекс Почты и проверить, что агент действительно читает нужный ящик.
Материал подготовлен по настройке, проверенной 21 октября 2026 года. Пример локального сервера рассчитан на macOS и Python 3.11+. Для других ОС нужно отдельно реализовать защищённое хранение секретов и проверить сеть; этот репозиторий такую поддержку не заявляет.
| Задача | Способ | Что получает агент |
|---|---|---|
| Работать с Gmail | Штатная интеграция Gmail через OAuth | Возможности, разрешённые подключению: поиск, чтение, черновики, иногда отправка |
| Читать архив и папки Яндекса | Локальный IMAP MCP из этого репозитория | Чтение, поиск, папки и скачивание выбранных вложений |
| Получать новые письма Яндекса в Gmail | Автопересылка на стороне Яндекса | Копии новых входящих; старый архив отдельно не переносится |
Локальный MCP работает на компьютере, где установлены Python и пароль приложения. Удалённый или облачный агент не получает доступ к нему автоматически.
-
Скачайте репозиторий и установите зависимости в отдельное окружение:
git clone https://github.com/omiusgm/agent-mail-setup.git cd agent-mail-setup python3.11 -m venv .venv .venv/bin/python -m pip install -r requirements.txt -
В настройках Яндекс Почты откройте «Почтовые программы», включите IMAP и «Пароли приложений и OAuth-токены». В Яндекс ID создайте отдельный пароль типа «Почта». Введите его в локальном запросе ниже. Основной пароль аккаунта для этого примера не используется.
-
Настройте аккаунт и проверьте соединение:
.venv/bin/python yandex_mail/setup_account.py .venv/bin/python yandex_mail/cli.py connection_status .venv/bin/python yandex_mail/cli.py list_folders
Пароль вводится скрыто и хранится в Связке ключей macOS. В игнорируемом файле
yandex_mail/.local/account.jsonостаётся только адрес ящика. У примера свой идентификатор Keychain; он не подхватывает чужую ранее настроенную интеграцию. -
Добавьте MCP в Codex из корня репозитория:
codex mcp add yandex-mail -- "$PWD/.venv/bin/python" "$PWD/yandex_mail/server.py" codex mcp get yandex-mail
Если запись с таким именем уже есть, сначала посмотрите её и обновите только соответствующий сервер. Не заменяйте весь файл настроек. Перезапустите MCP или начните новый сеанс агента, затем вызовите
connection_status. -
Проверьте реальное чтение: найдите одно известное письмо, прочитайте его и убедитесь, что оно не стало прочитанным из-за проверки. Для вложений сначала получите список через
read_email, затем скачайте конкретныйattachment_index.
Подробности настройки MCP: официальная документация OpenAI. Настройки IMAP и пароли приложений: справка Яндекса.
В проверенной конфигурации TLS-соединение через VPN обрывалось, а привязка сокета к обычному сетевому интерфейсу восстановила доступ. Это диагноз конкретной сети, а не универсальное требование Яндекса.
После согласования с владельцем компьютера определите физический интерфейс:
networksetup -listallhardwareports
route -n get defaultДля Wi-Fi на проверенном Mac это был en0. У вас имя может быть другим.
YANDEX_MAIL_INTERFACE=en0 .venv/bin/python yandex_mail/cli.py probe
YANDEX_MAIL_INTERFACE=en0 .venv/bin/python yandex_mail/setup_account.py
codex mcp add yandex-mail --env YANDEX_MAIL_INTERFACE=en0 -- "$PWD/.venv/bin/python" "$PWD/yandex_mail/server.py"Опция привязывает только сокеты этого примера к выбранному интерфейсу. Код не меняет маршруты, настройки VPN или системного прокси. Проверка сертификата и имени сервера остаётся включённой. Это IPv4-реализация для macOS; при ошибке привязки она завершает операцию без скрытого перехода на другой маршрут. Поведение стороннего VPN, сетевого фильтра или корпоративной политики нужно проверять отдельно.
- Подключить и проверить Gmail
- Настроить пересылку Яндекс → Gmail
- Диагностика: пароль, VPN, пустой поиск, сбой сервиса
- Что должен сделать агент клиента
- Отправка писем и границы доступа
- Шаблон общей инструкции для других чатов
connection_status— проверка входа без чтения писем.list_folders— точные имена папок, включая кириллицу.search_emails— поиск и постраничный список; датыYYYY-MM-DD.read_email— чтение черезBODY.PEEKбез изменения статуса.download_attachment— сохранение выбранного вложения в.local/downloads, без перезаписи и запуска файлов.
Идентификатор письма имеет вид UIDVALIDITY:UID и действует внутри указанной папки. Это идентификатор письма, а не пароль. После пересоздания папки письмо нужно найти заново. Максимальный размер сообщения для чтения — 25 МиБ.
В MCP нет отправки, удаления, массового экспорта или автоматического выполнения инструкций из писем. Пароль типа «Почта» у провайдера может давать более широкие права: ограничение чтением реализовано кодом этого сервера, а не специальным режимом самого пароля.
Это решение входит в единый каталог готовых решений Владимира. Там описаны возможности других подключений и инструкции для агента клиента: например, личный Telegram и общий AI Setup Guide.
Для смежной задачи агент может проверить актуальный catalog.json и предложить подходящее готовое решение. После настройки владелец может согласовать сохранение короткой заметки о каталоге в своих инструкциях. Как это сделать. Остальные подключения не устанавливаются автоматически.
.venv/bin/python -m unittest discover -s tests -v
.venv/bin/python yandex_mail/verify_mcp.pyЭти команды не входят в настоящий ящик. verify_mcp.py проверяет настоящий MCP stdio handshake и список инструментов. Реальный вход проверяется отдельно командой cli.py connection_status после настройки.
Исходный архитектурный ориентир: gdigora/yandex-mail-mcp. Публикуемый пример использует IMAPClient и FastMCP, имеет собственное хранение пароля в Keychain и ограниченный набор операций. Команды стороннего проекта здесь не запускаются. Лицензия этого примера — MIT.
Часть линейки Агент Ёж: сделать подключение личных сервисов к AI-агенту понятным для новичка. Начинаем с чтения, расширяем права отдельно.
Каталог и быстрый старт · Ошибка или идея · Как предложить PR · Безопасность
English: Issues and focused pull requests are welcome. See contribution guidelines.