Apple Mail

apple-mail-mcp

一个只读的 MCP 服务，可让 AI 助手搜索和阅读 Apple Mail 中的邮件。

仅限 macOS。 它读取 Mail.app 在 Mac 上维护的本地索引。

claude mcp add apple-mail -- npx -y @redpop/apple-mail-mcp

然后运行 npx -y @redpop/apple-mail-mcp setup，授予一次“完全磁盘访问”权限。对于 Claude Desktop，可一键安装：参见安装。

功能

主要用途是“查找关于 X 的邮件”：

"Find the mail from the landlord about the heating bill"
"What did Anna send me last week with an attachment?"
"Show the whole thread about the contract renewal"

提供四种工具：list_mailboxes、search_messages、get_message、get_thread。搜索范围包括发件人、收件人、主题、全文、邮箱、日期范围、未读、已加旗标和附件，也可搜索邮件正文。结果包含一个 message:// 链接，可在 Mail.app 中打开邮件；Message-ID 存储在 Mail 中（macOS 15 除外）。详情请参阅 docs/tools.md。

为什么选择它

• 速度快。 它查询 Mail 的 SQLite 索引，而不是通过 AppleScript 脚本操作 Mail.app。在一个约有 240,000 条邮件记录的真实邮箱中，辅助程序检索一页结果耗时 4 到 90 ms；首次搜索后，按主题搜索耗时 25 ms。测量结果及其局限性请参阅 docs/architecture.md。
• “完全磁盘访问”权限仅授予一个小型辅助程序，而非终端或 AI 客户端。 服务通过一个名为“Mail MCP Helper”的小型应用访问 Mail 文件，macOS 只将权限绑定到该应用。Node、Terminal 和 Claude 都不会获得此权限。
• 只读是由设计决定的，而非通过标志控制。 代码不会发送、起草、移动、删除或标记邮件，不会以写入模式打开数据库，也不会建立网络连接。
• Mail.app 无需运行，也不会出现自动化权限提示。不过，数据的新鲜度取决于 Mail 上次同步的时间，而且 Mail 从未下载过的邮件没有正文。
• 会话和深层链接。 get_thread 会返回一个对话；邮件包含一个 message:// 链接（macOS 15 除外）。
• 默认不显示安全相关邮件。 看起来像验证码、密码重置或登录链接的邮件会隐藏正文、遮盖主题中的数字，且无法通过正文搜索找到。检测尽力而为，不作保证。
• 设置来自配置，而非工具参数，因此恶意邮件无法要求模型将其关闭。
• 可与 apple-calendar-mcp 配合使用：例如“查找关于周四会议的邮件”。遵循相同约定：时间戳使用带时区偏移的 ISO 8601 格式；错误以 isError 结果返回，每个错误代码对应一条通俗易懂的说明。

要求

• macOS 15 或更高版本。仅在 macOS 27.0.1 和 Mail 16.0 上通过真实邮箱验证。macOS 15.8 和 26.6 的数据库布局通过了辅助程序的列检查；这些版本来自未配置邮件账户的运行环境。在 macOS 15 上，Mail 不存储 Message-ID 标头，因此结果不包含 message:// 链接。是否支持取决于 Mail 数据库的布局，而非版本号：doctor 会检查数据库布局。 欢迎反馈其他版本的测试结果，参见问题报告。
• Node.js 22 系列中的 22.16 或更高版本，或 24 及更高版本。
• 已设置至少一个账户的 Mail。
• Exchange 账户尚未测试。邮箱和邮件元数据会列出，但目前不会读取 Exchange 邮件正文：get_message 会报告 file_not_found。请参阅 docs/exchange.md。

安全模型简介

邮箱中存有机密信息：验证码、重置链接、合同。在将邮箱连接到也能访问互联网的模型之前，请先阅读此内容。

• 辅助程序拥有「完全磁盘访问权限」，且只运行固定命令。它没有自由形式的 SQL，也没有路径参数，并且从不解析邮件内容。不可信的 MIME 由没有特殊权限的 Node 解析。
• 邮件文本是不可信输入。服务端会告知模型这一点，但无法强制模型遵守。
• 如果你的客户端也有网页访问或发送工具，恶意邮件可能会试图诱使模型泄露它读取的内容。请为这些工具启用确认，或者在不包含这些工具的客户端中使用此服务。
• 任何以你的用户身份运行的程序都可以启动辅助程序，并借助它读取你的邮件。这比授予 Terminal「完全磁盘访问权限」更安全，但并非毫无风险。
• 可选的正文索引是邮件的纯文本副本，任何以你的用户身份运行的程序都可以读取，无需「完全磁盘访问权限」。默认关闭；请参阅正文索引。

