apple-mail-mcp

uvx apple-mailbox-mcp setup

✨ 你可以做什么

🔍 向邮箱提问。 “Maria 上周发给我的备忘录相关邮件是什么？” 搜索以数据库速度运行 — 可按发件人、邮箱、日期、未读状态和附件搜索 — 并还原完整对话。

🕳️ 找到 Mail 本身找不到的内容。 Mail 内置的搜索只会浏览大多数邮件的第一行。apple-mail-mcp 会为 Mac 上每封邮件的正文建立索引 — 对于 Exchange 账户，它甚至会直接从你自己的服务器邮箱中获取 Mail 从未下载的正文。原本搜不到的内容，现在能搜出二十条。

🎭 以正确的身份发送。 工作邮件走工作通道，个人邮件走 Gmail — 一个参数即可选择身份。每封邮件都从头编写为干净、符合标准且能在任何地方正确呈现的邮件，包括 Outlook（通过 AppleScript 撰写的邮件在 Outlook 中显示为空白，这正是这个项目存在的原因）。

⏰ 像“稍后发送”一样安排发送，还能通过脚本控制。 已安排的邮件会完整冻结 — 包括附件、身份、确切文本，以及从 1.8.2 开始的线程标头，因此定时回复会进入它所回复的对话。Exchange 可以在指定时间于服务器端执行，即使合上 Mac 的盖子也没问题；其他服务提供商则使用本地后台发送器，在下一次运行时发送（或在 Mac 唤醒后立即发送）。

🗂️ 放心地大批量整理。 “归档这 40 封新闻简报” 会生成可供审核的计划：批准前不会移动任何内容，每封邮件在处理前都会重新检查，之后还会根据 Mail 自己的记录验证结果。删除操作会将邮件移入 Mail 的废纸篓 — 永远不会彻底抹除。

📝 在草稿所在的位置撰写。 将邮件写入真正的 Exchange“草稿”文件夹，可在 Outlook 或 OWA 中打开 — 只创建草稿，绝不自动发送。

⚡ 与众不同之处

其他所有 Apple-Mail MCP 都会用 AppleScript 来搜索和执行操作。 而这个 MCP 不会——效果一目了然：

以上所有数据均在一个约包含 30 万封邮件的实时存储中测得；测试脚本和完整方法见 docs/benchmarks.md。

如果这些基准测试在你的邮箱中也成立，点个 ⭐ 能帮助更多人发现这个项目。

🛡️ 值得信赖的设计

• ✅ 规划 → 审核 → 执行 → 验证。 批量操作会先冻结为一份计划，你可以在任何操作发生前查看；之后会根据 Mail 自己的存储确认结果，而不是想当然地认为操作成功了。
• 🗑️ 绝不会彻底删除任何内容。 “删除”会将邮件移至 Mail 的废纸篓；破坏性计划则有专门的独立入口，并设有上限。
• 👓 只读邮件模式。 设置 EMAIL_MCP_READ_ONLY=1 后，会话中只提供 11 个不会修改数据的邮件工具。搜索仍可能维护本地正文索引；获取附件时，会将请求的文件写入配置的临时目录。
• 💾 崩溃安全的定时队列。 清单更新会先写入并原子替换，因此重写中断时仍能保留最后一条有效记录。如果文件单独损坏，诊断信息会指出具体文件，而不会误称队列为空；正常的定时邮件仍会继续处理。
• 🧾 本地尽力而为的活动日志。 发送、定时发送、取消和分类操作都会被记录，但日志不可写时不会因此阻止邮件操作。需要核对时，邮件本身、其 Message-ID 和定时记录仍是权威依据。
• 🔒 不使用第三方邮件中继。 除了你发送的邮件，以及可选的自有服务商访问（用于 Exchange/IMAP 正文补充、草稿和服务端定时发送）以外，邮件内容都留在本地。SMTP 密码保存在 macOS Keychain 或 1Password 中；Microsoft OAuth 令牌存放在 ~/.email-mcp/graph/ 下权限为 0600 的私有缓存中。
• 📜 有据可查的契约。 自 v1.0 起，每个工具的结构、错误代码和上限都以向后兼容的方式扩展，并由 800 多项自动化测试保障。
• 🤝 让所有 MCP 客户端都能清楚了解。 全部 21 个工具都会说明其功能、解释每项输入，并声明它们会读取、更改还是可能移除数据。较新的客户端会收到结构化结果；较旧的客户端仍会得到相同的 JSON 文本。项目会测试 MCP SDK 2.2 及更新的 2.x 版本，并支持较旧的客户端。
• 🧱 不断演进，不破坏现有工作流。 邮件规则与 MCP、Mail.app、Exchange、邮件投递和本地存储相互隔离。服务商或 SDK 的变更仅影响边界层，而 21 个工具的契约保持稳定。依赖规则由 CI 强制执行，并在架构指南中说明。
• 📦 可验证的发行版本。 每个带标签的发行版本都会先在干净环境中构建并安装，再发布。GitHub 会提供 wheel、源码归档、SHA-256 校验和以及签名的构建来源证明，而不只是源代码。
• 🩺 可自我诊断。 apple-mail-mcp status 会提供一屏易读的就绪状态、定时发送和恢复信息。apple-mail-mcp doctor 会给出完整的诊断详情，并为每项异常提供确切的修复方法。

