mail-mcp

大多数电子邮件 MCP 服务器只能进行 IMAP 读取。这个服务器能做所有事情：读取、搜索、发送、回复、转发、批量操作、Microsoft Graph API 和 Exchange Web Services——并支持真正的 OAuth2、多账户和多提供商。使用 Rust 编写，兼具速度与安全性。

v0.4.10 的新功能

社区发布——三项更改均来自外部贡献者。感谢！

• NetEase IMAP 兼容性（126.com / 163.com / yeah.net），由 @pep-27 在 #21 中贡献。NetEase 服务器会拒绝来自未标识自身身份的客户端的邮箱访问。mail-mcp 现在会在服务器通告 ID 能力后，在认证后发送 RFC 2971 ID 命令。包含 mock-server 回归测试和 docs/account-setup.md 中的 NetEase 设置文档。

• MAIL_SMTP_<ID>_FROM_EMAIL——发件人地址覆盖，由 @arwack 在 #19 中贡献。适用于共享/组邮箱，其中 SMTP 使用个人账户进行身份验证，但 From 地址应为组地址。适用于发送、回复（包括全部回复时的自身地址检测）和转发；未设置时回退到 _USER。

• 已发送邮件的副本现在标记为 \Seen，由 @ray-of-darkness 在 #9 中贡献。MCP 在 SMTP 发送后追加到“已发送”文件夹的副本不再显示为未读。

Related MCP server: outlook-mcp-server

v0.4.9 的新功能

• 新工具 imap_get_attachment——将单个附件下载到磁盘。 在此之前，获取附件字节的唯一途径是 imap_get_message（它返回附件的元数据和可选的提取 PDF 文本，从不返回二进制数据）和 imap_get_message_raw（限制为 1 MB，并以 base64 编码放入响应中）。一封包含 X 光图像的 7 MB 邮件根本无法检索——超过上限，而且将其转储到响应中无论如何都会撑爆模型的上下文。

• 工作原理： 使用 message_id 加上一个选择器调用 imap_get_attachment——可以是 part_id（imap_get_message 为每个附件报告的值）或 filename。服务器获取完整邮件（服务器端没有大小限制），仅提取并解码那一个部分，然后将其写入磁盘，返回 { file_path, filename, content_type, part_id, size_bytes }。二进制数据永远不会进入响应，因此上下文保持较小。保存的路径可直接提供给本地读取器（例如图像描述工具或 PDF 阅读器）。

• 文件保存位置： 如果提供了 output_dir 参数，则使用该参数；否则使用 MAIL_ATTACHMENT_DOWNLOAD_DIR 环境变量；再否则使用系统临时目录。文件名经过清理（仅保留基本名称，去除控制字符）以防止路径遍历，并加上消息 UID 和部件 ID 前缀以避免冲突。

• 可选的内联 base64： 设置 include_base64: true 以同时在响应中获取字节，但仅当附件不超过 max_inline_bytes（默认 256 KiB）时。默认关闭。

v0.4.8 的新功能

• SAVE_SENT 现在是按账户设置，并带有提供商感知的默认值。 以前，通过 IMAP APPEND 将外发邮件的副本保存到“已发送”文件夹由单个全局标志 MAIL_SMTP_SAVE_SENT 控制。问题在于：已经在服务器端保存已发送邮件的提供商（Gmail、Zoho）最终在“已发送”中出现了两份完全相同的副本，而通用 SMTP 服务器或 Office 365（在 SMTP 提交时不会自动保存）在标志为 false 时完全丢失了副本。

• 提供商感知的默认值（未配置任何内容时）：

  • Gmail（smtp.gmail.com）：在服务器端保存并按 Message-ID 去重 → MCP 不会追加（false）。

  • Zoho（smtp.zoho.com）：在服务器端保存但不去重 → MCP 不会追加（false），从而避免重复。

  • Office 365 / 通用 SMTP：在 SMTP 提交时不会自动保存 → MCP 会追加（true），否则已发送副本将丢失。