完整的威胁模型和两项剩余风险：SECURITY.md。

安装

Claude Code 和 Cowork，作为插件使用（在对话框中配置设置，每次发布时更新）：

/plugin install apple-mail-mcp --marketplace redpop/apple-mail-mcp

插件会运行下方 npm 包的相应版本。使用 npx -y @redpop/apple-mail-mcp setup 授予一次「完全磁盘访问权限」。

Claude Code，不使用插件（或任何可启动命令的客户端）：

claude mcp add apple-mail -- npx -y @redpop/apple-mail-mcp
npx -y @redpop/apple-mail-mcp setup

setup 会引导你完成授予「完全磁盘访问权限」。设置项为环境变量，详见配置。

Claude Desktop： 从最新发布版本下载 apple-mail-mcp-<version>.mcpb 并打开。Claude Desktop 会安装扩展并显示其设置页面；其中的设置与环境变量相同。首次在没有访问权限的情况下调用工具时，会打开「系统设置」和用于授权的 Finder 窗口。

每个发布版本都会列出 SHA256SUMS，并附带该捆绑包和辅助程序 zip 的构建来源证明。

从源代码安装

适用于开发，或运行尚未发布的更改。你需要 Xcode 命令行工具（用于 Swift），以及钥匙串中的 Apple Development 证书，才能让构建版本在重新构建后继续保留权限；没有证书时，构建会采用临时签名，并获得独立且权限较弱的身份。

git clone https://github.com/redpop/apple-mail-mcp.git
cd apple-mail-mcp
npm ci
npm run build           # TypeScript -> dist/
npm run build:helper    # Swift helper -> bin/Mail MCP Helper (Dev).app

然后为辅助程序授予「完全磁盘访问权限」（见下一节），并注册服务端：

claude mcp add apple-mail \
  -e APPLE_MAIL_HELPER_PATH="$PWD/bin/Mail MCP Helper (Dev).app" \
  -- node "$PWD/dist/index.js"

APPLE_MAIL_HELPER_PATH 用于让服务端指向本地构建版本。未设置时，服务端会在包内查找发布捆绑包 Mail MCP Helper.app，该捆绑包仅由发布流程生成。本地构建版本的名称为 "Mail MCP Helper (Dev)"（Apple Development 签名）或 "Mail MCP Helper (Ad hoc)"（无证书）。两者都使用各自的捆绑包 ID，因此绝不会影响发布版应用的权限。

构建脚本绝不会在 CI 之外使用 Developer ID 证书签名。

授予完全磁盘访问权限

macOS 会保护 ~/Library/Mail，且不会弹出对话框请求访问权限。只需为辅助应用授予一次权限：

1. 运行 setup（从源代码运行：APPLE_MAIL_HELPER_PATH="$PWD/bin/Mail MCP Helper (Dev).app" node dist/index.js setup；从 npm 运行：npx -y @redpop/apple-mail-mcp setup）。它会打开“系统设置”中的“隐私与安全性”>“完全磁盘访问权限”，在 Finder 中显示辅助应用，并等待权限生效。
2. 将 Finder 窗口中的 Mail MCP Helper 拖到列表中，然后将其打开。（本地构建的名称为“Mail MCP Helper (Dev)”。）也可以点击 +，按下 Cmd-Shift-G，然后粘贴 setup 打印的路径。
3. setup 会报告成功，并打印将服务添加到 Claude Code 的命令。

如果没有终端（例如使用 MCPB 捆绑包），首次工具调用被拒绝时，会自行打开“系统设置”和 Finder 窗口；每个服务进程只会打开一次，错误消息中也会列出相同的步骤。

说明：

• 权限归属于应用的 bundle id，而非其所在位置。移动或更新软件包后无需重新授予权限。
• 如果列表中显示“Mail MCP Helper”且已将其打开，但访问仍被拒绝，则该条目已失效。点击减号按钮将其移除，然后重新添加。
• 授予权限后无需重启。

更多情况：docs/troubleshooting.md。

配置

在服务的环境中设置这些变量，例如使用 claude mcp add -e NAME=value。无法通过工具参数更改这些变量。布尔值接受 true、false、1、0。空值视为未设置。无效值不会阻止服务启动；此后每次工具调用都会失败，并返回指出对应设置名称的 CONFIG_INVALID，且不会回退为“允许全部”。

