Mail Notification MCP

一个通过 SMTP 发送工程进展和人工审批邮件的 MCP Server。它使用标准 stdio transport，适合被 Codex、Claude Desktop、Cursor、VS Code 等 MCP 客户端调用。

提供的工具

• 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

MCP 的 stdio 模式不要手工输入普通文字；应由 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 参数做单次收件人覆盖；省略时使用 config.json 中 notification.to。

读取回复：

调用 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。