mcp-email-server

一个能收发邮件的 MCP 服务器。通过标准 IMAP 读信、标准 SMTP 发信，因此 Gmail、QQ、163、Outlook、企业自建邮箱都能接入，不依赖任何单一服务商的私有 API。

用 Python 编写，基于 MCP Python SDK v2。

它能做什么

读信

写信

管理与诊断

此外还提供资源 email://{文件夹}/{uid}（把某封邮件当作上下文附件挂进对话），以及提示词 draft_reply（带原文引用地起草回复）。

Related MCP server: IMAP/SMTP Email MCP Server

安装

需要 Python 3.10 及以上。

git clone <this-repo> && cd mcp-email-server
python3 -m venv .venv
.venv/bin/pip install -e .

配置

复制 .env.example 为 .env 并填写，或者直接用环境变量。

cp .env.example .env

最小可用配置：

IMAP_HOST=imap.qq.com
IMAP_USERNAME=you@qq.com
IMAP_PASSWORD=你的授权码
SMTP_HOST=smtp.qq.com
EMAIL_FROM=you@qq.com
EMAIL_ALLOW_SEND=true

填完先自检，不用启动客户端：

.venv/bin/mcp-email-server --check

它会分别连接 IMAP 与 SMTP 并报告结果，成功时退出码为 0。

各邮箱服务商参数

几个务必注意的点：

• 绝大多数服务商不接受登录密码。Gmail、QQ、163 都要求单独生成一串"授权码"或"应用专用密码"，填错了会得到一条含糊的登录失败信息。

• Microsoft 已停用个人 Outlook.com 与多数 M365 租户的基本认证（basic auth）。也就是说密码方式在那里多半已经行不通，需要 OAuth2 —— 本项目当前尚未实现完整的 OAuth2 授权流程（见下文"扩展 OAuth2"）。

• 163/126 需要 IMAP ID 命令，否则登录后每条命令都会被拒绝并返回 Unsafe Login。本服务器会在服务端声明支持时自动发送该命令，你不需要做任何事。

• SMTP_USERNAME / SMTP_PASSWORD 留空时自动复用 IMAP_* 的值，同一个账号不必填两遍。

安全开关

默认配置是保守的：装好之后只能读信，不能发信也不能删信。这是刻意的——模型可能误解意图，而发出去的邮件收不回来。

刚接入时强烈建议先把白名单设成你自己的地址，确认整条链路行为符合预期后再放开：

EMAIL_RECIPIENT_ALLOWLIST=me@example.com

白名单支持三种写法：完整地址 bob@example.com、域名 @example.com 或 example.com。匹配的是真实地址，不是显示名，所以 me@example.com <attacker@evil.com> 这类伪装会被拒绝。

关于 EMAIL_SAVE_SENT_COPY：Gmail 会在服务端自动保存通过 SMTP 发出的邮件，而 QQ、163 等大多数服务商不会——在那些邮箱上如果不打开这个开关，你发出去的信除了对方收件箱之外哪儿都不存在。

接入 Cursor

在项目里建 .cursor/mcp.json（或用户级 ~/.cursor/mcp.json）：

{
  "mcpServers": {
    "email": {
      "command": "/绝对路径/mcp-email-server/.venv/bin/mcp-email-server",
      "env": {
        "IMAP_HOST": "imap.qq.com",
        "IMAP_USERNAME": "you@qq.com",
        "IMAP_PASSWORD": "你的授权码",
        "SMTP_HOST": "smtp.qq.com",
        "EMAIL_FROM": "you@qq.com",
        "EMAIL_ALLOW_SEND": "true",
        "EMAIL_RECIPIENT_ALLOWLIST": "you@qq.com"
      }
    }
  }
}

Claude Desktop 的 claude_desktop_config.json 格式相同。

如果不想把密码写进配置文件，可以省略 env，改为在项目根目录放一个 .env——服务器启动时会自动读取。此时记得把 .env 加入 .gitignore（本仓库已经加了）。

想通过 HTTP 而不是 stdio 提供服务：

