Mail.app

mail-mcp

MCP 服务，让 Claude（及其他 MCP 宿主）能够全面访问 macOS 上的 Mail.app，可在 Mail.app 配置的所有账户（iCloud、Exchange、IMAP 等）中搜索、阅读、发送、回复、标记、移动邮件等。

前置条件

• macOS（需要 Mail.app）
• Node.js 20+
• MCP 宿主：Claude Desktop、Amazon Quick，或任何 stdio MCP 客户端

安装

Claude Desktop — 一键安装（推荐）

1. 从最新版本下载 mail-mcp.mcpb
2. 双击 .mcpb 文件 — Claude Desktop 会自动安装
3. 授予所需的 macOS 权限（见下文）

手动安装 / Amazon Quick / 其他宿主

npx @p-l-ta/mail-mcp

或全局安装：

npm install -g @p-l-ta/mail-mcp
mail-mcp

将 MCP 宿主指向 mail-mcp 可执行文件（stdio 传输）。配置示例：

{
  "mcpServers": {
    "mail-app": {
      "command": "npx",
      "args": ["@p-l-ta/mail-mcp"]
    }
  }
}

所需的 macOS 权限

向运行 MCP 宿主的应用程序（Claude Desktop、Amazon Quick 等）授予以下权限：

权限	授予位置
完全磁盘访问权限	系统设置 → 隐私与安全性 → 完全磁盘访问权限
自动化 → Mail	系统设置 → 隐私与安全性 → 自动化

MCP 服务进程会继承启动它的宿主应用程序的权限。

工具

工具	描述
search_emails	通过 Envelope Index 数据库，使用丰富的筛选条件搜索邮件
read_email	根据 RFC message-id 读取邮件的完整正文
list_accounts_and_mailboxes	列出所有已配置的账户和邮箱，并显示未读数量
list_recent	列出特定邮箱中的近期邮件
list_senders	按发件人分组汇总邮件数量和未读数量
send_email	从某个已配置账户发送新邮件
reply_to_email	根据 RFC message-id 回复现有邮件
set_message_flags	设置邮件的已读和/或标记状态
move_email	将邮件移至其他邮箱
trash_email	将邮件移至“已删除邮件”
create_mailbox	在账户中创建新邮箱/文件夹
bulk_mark_read	将邮箱中和/或来自某个发件人的所有邮件标记为已读
get_unsubscribe_link	从邮件的标头和正文中提取取消订阅 URL
empty_mailbox	一次性删除邮箱中的所有邮件（垃圾邮件、废纸篓等）

工作原理

• 搜索与阅读 — 直接查询 Mail 自带的 Envelope Index SQLite 数据库，快速获取所有账户中的结构化结果
• 操作（发送、回复、标记、移动、移至废纸篓）— 通过 AppleScript 自动化操作 Mail.app，因此即使账户的邮件未存储为本地文件，也能正常使用

开发

npm install
npm run dev          # tsx watch — live reload
npm test             # vitest unit tests
npm run build        # compile TypeScript → dist/
npm run mcpb         # build Claude Desktop extension → build/mail-mcp.mcpb

交互式 MCP 测试：

npm run build
npx @modelcontextprotocol/inspector node dist/server.js

隐私政策

mail-mcp 是一个本地 MCP 服务，完全在 Mac 上运行。它没有后端、不收集遥测数据，也不会自行发起网络请求。

访问的内容：

• Mail.app 的 Envelope Index 数据库（~/Library/Mail/）— 只读，用于搜索查询
• 通过 AppleScript 访问 Mail.app — 用于读取邮件正文、发送邮件、标记、移动和移至废纸篓

不会执行的操作：

• 在 Mac 之外收集、存储或传输任何数据
• 连接到任何外部服务或 API
• 在任何位置记录邮件内容

所有邮件数据都保留在你的设备上，并仅作为正常的工具响应内容传递给 MCP 宿主（Claude Desktop 或其他客户端）。你可以精确控制 Claude 能调用哪些工具。

许可证

MIT