Mail Notification MCP

An MCP server that sends engineering progress and human approval emails via SMTP. It uses the standard stdio transport and is suitable for invocation by MCP clients such as Codex, Claude Desktop, Cursor, VS Code, and others.

Provided tools

• send_progress_update: Send a project progress, completion, or blocked update report.

• request_human_approval: Send an item requiring human approval or rejection, and generate an approval number.

• send_simple_email: Send a plain-text or HTML email.

• send_custom_email: Send a custom email with CC/BCC and attachments.

• test_smtp_connection: Test SMTP connection and authentication.

• test_imap_connection: Test IMAP connection and authentication.

• read_replies: Read the latest replies in the inbox; by default they are not marked as read.

• check_approval_status: Determine whether an approval number is "approved", "rejected", or "pending".

• wait_for_approval: Poll and wait for a human reply until approved, rejected, or timeout.

The default recipient for the progress tool comes from config.json; approval emails explicitly ask for an "Approve" or "Reject" reply. Other engineering teams only need to call the MCP tools and do not need to implement SMTP themselves.

Related MCP server: mcp-email-server

1. Configure SMTP and the target mailbox

Edit config.json in the project root (template: 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": "我的工程"
  }
}

It is recommended to put the password in an environment variable rather than writing it directly into the file:

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

You can also fill in smtp.password directly. config.json is ignored by .gitignore and should not be committed to the repository.

Common SMTP settings:

Gmail, QQ Mail, etc. usually require SMTP to be enabled and an app-specific password to be used; when the regular web login password cannot be used directly, generate an authorization code/app password as required by the mailbox provider.

IMAP is used to read replies. QQ Mail typically uses imap.qq.com:993 with SSL; if imap.password is omitted, the program reuses the SMTP password/authorization code. Environment variables override config.json, and you can also use IMAP_HOST, IMAP_PORT, IMAP_SECURE, IMAP_USER, IMAP_PASS, and NOTIFY_TO.

2. Install and test

Requires Python 3.11+ and uv. Run in PowerShell:

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

The stdio mode of MCP should not be typed into manually; it should be launched by an MCP client. We recommend first calling test_smtp_connection and test_imap_connection.

3. Integrate with other engineering projects

Using a client that supports the mcpServers format as an example, merge the following server entry into the client configuration. Windows paths must use double backslashes:

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

If uv is not on the client's PATH, replace command with the absolute path of uv.exe. Restart the client after modifying the MCP configuration.

Invocation examples

Progress report:

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

Human approval:

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

The tools support an optional to parameter as a one-time recipient override; when omitted, notification.to in config.json is used.

Read replies:

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

Approval confirmation:

调用 check_approval_status：
approval_id="APR-ABC1234567"

The approval tools return approved, rejected, pending, or timeout. By default, they only read the INBOX and do not automatically modify the read/unread state of messages.

Security notes

• Prefer app-specific passwords or authorization codes; do not use the primary mailbox password.

• Do not commit real passwords or real target mailbox configuration to Git.

• Local stdio is used by default; HTTP mode binds only to 127.0.0.1.