服务会在启动时读取这些设置一次。更改后，请重启客户端。在 Claude Desktop 中，退出应用（Cmd-Q）并重新打开：关闭再开启扩展，或保存其设置，都不会停止正在运行的服务，因此旧设置仍会生效。

变量	默认值	含义
APPLE_MAIL_ACCOUNTS	空（所有账户）	以逗号分隔的允许列表。条目会与账户的 UUID、地址或名称匹配，且不区分大小写。多个账户使用同一名称时，都会匹配；请使用地址或 UUID 指定某个账户。
APPLE_MAIL_INCLUDE_JUNK	false	包含垃圾邮件角色的邮箱及其子文件夹。
APPLE_MAIL_INCLUDE_TRASH	false	包含废纸篓角色的邮箱及其子文件夹。
APPLE_MAIL_EXCLUDE_MAILBOXES	空	以逗号分隔的要隐藏的邮箱。条目可匹配邮箱名称（完全匹配，不区分大小写）或带 / 的路径。
APPLE_MAIL_SHOW_SECURITY_MAILS	false	显示被检测为安全邮件的消息，不隐藏正文或遮蔽主题。
APPLE_MAIL_BODY_SEARCH	true	允许在 search_messages 中使用 bodyContains。设为 false 时，使用它会导致 INVALID_INPUT 错误。
APPLE_MAIL_BODY_INDEX	false	在磁盘上构建邮件正文的全文索引，以便通过 bodyContains 搜索所有邮件。仅在启用 APPLE_MAIL_BODY_SEARCH 时生效。关闭此项后，索引会在下次启动时删除。
APPLE_MAIL_MAX_RESULTS	50	搜索 limit 的上限（1 到 100）。
APPLE_MAIL_MAX_BODY_CHARS	20000	get_message 中 maxChars 的上限（1000 到 100000）。
APPLE_MAIL_HELPER_PATH	未设置	仅用于开发：辅助应用捆绑包（Dev 或 Ad hoc）的路径。不接受使用正式版 bundle id 的捆绑包。
APPLE_MAIL_MCP_DEBUG	false	针对每个辅助请求向 stderr 写入一行：命令、耗时和结果代码，例如 apple-mail-mcp: search 42 ms ok。绝不记录有效负载或结果。

示例：仅使用工作账户，不包含名为 Archive 的邮箱。

claude mcp add apple-mail \
  -e [email protected] \
  -e APPLE_MAIL_EXCLUDE_MAILBOXES=Archive \
  -- npx -y @redpop/apple-mail-mcp

正文索引

没有索引时，bodyContains 会在搜索过程中解码邮件，因此一次调用最多检查最新的 2,000 封候选邮件，或耗时 3 秒。要找到几年前的邮件，可能需要翻很多页。启用 APPLE_MAIL_BODY_INDEX=true 后，服务会为邮件正文建立全文索引，一次调用即可搜索所有邮件，匹配结果、顺序和 matchContext 均与扫描相同。

• 磁盘空间： 每封邮件约 14 KiB。在测试邮箱中，121,000 封邮件占用 1.7 GiB。
• 构建时间： 每封邮件约 3 毫秒，120,000 封邮件不到 6 分钟。服务会在首次成功调用工具后于后台构建索引，并在重启后继续构建。工具调用优先。
• 完成之前， bodyContains 会像之前一样扫描，note 会说明构建进度。少于 3 个字符的词始终通过扫描搜索。
• 索引会自动保持最新： 每次正文搜索前和每分钟都会添加新邮件，每 30 分钟删除已删除的邮件，配置变更会在下次启动时应用。
• 位置： ~/Library/Application Support/apple-mail-mcp/body-index/，目录权限为 0700，文件权限为 0600，并从 Time Machine 备份中排除。要重建索引，请删除该目录。
• 关闭索引后， 服务会在下次启动时将其删除。
• 要求： 22 系列中的 Node 22.16 或更高版本，或 Node 24 及更高版本（用于支持 FTS5 的 node:sqlite）。不满足要求时，索引会保持关闭，搜索将扫描实时邮件。

doctor 会在 body-index 下显示状态。索引是邮件文本的副本，当前用户运行的任何程序都可以读取，无需完全磁盘访问权限。启用前请阅读 SECURITY.md。

工具