🚀 快速开始

1. 为终端应用授予“完全磁盘访问权限” （系统设置 → 隐私与安全性 → 完全磁盘访问权限），然后退出并重新打开终端。这是 Apple 要求手动开启的一项设置，不会弹出提示。

2. 安装并设置：

   uvx apple-mailbox-mcp setup     # or: pipx install apple-mailbox-mcp
   # or via Homebrew:
   brew install parasxos/tap/apple-mail-mcp && apple-mail-mcp setup
   

3. 向客户端注册——Claude Code 只需一行：

   claude mcp add --transport stdio --scope user apple-mail -- uvx apple-mailbox-mcp
   

   或者，将同一 JSON 代码块用于 Claude Desktop / Cursor / VS Code （claude_desktop_config.json / .cursor/mcp.json / .vscode/mcp.json）：

   {
     "mcpServers": {
       "apple-mail": { "command": "uvx", "args": ["apple-mailbox-mcp"] }
     }
   }
   

4. **验证：**运行 uvx apple-mailbox-mcp status 会显示一屏就绪状态；也可以直接让客户端运行 doctor 工具，每条红色提示都会附带对应的修复方法。运行 uvx apple-mailbox-mcp --version 会显示已安装的版本（apple-mailbox-mcp、apple-mail-mcp 和 email-mcp 是同一命令的三个名称）。大型邮箱首次构建正文索引时会在后台运行，可能需要几分钟；搜索立即可用，并会随着索引填充而逐步完善。

运行 setup 之前，请为终端应用授予完全磁盘访问权限（系统设置 → 隐私与安全性 → 完全磁盘访问权限）——这样读取速度快，而且数据保留在本地。此设置不会弹出提示；这是 Apple 要求手动开启的一项设置。如果 setup 检测到尚未授予权限，会引导你前往对应的设置面板。

setup 会用通俗的语言逐项提问（直接按 Enter 即可接受推荐答案），提供发送身份选项，构建正文搜索索引，验证夜间刷新任务确实会运行，并在最后显示需要粘贴到 MCP 客户端的唯一代码块：

{
  "mcpServers": {
    "apple-mail": { "command": "apple-mail-mcp" }
  }
}

设置结束时会明确显示就绪结果，或提供编号恢复步骤。首次进行邮件分拣时，请授予自动化 → Mail权限。随时运行 apple-mail-mcp status，检查安装状态、下一封计划发送的邮件和发送失败的计划邮件；运行 apple-mail-mcp doctor 可查看完整的技术详情。

💡 不熟悉终端？ 以下三种情况看起来不对，其实都正常： brew install pipx 需要输入 y（只按 Enter 会被拒绝）； pipx ensurepath 可能会显示 ⚠️——后面的“pipx is ready to go!”才是结果；运行 ensurepath 后，请关闭并重新打开终端一次，这样才能找到 apple-mail-mcp。

🔌 兼容的客户端

以下客户端均支持 stdio MCP；使用的命令始终是 uvx apple-mailbox-mcp。

Claude Code

claude mcp add --transport stdio --scope user apple-mail -- uvx apple-mailbox-mcp

Claude Desktop

添加到 ~/Library/Application Support/Claude/claude_desktop_config.json：

{ "mcpServers": { "apple-mail": { "command": "uvx", "args": ["apple-mailbox-mcp"] } } }

Cursor

将同一代码块添加到 ~/.cursor/mcp.json（或项目级 .cursor/mcp.json）。

VS Code（Copilot MCP）

将同一代码块添加到 .vscode/mcp.json 的 "servers" 下。

Codex CLI

# ~/.codex/config.toml
[mcp_servers.apple-mail]
command = "uvx"
args = ["apple-mailbox-mcp"]

任何 stdio MCP 客户端

将其指向 uvx apple-mailbox-mcp。自 v1.0 起，线协议仅以追加方式扩展。

🔧 故障排除

🧰 21 个工具

支持双向收发附件，并设有大小限制。回复会在所有客户端中正确归入会话。定时发送不受休眠影响——若邮件在合上电脑盖时到期，会在唤醒后的第一个时点发出；使用 Exchange 则能准时发送。

🎭 你的地址，你的通道

邮件的 From: 地址决定邮件的发送方式。~/.email-mcp/identities.toml：

default = "work"

[work]                    # sent through a host you already trust, over SSH
from_addr = "[email protected]"
driver    = "ssh_sendmail"
host      = "bastion.example.org"   # any login host you already SSH to

[gmail]                   # classic SMTP — the app password stays in 1Password
from_addr = "[email protected]"
driver    = "smtp"
host      = "smtp.gmail.com"
op        = "op://Personal/gmail app password/password"

Exchange 身份可通过添加一个登录账户解锁额外功能：将草稿保存到你的真实“草稿”文件夹，并由服务器自行执行定时发送——即使合上电脑盖、Mac 进入睡眠也不受影响。setup 会通过一个简单的问题提供此选项。读取邮件完全无需配置发送功能。