email-mcp

Небольшой персональный MCP-сервер для одного почтового ящика через IMAP + SMTP.

В первую очередь он предназначен для частного использования:

• один почтовый ящик

• учетные данные передаются через переменные окружения

• чтение почты через IMAP

• отправка почты через SMTP

• хорошо работает с настройками Yandex Mail по умолчанию, но может быть настроен на любого IMAP/SMTP провайдера

Что я изменил

Изначально этот репозиторий работал только в режиме stdio. Это подходит для локальных MCP-клиентов, но для интеграции с веб-версией ChatGPT требуется HTTP MCP-эндпоинт. Теперь сервер поддерживает:

• stdio для локального использования/разработки

• streamable-http для использования с веб-приложением ChatGPT

• sse для совместимости

Я также исправил проблему с цепочками писем:

• старый параметр reply_to устанавливал только заголовок Reply-To

• для полноценных ответов обычно следует использовать In-Reply-To и References

• read_email теперь возвращает эти заголовки, чтобы их можно было передать обратно в send_email

И я улучшил вывод read_email, добавив:

• декодированные заголовки

• метаданные вложений

• заголовки цепочек сообщений

Related MCP server: IMAP/SMTP Email MCP Server

Поддержка вложений

Эта версия поддерживает как чтение, так и отправку вложений.

Загрузка вложения из полученного письма

1. Вызовите read_email(uid=..., folder="INBOX")

2. Проверьте список attachments

3. Используйте attachment_index с get_attachment(...)

get_attachment(...) возвращает:

• filename

• content_type

• size_bytes

• content_base64

Отправка вложений в исходящем письме

send_email(...) принимает список attachments.

Каждый элемент может быть одним из:

{"path": "/path/to/file.pdf"}

{"filename": "note.txt", "content_text": "hello from MCP"}

{"filename": "report.pdf", "content_base64": "JVBERi0x...", "content_type": "application/pdf"}

Поведение папки «Отправленные»

После успешной отправки через SMTP, то же самое MIME-сообщение добавляется в вашу папку отправленных писем IMAP.

По умолчанию это имя папки:

Sent

Вы можете переопределить его, если ваш почтовый ящик использует другое имя папки IMAP:

export SENT_FOLDER="Sent"
# or
export MAILBOX_SENT_FOLDER="Sent"

Если отправленные письма не отображаются, сначала запустите list_folders() и используйте точное имя папки, возвращенное вашим почтовым ящиком.

Файлы

• server.py — определения инструментов MCP и запуск транспорта

• mail_ops.py — реализация IMAP/SMTP

• requirements.txt — зависимости Python

Окружение

Обязательно:

export MAILBOX_EMAIL="you@example.com"
export MAILBOX_PASSWORD="your-app-password"

Дополнительные настройки провайдера:

export IMAP_HOST="imap.yandex.com"
export IMAP_PORT="993"
export SMTP_HOST="smtp.yandex.com"
export SMTP_PORT="465"

Дополнительная настройка папки отправленных:

export SENT_FOLDER="Sent"

Дополнительные настройки MCP-сервера:

export MCP_TRANSPORT="stdio"
export MCP_HOST="0.0.0.0"
export MCP_PORT="8000"

Для удобства также поддерживаются псевдонимы:

export YANDEX_EMAIL="you@yandex.ru"
export YANDEX_APP_PASSWORD="..."

Установка

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Запуск локально через stdio

python server.py

Это подходящий режим для локальных MCP-клиентов, которые запускают процесс напрямую.

Запуск для веб-приложения ChatGPT

Веб-версии ChatGPT нужен публичный HTTPS MCP-эндпоинт. Запустите сервер в режиме HTTP:

python server.py --transport streamable-http --host 0.0.0.0 --port 8000

Затем откройте этот порт через публичный HTTPS-туннель или обратный прокси-сервер и зарегистрируйте полученный URL MCP в ChatGPT.

Доступные инструменты

list_folders()

Выводит список доступных папок IMAP.

search_emails(folder="INBOX", text=None, unseen_only=False, since_date=None, limit=30)

Поиск сообщений по критериям IMAP.

Возвращает элементы, такие как:

• uid

• subject

• from

• to

• date

• flags

• size_bytes

read_email(uid, folder="INBOX")

Получает полное сообщение, не помечая его как прочитанное.

Возвращает:

• декодированные заголовки

• message_id

• in_reply_to

• references

• attachments

• body_plain

• body_html

get_attachment(uid, folder="INBOX", attachment_index=None, filename=None)

Получает одно вложение и возвращает его в формате base64.

send_email(...)

Отправляет сообщение через SMTP.

Важные параметры:

• reply_to_header — устанавливает заголовок Reply-To

• in_reply_to — заголовок цепочки

• references — заголовок цепочки

• attachments — необязательный список спецификаций вложений

Для полноценного ответа используйте in_reply_to и, как правило, также references.

Примечания по Yandex

Типичные настройки Yandex по умолчанию:

• IMAP: imap.yandex.com:993 через SSL/TLS

• SMTP: smtp.yandex.com:465 через SSL/TLS

Используйте пароль приложения, а не пароль от основной учетной записи.

Следующие разумные улучшения

• встроенные/вложенные изображения

• ограничения на размер вложений и потоковая передача

• инструменты перемещения/архивирования/удаления с подтверждением

• OAuth вместо учетных данных на основе переменных окружения

• тесты с имитацией бэкендов IMAP/SMTP