工具	功能
list_mailboxes	列出账户和可见邮箱，并显示总数、未读数及邮箱角色（收件箱、已发送、垃圾邮件等）。
search_messages	按发件人、收件人、主题、自由文本、邮箱、日期、未读、已标记、附件以及可选的正文文本进行最新优先搜索。支持使用游标分页。
get_message	获取一封邮件：标头、附件名称、纯文本正文，以及可选的引用回复移除功能。
get_thread	获取一个会话中的邮件，按时间从早到晚排列，不含正文。

这四个工具都标记为只读。参数、结果和错误代码：docs/tools.md。

诊断和错误报告

npx -y @redpop/apple-mail-mcp doctor        # from source: node dist/index.js doctor

doctor 会检查 macOS 版本、辅助程序签名、完全磁盘访问权限、数据库布局、有本地文件的邮件数量、邮箱角色、隐藏的已移除账户数量和已关闭 Mail 的账户数量、生效的设置，以及正文索引状态。默认输出不包含名称、地址或主题，因此可以直接粘贴到问题报告中。--verbose 会添加邮箱名称和账户标识符；--json 供机器使用；--schema 只会打印数据库指纹、缺失的列，以及 Mail 数据库的 CREATE TABLE 语句（仅结构，不含数据）。退出代码 1 表示至少有一项检查失败。

问题反馈

在 https://github.com/redpop/apple-mail-mcp/issues 提交问题，并附上 doctor 的输出。如果运行的 macOS 版本不是 27，请改为使用 doctor --schema 的输出提交架构报告：这是我们最有用的报告。安全问题请通过 GitHub Security Advisories 反馈，详见 SECURITY.md。

更多文档

• docs/tools.md：每个工具及其参数、结果和错误
• docs/architecture.md：工作原理及测量结果
• docs/troubleshooting.md：权限和数据库问题
• docs/exchange.md：关于 Exchange 账户的已知信息
• SECURITY.md：威胁模型和剩余风险
• docs/releasing.md：如何构建、签名和发布版本（维护者）

刻意不包含的功能

发送、回复、草稿、移动、删除、标记、附件内容、语义搜索、链接提取。只读服务更值得信赖。

隐私政策

本政策适用于通过 npm、GitHub releases 和 MCP Registry 发布的服务及其辅助应用。

收集的信息

作者和任何服务都不会收集信息。服务没有遥测、分析或崩溃报告功能，服务和辅助应用都不会打开网络连接。

在你的 Mac 上，服务只会读取其工具所需的内容：Mail 在 ~/Library/Mail 下的本地索引和邮件文件，以及 ~/Library/Accounts/Accounts4.sqlite 中邮件账户的名称和用户名。你的配置会限制读取范围（账户、垃圾邮件、废纸篓、排除的邮箱、安全邮件）。

使用和存储方式

只有在你的 AI 客户端调用工具时，才会读取数据；结果也只会返回给该客户端。服务会在 ~/Library/Application Support/apple-mail-mcp/ 下保留两类文件，目录权限为 0700，文件权限为 0600：

• state.json：上次成功访问 Mail 的时间，以及辅助应用的版本和校验和。不含邮件数据。
• 正文索引，仅当你设置 APPLE_MAIL_BODY_INDEX=true 时才会生成：配置设为可见的邮件正文全文副本，但绝不包含安全邮件。请参阅正文索引和 SECURITY.md。

设置 APPLE_MAIL_MCP_DEBUG=true 时，服务会针对每个请求向 stderr 写入一行日志，其中包含耗时和计数，但不含邮件内容。客户端会决定是否将这些输出保留在日志中。

与第三方共享

服务不会与任何人共享信息。你的 AI 客户端如何处理工具结果，受该客户端和模型提供商的隐私政策约束：云端托管的模型会收到客户端发送给它的结果。通过 npm 或 npx 安装或更新时，会根据 npm 的条款从 npm 注册表下载软件包。

保留期限

state.json 会在原位置覆盖，并一直保留到你将其删除。正文索引启用期间会保持最新；关闭后，它会在下次启动服务时删除。如需删除所有内容，请删除 ~/Library/Application Support/apple-mail-mcp/。服务绝不会更改或删除 ~/Library/Mail 下的任何内容。

联系方式

对本政策有疑问：请在 https://github.com/redpop/apple-mail-mcp/issues 提交 issue。安全问题：请按 SECURITY.md 所述私下报告。

许可证

MIT，详见 LICENSE。