• 按账户覆盖：MAIL_SMTP_<ID>_SAVE_SENT=true|false 优先于一切。全局的 MAIL_SMTP_SAVE_SENT 仍然可以作为粗略覆盖（胜过提供商默认值，但输给按账户覆盖）。

• 优先级：按账户 → 全局 → 提供商感知默认值。

v0.4.7 的新功能

• 关键修复——graph_send_message 在线程回复中静默丢弃附件。 当使用 in_reply_to + attachments 调用时，createReply → PATCH → send 流程将附件包含在针对 /me/messages/{id} 的 PATCH 中。Microsoft Graph 将 Message.attachments 视为导航属性，并在 PATCH 时静默丢弃该字段（返回 2xx 响应，无错误），因此邮件以不带文件的单部分 text/html 发出。MCP 返回 status: ok，调用方以为成功了。这是不可见的数据丢失。

• 修复方法： 在 send_via_reply() 中，附件现在在 PATCH 和发送之间逐个上传到 POST /me/messages/{draft_id}/attachments。小于 3 MB 的文件以内联方式发送（JSON 中包含 base64 的 contentBytes）；大于等于 3 MB 的文件使用 createUploadSession 进行 4 MB 分块 PUT。attachments 字段已从 PatchDraftRequest 结构体中移除，因此无法通过类型正确的编辑重新引入该回归问题。

• 对已经正常工作的流程没有更改。 send_via_sendmail（没有 in_reply_to 的新邮件）使用 POST /me/sendMail，并在 JSON 中内联包含 attachments——Graph 在该端点上确实接受该字段，从未丢弃过。该路径未做改动。

• 新增回归测试： 如果有人重新将该字段添加到结构体中，patch_draft_request_never_serializes_attachments 将失败。

• 参考： 仓库根目录下的 BUG_GRAPH_ATTACHMENTS.md 记录了完整的复现步骤、根本原因以及修复背后的实证证据。

v0.4.6 的新功能

• 对硬性规则 #1 的服务器端强制执行。 三个版本的仅提示词加固（v0.4.3 → v0.4.4 → v0.4.5）仍然让 LLM 偶尔将字面的 </body_text><parameter name="body_html"> 标记泄漏到收件人的收件箱中。v0.4.6 添加了一个真正的验证器，如果 body_text 或 body_html 包含工具调用包装器语法，它会在任何 SMTP / Graph / EWS 尝试之前拒绝该工具调用。该检查已接入所有 5 条发送路径（smtp_send_message、smtp_reply_message、smtp_forward_message、graph_send_message、ews_send_message）。

• 被禁止的标记不区分大小写，且范围严格限定——仅限于在人类通信中没有合法用途的伪标签：<body_text>、</body_text>、<body_html>、</body_html>、<function_calls>、</function_calls>、<invoke name=、</invoke> 和 <parameter name="body_*">。恰好提到用于 XML 模式的 <parameter> 或代码示例中的 <invoke> 的通用技术内容仍然可以通过。

• 硬性规则 #1 的措辞已更新，以宣布服务器端拒绝，让 LLM 知道这是一项硬性约定——不是可以忽略的建议。

• 对正常调用方没有破坏性更改：行为良好的邮件与之前完全一样地发送。

v0.4.5 的新功能

• serverInfo 现在报告 name="mail-mcp" + crate 的 version（该框架以前返回自己的 rmcp 0.16.0，它在各版本之间从不变化）。这有助于使用 /mcp 验证当前版本，并且使任何以（server, version）为键的客户端缓存每次升级时都会失效。

• MCP 指令重新组织：3 条关键的反拼接规则（在 v0.4.3 和 v0.4.4 中位于块末尾，可能因截断/注意力稀释而丢失）现在作为硬性规则 #1、#2、#3 出现在顶部，紧跟在标题之后。合并为 3 个短段落（以前是 3 个长章节，合计约 1500 个字符）。

• 服务器没有功能变化。 相同的 SMTP/IMAP/EWS/Graph、相同的工具集、相同的行为。只有暴露给客户端的文本发生了变化。

