mcp-mail

mcp-mail

mcp-mail 是一个可自托管的 IMAP/SMTP 邮件 MCP 服务，让 Claude、ChatGPT、Cursor 和任何其他 MCP 客户端都能通过你现有的邮箱读取、搜索、起草和发送邮件，并支持按客户端设置权限、记录审计日志，且只需一行命令即可安装。

curl -fsSL https://raw.githubusercontent.com/Annseraf/mcp-mail/main/install.sh | sudo bash -s -- --auto-update

本地客户端（Claude Desktop、Claude Code、Cursor、VS Code）可以直接运行它：npx -y @annseraf/mcp-mail stdio。

mcp-mail 是 claude-mail-mcp 的持续维护版本，原作者为 Markus Stöger（MIT）。现有的 claude-mail-mcp v0.2 安装可以直接切换，无需更改配置（参见兼容性约定）。

兼容对象

• **AI 客户端：**Claude.ai、Claude Desktop、Claude Code、ChatGPT（开发者模式、深度研究）、Cursor、VS Code、Meta Muse，以及任何通过 Streamable HTTP 或 stdio 通信的 MCP 客户端。配置指南：docs/clients。
• **邮件服务提供商：**任何 IMAP/SMTP 邮箱：Fastmail、iCloud、Purelymail、Gmail 和 Google Workspace（应用专用密码）、Yahoo、Zoho、Mailbox.org、Migadu、Mailcow、Dovecot/Postfix。
• **日历：**任何 CalDAV 服务（Fastmail、iCloud、Nextcloud、Radicale），可选。
• **MCP 协议：**2026-07-28（无状态）及自 2024-11-05 起的所有更早版本，使用同一端点。

工具

工具	功能说明	能力
list_accounts	列出已连接的邮箱、发件人名称和签名（绝不包含凭据）	读取
list_folders	列出文件夹及其特殊用途（收件箱、已发送、草稿、垃圾箱）	读取
list_messages	列出文件夹中的最新邮件，并附简短预览	读取
search_messages	按发件人、主题、正文、日期、已读状态或标记状态搜索一个或多个文件夹，也可搜索全部文件夹（"*"）	读取
get_message	阅读一封邮件：邮件头、正文、附件列表和会话 ID	读取
get_attachment	下载一个附件（有大小限制）	读取
get_thread	阅读收件箱和已发送邮件中的完整对话，按时间从早到晚排列	读取
list_threads	将文件夹中的最新邮件归组为对话	读取
create_draft	保存草稿（含附件）；reply_to_uid 会自动填入回复内容	草稿
mark_read	将邮件标记为已读或未读	整理
set_flags	加星标（标记）、标记为已回复，或添加自定义关键词	整理
move_message	将邮件移至其他文件夹	整理
delete_message	移至垃圾箱；permanent: true 会永久删除	整理 / 破坏性操作
send_message	发送邮件（含附件和签名）；副本会保存到已发送文件夹	发送
update_account_settings	更改发件人显示名称和签名	设置
list_calendars、list_events、find_free_slot	读取日历并查找空闲时间	日历读取
create_event	创建日历事件	日历写入
search、fetch	ChatGPT 深度研究适配器（CHATGPT_COMPAT=true）	读取

对比

	mcp-mail	claude-mail-mcp v0.2
传输方式	Streamable HTTP (2026-07-28 + legacy) and stdio	Streamable HTTP
身份验证	内置 OAuth 2.1 (DCR, PKCE)、每客户端令牌、共享令牌	共享令牌 + 独立 OAuth shim
每客户端权限	预设、工具允许/拒绝、邮箱范围、收件人允许列表、发送速率限制	—
只读模式	read-only 预设（或 STDIO_PRESET=read-only）	—
撤销单个客户端	可以，其他客户端继续正常工作	轮换共享密钥
附件	发送、起草和下载	仅发送
会话、标记、多文件夹搜索	可以	—
审计日志	JSONL，不含邮件内容	—
提示词注入防护	不可信内容隔离、清除隐藏 HTML、服务端指令	—
多租户 + 管理 API	可选启用，提供 OpenAPI 规范	—
安装和更新	一行安装程序、签名版本、支持回滚的自动更新	手动

其他值得一看的 IMAP MCP 服务（视你的需求而定）：codefuturist/email-mcp（TypeScript、IMAP/SMTP，提供许多工具）、tecnologicachile/mail-mcp（Rust、IMAP/SMTP，另支持 Microsoft Graph 和 EWS）以及 wildsurfer/your-mail-mcp（只读、本地 notmuch 索引）。请查看它们的 README，了解当前功能。

