Mail Notification MCP

MCP-сервер, который отправляет по SMTP письма с обновлениями хода работ и запросами ручного утверждения. Он использует стандартный транспорт stdio и подходит для вызова из MCP-клиентов, таких как Codex, Claude Desktop, Cursor, VS Code и других.

Предоставляемые инструменты

• send_progress_update — отправляет отчёт о ходе выполнения проекта, его завершении или блокировке.

• request_human_approval — отправляет запрос на ручное одобрение или отклонение с генерацией номера утверждения.

• send_simple_email — отправляет простое письмо в виде обычного текста или HTML.

• send_custom_email — отправляет настраиваемое письмо с копиями CC/BCC и вложениями.

• test_smtp_connection — проверяет подключение к SMTP и аутентификацию.

• test_imap_connection — проверяет подключение к IMAP и аутентификацию.

• read_replies — читает последние ответы из входящих, по умолчанию не помечая их прочитанными.

• check_approval_status — определяет по номеру утверждения статус «одобрено», «отклонено» или «в ожидании».

• wait_for_approval — опрашивает сервер, ожидая ручного ответа до одобрения, отклонения или тайм-ая.

Получатели по умолчанию для инструментов отчётов берутся из config.json; письма на утверждение явно требуют ответа «одобрено» или «отклонено». Другим проектам достаточно вызывать MCP-инструменты, не нужно реализовывать SMTP самостоятельно.

Related MCP server: mcp-email-server

1. Настройка SMTP и целевого почтового ящика

Отредактируйте config.json в корне проекта (шаблон — config.example.json):

{
  "smtp": {
    "host": "smtp.gmail.com",
    "port": 587,
    "secure": false,
    "username": "你的发件邮箱@gmail.com",
    "password": "",
    "password_env": "MAIL_SMTP_PASSWORD",
    "from_email": "你的发件邮箱@gmail.com"
  },
  "imap": {
    "host": "imap.gmail.com",
    "port": 993,
    "secure": true,
    "username": "你的发件邮箱@gmail.com",
    "password": "",
    "password_env": "MAIL_SMTP_PASSWORD"
  },
  "notification": {
    "to": "目标收件邮箱@example.com",
    "subject_prefix": "[工程通知]",
    "project_name": "我的工程"
  }
}

Рекомендуется хранить пароль в переменных окружения, а не записывать его напрямую в файл:

$env:MAIL_SMTP_PASSWORD = "你的邮箱应用专用密码"

Можно также указать smtp.password напрямую. Файл config.json уже добавлен в .gitignore и не должен попадать в репозиторий.

Распространённые настройки SMTP:

Для Gmail, QQ и других сервисам обычно требуется включить SMTP и использовать пароль приложения. Если напрямую использовать пароль от веб-входа нельзя, создайте код авторизации или такой пароль по требованию вашего почтового провайдера.

IMAP используется для чтения ответов. Для почты QQ обычно используется imap.qq.com:993 + SSL; если imap.password не указан, используется SMTP-пароль/авторизационный код. Переменные окружения переопределяют значение из config.json; также можно использовать IMAP_HOST, IMAP_PORT, IMAP_SECURE, IMAP_USER, IMAP_PASS и NOTIFY_TO.

2. Установка и проверка

Требуются Python 3.11+ и uv. Запустите в PowerShell:

cd C:\AI_Tools\Mail
uv sync --extra dev
uv run pytest
uv run python -m email_mcp_server.server

В stdio-режиме MCP не вводите обычный текст вручную — его должен запускать MCP-клиент. Сначала рекомендуется вызвать test_smtp_connection и test_imap_connection.

3. Подключение к другим проектам

Например, для клиента, поддерживающего формат mcpServers, объедините следующие записи серверов в конфигурации клиента. В Windows пути должны использовать двойную обратную косую черту:

{
  "mcpServers": {
    "mail-notification": {
      "command": "uv",
      "args": [
        "--directory",
        "C:\\AI_Tools\\Mail",
        "run",
        "python",
        "-m",
        "email_mcp_server.server"
      ]
    }
  }
}

Если uv нет в PATH клиента, замените command на абсолютный путь к uv.exe. После изменения конфигурации MCP перезапустите клиент.

Примеры вызова

Отчёт о ходе работ:

调用 send_progress_update：
project="订单系统"
status="进行中"
summary="已完成数据库迁移脚本，并通过本地测试"
details="迁移了 12 张表，新增回滚检查"
next_steps="部署到测试环境并等待接口联调"

Ручное утверждение:

调用 request_human_approval：
project="订单系统"
title="是否允许部署到生产环境"
request="请批准今晚 22:00 执行生产部署"
reason="测试环境已通过，预计需要 15 分钟，期间会短暂重启服务"
options="批准部署 / 延后到明天"
deadline="今天 21:30 前"

Инструменты поддерживают необязательный параметр to для переопределения получателя в одном вызове; если он опущен, используется notification.to из config.json.

Чтение ответов:

调用 read_replies：
from_address="target@example.com"
subject_contains="Mail Notification MCP 测试邮件"
since_hours=72

Проверка статуса подтверждения:

调用 check_approval_status：
approval_id="APR-ABC1234567"

Инструменты утверждения возвращают статус approved, rejected, pending или timeout. По умолчанию читается только INBOX, статус прочтения писем автоматически не меняется.

Замечания по безопасности

• Прежде всего используйте специальные пароли приложений или коды авторизации, не используйте основной пароль почты.

• Не коммитьте в Git реальные пароли и настройки с реальными адресами почты.

• По умолчанию используется локальный stdio; HTTP-режим привязывается только к 127.0.0.1.