这些规则生效的重要说明

使用 claude --continue（或 /resume）恢复会话的客户端不会刷新 MCP 的 system_prompt——它们会保留该会话首次握手时的那个。如果您的会话早于 v0.4.5，即使磁盘上的二进制文件已更新，这些规则也不会进入您的上下文。要接收它们，请在项目中启动一个新会话（而不是 --continue）。

v0.4.4 的新功能

• 预览卫生规则，位于 MCP instructions 中：当 LLM 在发送前向用户展示邮件预览时，它应该渲染正文的一个干净版本（markdown 风格的项目符号、粗体、链接以文本 + URL 形式呈现），并说明邮件将以 multipart 形式发送——但绝不能将原始 HTML 源码（<p>、<strong>、<a href>...）转储到预览中。原因有二：

  1. 人工审阅者想要阅读邮件，而不是审计标记——展示 HTML 是噪音。

  2. 在预览中并排展示纯文本字符串和 HTML 字符串，正是历史上导致 LLM 在最终工具调用中将它们拼接起来的上下文（v0.4.3 记录的那个 bug）。从预览中隐藏 HTML 源码可以消除这种诱惑。

  这是对 v0.4.3 中引入的 预览不等于工具调用 规则的补充。

v0.4.3 的新功能

• 针对畸形工具调用的服务器端指导。 MCP instructions 块现在明确告诉调用方 LLM：body_text 和 body_html 是两个独立的 JSON 字段，绝不能拼接。以前的措辞（“同时发送 body_text 和 body_html”）有歧义，一些 LLM 将其解释为“在单个 body_text 字符串中用 <body_text>...</body_html> 伪标签将两者拼接起来”。发生这种情况时，收件人会看到乱码的重复内容，而且任何后来通过此 MCP 打开已保存副本的 Claude 会话都会触发使用政策拦截（泄漏的 <invoke>...</invoke> 在安全过滤器看来像一次提示注入尝试）。新的指令展示了正确与错误的示例，并禁止在邮件字段中使用伪标签 / 工具调用包装器语法。

v0.4.2 的新功能

• 修复了发布流水线：CI 发布工作流中的 publish-npm 任务已被禁用。它继承自上游 fork，会尝试发布到 @bradsjm/mail-imap-mcp-rs——这个 scope 并非本组织所有，因此每次发布在该步骤都会返回 404。完整说明以及如何按需重新启用 npm 发布，请参阅下文的"Releasing"。

• 推送标签时自动触发发布：.github/workflows/release.yml 现在会在 push: tags: ['v*'] 时触发，因此只需打上 vX.Y.Z 标签并推送，即可完成一次发布。workflow_dispatch 仍保留，作为手动应急出口。

• 清理：移除了悬挂的 init-npm-placeholder.yml 工作流（它也引用了该 fork 的 npm scope）。

• 文档：README 新增了 "Releasing" 一节，记录了新流程和 npm 决策。

v0.4.1 中的新增内容

• 修复：save_to_sent_folder 现在会存档实际发送的 RFC822 原始字节（通过 lettre.formatted()），而不是手工拼凑的纯文本占位内容。Sent 文件夹副本会保留 HTML 正文、multipart/alternative 结构和 RFC 2047 编码的主题——重音字符不再显示为 ???，HTML 也不会再被静默丢弃。

• 改进：本地化 Sent 文件夹检测——Enviado[s]、Elementos enviados、Enviadas、Itens enviados、Envoyés、Éléments envoyés、Gesendet、Posta inviata、Verzonden、Wysłane，以及嵌套变体。此前只识别英文名称，因此 Zoho/本地化 IMAP 账户会落入不存在的 "Sent" 文件夹。

• 改进：smtp_forward_message 现在接受 body_html（此前硬编码为仅纯文本）。

• 改进：EWS 发送新增 bcc、in_reply_to、references（通过 <t:InternetMessageHeaders>），并加入完整的收件人和主题长度校验——现在与 SMTP 和 Graph 发送路径保持对等。