常见问题

如何让 ChatGPT 只读访问我的邮件？

运行 mcp-mail clients add chatgpt --for chatgpt（OAuth 登录，使用 read-only 预设），启用 OAUTH=true，并在 ChatGPT 的开发者模式中添加此服务。ChatGPT 只能看到读取工具。请参阅 docs/clients/chatgpt.md。

我可以将它用于 Fastmail、iCloud、Purelymail 或 Gmail 吗？

可以。任何支持 IMAP 和 SMTP 的服务都能使用。对于 Gmail、iCloud、Yahoo 和 Fastmail，请在服务提供商的安全设置中创建应用专用密码，并用它代替常规密码。

如何阻止 AI Agent 发送邮件？

为 Agent 指定不包含 send 的预设（read-only、read-draft 或 organize）。这样发送工具会从其工具列表中消失，即使被调用也会遭到拒绝。对于可能发送邮件的 Agent，请使用 sendRecipientAllowlist 限制收件人，并使用 sendRateLimit 限制发送量。请参阅 docs/CLIENTS.md。

邮件会诱骗 AI 做某些事吗？

邮件是不可信输入。mcp-mail 会用不可信内容分隔符包裹每封邮件的正文、清除隐藏 HTML 文本和跟踪像素，并告知客户端在发送邮件和删除邮件前向你确认。对于不需要发送功能的 Agent，请保持发送功能关闭。请参阅 SECURITY.md。

删除邮件会导致它永远丢失吗？

不会。delete_message 会将邮件移至垃圾箱。永久删除需要设置 permanent: true，并且客户端必须具备 destructive 能力。

我的密码存储在哪里？

存储在服务器上的 accounts.json 中（可选使用 mcp-mail secrets encrypt 对静态数据加密）。在多租户模式下，凭据会按租户使用本地密钥文件或 OCI Vault 进行信封加密。任何工具、API 或日志都不会返回这些凭据。

我的 Agent 可以为邮件签名吗？

可以。每个账户都可以设置发件人显示名称和签名，可在 accounts.json 中设置，也可以由 Agent 使用 update_account_settings 设置。传入 include_signature: false 即可在发送时不附加签名。

我使用的是 claude-mail-mcp。需要做任何更改吗？

不需要。替换二进制文件即可；你的 .env、accounts.json 和已连接的客户端都能继续使用。CI 会根据记录的 v0.2.1 行为对此进行验证。

安全模型

• 默认绑定到 127.0.0.1；如需 TLS，请在前面配置 nginx 或 Caddy。
• 客户端通过 OAuth 2.1（PKCE、轮换刷新令牌）、按客户端设置的静态令牌（以哈希形式存储）或旧版共享令牌进行身份验证。
• 每次工具调用都会针对客户端策略检查两次：列出工具时和调用工具时。
• 审计日志记录操作者和操作，但绝不记录邮件内容。
• 邮件内容会标记为不可信；发送和删除操作应由人工确认。
• 发布版本仅由 CI 基于带标签的提交构建，并附带校验和与来源证明。

详情：SECURITY.md、docs/CLIENTS.md、docs/PLATFORM.md。

配置

• .env：传输设置（.env.example）。所有新增设置均为可选。
• accounts.json：邮箱（格式与 claude-mail-mcp 相同；可选的 fromName/signature）。
• clients.json：按客户端设置的身份和策略（docs/CLIENTS.md）。
• 多租户模式和管理 API：docs/PLATFORM.md。

升级

从 claude-mail-mcp v0.2.x 升级：无需更改配置。 安装 mcp-mail，并指向相同的 .env、accounts.json 和（如果使用）OAuth 状态。新功能默认保持关闭，直到你启用它们。两项经批准的行为更改列于 docs/COMPATIBILITY.md：删除操作会将邮件移至“已删除邮件”，邮件内容会标记为不可信（设置 UNTRUSTED_FENCING=false 可恢复旧版输出）。

开发

npm ci
npm run check        # lint, format, typecheck, unit tests, license scan, build
npm run test:compat  # compatibility gate + integration suites (needs GreenMail, see docs/COMPATIBILITY.md)

添加工具：docs/ADDING_A_TOOL.md。贡献指南：CONTRIBUTING.md。

许可证

MIT。版权所有 (c) 2026 Markus Stöger、(c) 2026 Mohith K Das 及 mcp-mail 贡献者。请参阅 LICENSE 和 NOTICE。