✉️ apple-mail-mcp

你的 Apple Mail，完全可由智能体操作。

在你的 Mac 上本地运行。 它以只读方式打开 Mail 存储，只返回客户端请求的内容，并且仅在客户端显式调用发送工具时才发送。没有第三方中继，没有你的邮件的云端副本。

使用 Claude、Codex、Cursor、VS Code 或任何本地 MCP 客户端 通过 Apple Mail 搜索、阅读、分类和发送邮件——你的邮箱变成你可以 询问、搜索和委托 的东西——几秒钟内找到任何内容，通过审阅过的计划归档数百条消息，以正确的身份发送精美的邮件，并让 Exchange 即使在你的 Mac 休眠时也能投递定时消息。

✨ 你可以做什么

🔍 向你的邮箱提问。 "Stefan 上周关于备忘录给我发了什么？" 搜索以数据库速度运行——发件人、邮箱、日期、未读、附件——并重建完整对话。

🕳️ 找到 Mail 本身找不到的东西。 Mail 的内置搜索只浏览大多数消息的第一行。apple-mail-mcp 索引你 Mac 上每条消息的正文——对于 Exchange 账户，它甚至能获取 Mail 从未下载的正文，直接从服务器上你自己的邮箱中获取。返回零结果的查询返回二十条结果。

🎭 以正确的你发送。 工作邮件走工作通道，个人邮件走 Gmail——一个参数选择身份。每条消息都从头撰写为干净、符合标准的电子邮件，在任何地方都能正确渲染，包括 Outlook（在 Outlook 中显示为空白的那条 AppleScript 撰写路径正是这个项目存在的原因）。

⏰ 像"稍后发送"一样定时，但可脚本化。 定时消息被完整冻结——附件、身份、确切文本。Exchange 可以在请求的时间在服务器端执行它，合上盖子也行；其他提供商使用本地后台发送器，在其下一次运行时投递（或 Mac 唤醒后立即投递）。

🗂️ 大规模分类，无需担心。 "归档这 40 份新闻通讯" 变成一个可审阅的计划：在批准之前不会移动任何内容，每条消息在被处理前都会重新检查，之后还会对照 Mail 自己的记录验证结果。删除意味着 Mail 的废纸篓——任何内容都不会被永久擦除。

📝 在你的草稿所在处起草。 撰写到你的真实 Exchange 草稿文件夹中，随时可以在 Outlook 或 OWA 中打开——创建，绝不自动发送。

Related MCP server: Mac Local Mail MCP

⚡ 为什么它不同

其他每个 Apple-Mail MCP 都使用 AppleScript 进行查找和操作。这个不是——而且效果显而易见：

以上每个数字都是在实时约 30 万条消息的存储上实测的；脚本和完整方法见 docs/benchmarks.md。

🛡️ 为可信赖而构建

• ✅ 计划 → 审阅 → 应用 → 验证。 批量操作被冻结为计划，在任何操作发生前你都可以阅读；结果之后会对照 Mail 自己的存储进行确认——绝不假设。

• 🗑️ 任何内容都不会被永久擦除。 "删除"归档到 Mail 的废纸篓，破坏性计划有自己独立的、有上限的门。

• 👓 只读邮件模式。 设置 EMAIL_MCP_READ_ONLY=1，会话中只存在 11 个非修改性邮件工具。搜索可能仍会维护其本地正文索引，附件检索会将请求的文件写入配置的临时目录。

• 💾 崩溃安全的定时队列。 清单更新会被刷新并原子替换，因此中断的重写会保留最后一条有效记录。如果文件被独立损坏，诊断会指明它，而不是声称队列为空，同时健康的定时消息继续移动。

• 🧾 本地、尽力而为的活动账本。 发送、定时、取消和分类运行都会被记录，而不会让不可写的日志阻塞邮件。为了对账，消息本身、其 Message-ID 和其定时记录保持权威。

• 🔒 没有第三方邮件中继。 邮件内容保持本地，除了你发送的邮件和对你自己提供商的可选访问（用于 Exchange/IMAP 正文回填、草稿和服务器端定时）。SMTP 密码保留在 macOS 钥匙串或 1Password 中；Microsoft OAuth 令牌存放在 ~/.email-mcp/graph/ 下的私有 0600 缓存中。

• 📜 书面契约。 自 v1.0 起，每个工具的形状、错误代码和上限都以增量方式演进，由 800 多项自动化测试保障。

• 🤝 对每个 MCP 客户端都清晰。 所有 21 个工具都说明它们做什么，解释每个输入，并声明它们是读取、更改还是可能删除数据。较新的客户端接收结构化结果；较旧的客户端保持相同的 JSON 文本。维护中的 MCP 1.x 系列和当前的 MCP 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

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 工具；每个红色行都附带确切修复。大型邮箱的首次正文索引构建在后台运行，可能需要几分钟；搜索立即可用，并随着索引填充而完成。

在运行 setup 之前，授予你的终端应用完全磁盘访问权限（系统设置 → 隐私与安全性 → 完全磁盘访问权限）——这就是读取保持快速和本地的方式。这个没有弹出窗口；它是 Apple 唯一的手动开关，如果 setup 发现它缺失，会引导你到确切的面板。

setup 用通俗语言询问所有内容（直接按 Enter 接受推荐答案），提供发送身份，构建正文搜索索引，验证夜间刷新确实运行，最后打印你粘贴到 MCP 客户端的那一个块：

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

设置以明确的就绪结论或编号的恢复步骤结束。当分类首次请求时，授予自动化 → 邮件权限。随时使用 apple-mail-mcp status 检查安装、下一条定时消息和失败的定时发送；使用 apple-mail-mcp doctor 获取完整技术细节。

💡 终端新手？ 三件看起来不对但实际正常的事情： brew install pipx 需要输入 y（仅按 Enter 会被拒绝）； pipx ensurepath 可能打印 ⚠️ — 它后面的 "pipx is ready to go!" 行才是结论；在 ensurepath 之后，关闭并重新打开终端一次，以便找到 apple-mail-mcp。

🔧 故障排除

🧰 21 个工具

附件双向传输，按大小预算。回复在每个客户端中都能正确串成线程。调度在休眠后依然有效——合盖期间到期的消息会在唤醒后的第一个时钟周期发出，或通过 Exchange 精确按时发出。

🎭 你的地址，你的通道

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

default = "work"

[work]                    # sent through a host you already trust, over SSH
from_addr = "you@example.org"
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 = "you@gmail.com"
driver    = "smtp"
host      = "smtp.gmail.com"
op        = "op://Personal/gmail app password/password"

Exchange 身份可以额外添加一次登录以解锁更多功能：草稿归档到你的真实 Drafts 文件夹，定时发送由服务器本身执行——合盖、Mac 休眠时也能工作。setup 用一个简单的问题就能完成配置。读取邮件完全不需要发送配置。

21 个工具 · 849 项测试 · 自 v1.0 起保持增量的线缆协议 在 305k 条消息的存储上进行了端到端实时校准。

为了一台 Mac 而构建——也为了任何其他运行 Mail.app 的 Mac 用户。