• 改进：Graph API 线程回退现在会记录日志。当消息查询 HTTP 调用失败（限流、5xx、权限问题）时记录 WARN，让运维人员看到线程功能因真实错误而降级；当原始消息确实不存在时记录 DEBUG。

• 重构：EWS XML 解析从子串匹配迁移到 quick-xml。修复了潜在的命名空间冲突 bug（<soap:Body> 与 <t:Body>），正确解码 XML 实体和 CDATA，并处理包含 = 的属性值（在 base64 风格的 EWS 项目 ID 中很常见）。

• 清理：cargo build --release 零警告。

• 测试：64 个（原为 47 个）。

为什么选择这个项目

功能矩阵

EWS 是添加 Microsoft 账户的最简单方式——一个 OAuth2 令牌即可同时用于读取和发送。即使在屏蔽 Graph API 和 IMAP 的租户上也能正常工作。

快速开始 —— 让 Claude Code 来完成

将以下提示词复制粘贴到 Claude Code 中，它会为你安装、编译并配置好一切：

Install and configure the mail-mcp MCP server from https://github.com/tecnologicachile/mail-mcp

1. Clone the repo, build with cargo build --release
2. Add the MCP server to .claude.json with the binary path
3. For Microsoft accounts: use EWS (simplest) — run device code flow with
   client_id d3590ed6-52b3-4102-aeff-aad2292ab01c and scope
   https://outlook.office365.com/EWS.AccessAsUser.All offline_access
   Then configure MAIL_EWS_<ID>_USER and MAIL_EWS_<ID>_REFRESH_TOKEN
4. For Gmail: configure MAIL_IMAP + MAIL_SMTP with App Password from
   https://myaccount.google.com/apppasswords
5. For Zoho: configure MAIL_IMAP + MAIL_SMTP with standard password
6. Enable write/send: MAIL_IMAP_WRITE_ENABLED=true, MAIL_SMTP_WRITE_ENABLED=true

My email accounts to configure:
- <your-email@example.com>

将最后一行替换为你的邮箱。Claude Code 会引导你完成每一步，包括 Microsoft 账户的 OAuth2 设备代码流程。

手动设置（2 分钟）

git clone https://github.com/tecnologicachile/mail-mcp.git
cd mail-mcp
cargo build --release

添加到你的 MCP 客户端配置中（Claude Code、Cursor 等）：

{
  "mcpServers": {
    "mail": {
      "command": "./target/release/mail-mcp",
      "env": {
        "MAIL_IMAP_DEFAULT_HOST": "imap.gmail.com",
        "MAIL_IMAP_DEFAULT_USER": "you@gmail.com",
        "MAIL_IMAP_DEFAULT_PASS": "your-app-password",
        "MAIL_SMTP_DEFAULT_HOST": "smtp.gmail.com",
        "MAIL_SMTP_DEFAULT_PORT": "587",
        "MAIL_SMTP_DEFAULT_USER": "you@gmail.com",
        "MAIL_SMTP_DEFAULT_PASS": "your-app-password",
        "MAIL_SMTP_DEFAULT_SECURE": "starttls",
        "MAIL_IMAP_WRITE_ENABLED": "true",
        "MAIL_SMTP_WRITE_ENABLED": "true"
      }
    }
  }
}

就这样。你的 AI 代理现在可以读取、搜索、发送、回复和管理邮件了。

使用 Microsoft 账户？请使用 Graph API

微软在个人账户上屏蔽了 SMTP。请改用 Graph API：

{
  "env": {
    "MAIL_IMAP_DEFAULT_HOST": "outlook.office365.com",
    "MAIL_IMAP_DEFAULT_USER": "you@hotmail.com",
    "MAIL_IMAP_DEFAULT_PASS": "your-app-password",
    "MAIL_OAUTH2_DEFAULT_PROVIDER": "microsoft",
    "MAIL_OAUTH2_DEFAULT_CLIENT_ID": "9e5f94bc-e8a4-4e73-b8be-63364c29d753",
    "MAIL_OAUTH2_DEFAULT_CLIENT_SECRET": "none",
    "MAIL_OAUTH2_DEFAULT_REFRESH_TOKEN": "<your-token>"
  }
}