mcp-email-server --transport streamable-http --host 127.0.0.1 --port 8000

注意 HTTP 模式没有内置鉴权，只应绑定在本机或可信网络内。

用起来是什么样

配好之后直接用自然语言指挥即可：

• "看看我收件箱里有没有来自财务的未读邮件" → search_emails

• "把第二封的完整内容念给我听" → read_email

• "帮我回复她，说方案我同意，周五之前给她初稿" → draft_reply / send_email（带 reply_to_uid，回复会正确挂在原会话线程上）

• "等一下验证码邮件，收到告诉我" → wait_for_new_emails

• "把那封带发票的附件下载下来" → download_attachment

服务器的 instructions 里明确要求模型在调用 send_email 前先把收件人、主题、正文摆给你确认，各工具也带了 readOnlyHint / destructiveHint 标注，支持的客户端会据此决定是否弹出确认框。但这些是提示而非强制——真正的兜底是上面那几个开关和白名单。

开发

.venv/bin/pip install -e ".[dev]"
.venv/bin/python -m pytest

测试不需要任何真实邮箱账号：

• SMTP 发信路径用 aiosmtpd 起一个本地真实 SMTP 服务（含 AUTH），断言信封收件人、MIME 结构、附件内容、中文主题的 RFC 2047 编码。

• IMAP 路径用真实构造的 RFC 5322 报文喂给假 mailbox，覆盖编码头解码、HTML-only 正文降级、超长截断、附件文件名消毒。

• 工具契约用 SDK 自带的内存客户端 Client(mcp) 直连服务器对象，不起进程不占端口。

• 安全策略单独覆盖：开关关闭时必须拒绝、白名单外必须拒绝、错误信息里绝不出现密码。

用 MCP Inspector 手动点一遍（需要本机有 Node.js）：

npx @modelcontextprotocol/inspector .venv/bin/mcp-email-server

这里直接把 Inspector 指向安装好的可执行文件，而不是用 mcp dev src/mcp_email/server.py——后者会按文件路径加载模块，包内的相对导入会因此失效。

代码检查：

.venv/bin/ruff check src tests

代码结构

src/mcp_email/
  config.py       # 环境变量配置与安全策略（白名单、路径限制、密码脱敏）
  auth.py         # AuthProvider 抽象：PasswordAuth，以及 XOAuth2Auth 的骨架
  models.py       # 工具返回的 Pydantic 模型，也就是对模型暴露的契约
  imap_client.py  # 收信：连接、搜索、解析、标记、移动、附件、轮询新邮件
  smtp_client.py  # 发信：MIME 组装与投递
  server.py       # MCPServer：全部工具、资源与提示词
  __main__.py     # CLI 入口

每次 IMAP 操作都是"连接 → 干活 → 登出"。IMAP 服务器会主动断开空闲连接，而一个 MCP 服务器可能几小时都没人调用，长连接放在那儿多半已经死了。

扩展 OAuth2

auth.py 里的 AuthProvider 就是为此准备的：imap_client 和 smtp_client 从不直接接触密码，只调用 authenticate_imap / authenticate_smtp。

XOAuth2Auth 已经写好了两侧的 SASL XOAUTH2 报文格式，缺的只是令牌本身——给它一个能返回 access token 的 token_provider 就能工作。还没做的是外围的授权流程：拿到 refresh token、刷新、本地缓存。这部分完成后，build_auth() 里加一个分支即可，IMAP 与 SMTP 客户端一行都不用改。

已知限制

• 等待新邮件用的是轮询而非 IMAP IDLE 推送。imaplib 的 idle() 要 Python 3.13 才有，而轮询对所有服务商都可用；代价是最长有一个轮询间隔的延迟。

• HTML 邮件转纯文本是基于标准库 HTMLParser 的朴素实现，能保留段落和列表的换行，但复杂排版（表格布局、内联样式）会被压平。

• 尚未实现 OAuth2 授权流程，因此接不了已停用基本认证的 Microsoft 账号。

许可

MIT