通过设备代码流程，1 分钟即可获得令牌。请参阅账户设置指南。

31 个 MCP 工具

读取（9 个工具）

写入（11 个工具）

发送（5 个工具）

EWS —— Exchange Web Services（3 个工具）

附件

使用任意发送工具发送文件。两种模式：

// Large files — MCP reads from disk (recommended)
"attachments": [{"file_path": "/path/to/report.pdf"}]

// Small files — inline base64
"attachments": [{"filename": "note.txt", "content_type": "text/plain", "content_base64": "SGVsbG8="}]

文件名和 MIME 类型会根据文件路径自动检测。回复时使用 include_original_attachments: true 即可转发原始附件。

下载收到的邮件中的附件：使用 imap_get_attachment 并传入 message_id 和 part_id（来自 imap_get_message）或 filename。它会将解码后的文件写入磁盘并返回路径——没有大小限制，二进制内容也不会出现在响应中。通过 MAIL_ATTACHMENT_DOWNLOAD_DIR 设置默认下载目录（回退到系统临时目录），或在每次调用时传入 output_dir。

批量操作（2 个工具）

设置助手（1 个工具）

多账户

按需配置任意数量的账户：

# Gmail
MAIL_IMAP_GMAIL_HOST=imap.gmail.com
MAIL_IMAP_GMAIL_USER=me@gmail.com
MAIL_IMAP_GMAIL_PASS=app-password

# Microsoft 365
MAIL_IMAP_WORK_HOST=outlook.office365.com
MAIL_IMAP_WORK_USER=me@company.com
MAIL_OAUTH2_WORK_PROVIDER=microsoft
MAIL_OAUTH2_WORK_CLIENT_ID=your-client-id
MAIL_OAUTH2_WORK_CLIENT_SECRET=none
MAIL_OAUTH2_WORK_REFRESH_TOKEN=your-token

# Zoho
MAIL_IMAP_DEFAULT_HOST=imap.zoho.com
MAIL_IMAP_DEFAULT_USER=info@mydomain.com
MAIL_IMAP_DEFAULT_PASS=password
MAIL_SMTP_DEFAULT_HOST=smtp.zoho.com
MAIL_SMTP_DEFAULT_USER=info@mydomain.com
MAIL_SMTP_DEFAULT_PASS=password
MAIL_SMTP_DEFAULT_SECURE=starttls

在工具调用中使用 account_id："account_id": "gmail"、"account_id": "work"、"account_id": "default"。

安全

• 所有连接强制启用 TLS（localhost 代理除外）

• 密码存放在 SecretString 中——绝不会被记录日志或在响应中返回

• 写操作受控——需要显式设置 MAIL_IMAP_WRITE_ENABLED=true

• 发送操作受控——需要显式设置 MAIL_SMTP_WRITE_ENABLED=true

• 删除确认——需要 confirm: true

• HTML 经过 ammonia 净化（防止 XSS）

• 输出有界——正文文本、HTML、附件会被截断到可配置的上限

• OAuth2 令牌缓存带有 10 分钟的刷新余量

• 响应中不含机密信息——凭据绝不会通过 MCP 工具暴露

配置参考

IMAP（每个账户）

SMTP（每个账户）

OAuth2（每个账户）

Graph API OAuth2（每个账户）

EWS — Exchange Web Services（每个账户，Microsoft 最简单的方案）

提示： EWS 只需要 2 个变量（USER + REFRESH_TOKEN）。客户端 ID 默认为 Microsoft Office，其所有权限均已预先批准。

全局设置

路线图

• IMAP 读取操作（搜索、获取、解析）

• IMAP 写入操作（复制、移动、删除、标记）

• IMAP 批量操作（每次调用最多 500 个）

• 基于游标的分页（带 TTL）

• SMTP 发送、回复、转发

• Microsoft Graph API (sendMail)

• OAuth2 XOAUTH2 (Google + Microsoft)

• 用于企业的独立 Graph API 令牌

• 通过环境变量支持多账户

• 从附件中提取 PDF 文本

• HTML 净化（ammonia）

• 带有直接链接的提供商设置文档

• 附件发送（SMTP/Graph）

• 使用原始附件回复

• CDATA 清理（修复 Zoho bug）

• 邮件确认协议（发送前预览）

• 令牌优化指令（减少 75%）

• 按需设置指南工具

• EWS (Exchange Web Services) — 在 Microsoft 上使用单个令牌即可读取和发送

• EWS 搭配 Microsoft Office 客户端 ID（适用于受限租户）

• Graph API 会话线程 — 使用 createReply 流程实现正确的会话线程

• HTML 格式指南 — LLM 更倾向于使用 multipart（text + HTML）发送面向人的邮件

• 已发送文件夹归档保留完整 MIME — 与收件人收到的邮件逐字节相同的副本（v0.4.1）

• 本地化的已发送文件夹检测 — 西班牙语 / 葡萄牙语 / 法语 / 德语 / 意大利语 / 荷兰语 / 波兰语（v0.4.1）

• EWS 功能与 SMTP/Graph 对等 — BCC、会话线程头、收件人验证（v0.4.1）

• 通过 quick-xml 解析 EWS XML — 正确处理实体/CDATA/命名空间（v0.4.1）

下一步 — 本地缓存与即时搜索

• SQLite + FTS5 本地邮件缓存 — 即时搜索（<10ms，对比 3-10s）

• 增量同步 — UIDVALIDITY + 上次 UID 增量同步

• 连接池 — 每个账户保持持久的 IMAP 会话

• 跨账户搜索 — 一次搜索所有账户

• 邮件统计 — 数量、最频繁发件人、按日期的活动

未来

• Docker 镜像

• npm/npx 分发

• 草稿管理

• 联系人搜索

• IMAP IDLE（实时通知）

• 托管文档站点

文档

开发

cargo test              # 64 unit + integration tests
cargo fmt -- --check    # formatting
cargo clippy --all-targets -- -D warnings  # linting

参见 AGENTS.md 了解贡献者指南。

发布

发布通过 cargo-dist 自动完成。要发布新版本：

1. 在 Cargo.toml 中升级 version = "X.Y.Z"（发布工作流会强制要求与推送的标签一致）。

2. 将版本升级和发布说明提交到 main。

3. 打标签并推送：

   git tag vX.Y.Z
   git push origin main --tags

4. .github/workflows/release.yml 中的 push: tags: ['v*'] 触发器会为 Linux / macOS（Intel + Apple Silicon）/ Windows 编译二进制文件，生成安装脚本（.sh、.ps1），创建 GitHub Release，并附加所有带 SHA256 校验和的构建产物。

5. 如果任何步骤失败，您可以从 Actions 选项卡手动重新运行工作流（保留了 workflow_dispatch 触发器作为应急方案）。

npm 发布已被有意禁用。 上游 fork 被配置为以 @bradsjm/mail-imap-mcp-rs 发布，但该组织并不拥有这个 scope，导致每次发布在 npm publish 时都返回 404。npm tarball 仍会生成并附加到每个 GitHub Release，用户可通过 npm install ./mail-mcp-npm-package.tar.gz 手动安装。若要为此 fork 启用 npm registry 发布：创建一个 npm 组织（例如 @tecnologicachile），在 npmjs.com 上配置指向此仓库的 Trusted Publishing，在 dist-workspace.toml 中设置 publish-jobs = ["npm"]，然后运行 dist generate --allow-dirty 以恢复 release.yml 中的 publish-npm 作业。

贡献

欢迎贡献！请查看 issues 查找适合新手的问题。

许可证

MIT 许可证 — 详情请参阅 LICENSE。