Apple Mail MCP

apple-mail-mcp

这是让 Claude（或任何大模型）访问 Apple Mail 和 iCloud 的唯一方式。

Gmail 和 Outlook 都有 API，iCloud 却没有。如果你是 Mac 用户，邮件都在 Apple Mail 中——无论是 iCloud、iCloud+，还是通过 Apple Mail 同步的其他账户——都没有可供大模型调用的 Web API。此服务使用你本机上的 AppleScript 弥合了这一差距。

它让 Claude 可以全面控制 Apple Mail：通过自然语言读取、搜索、撰写、回复、移动、标记和删除邮件，直接操作你的真实收件箱，无需经过云端中介。

此服务通过 osascript 基于 AppleScript 构建，并可选提供 MailKit 扩展，用于实时接收新邮件事件。

---

工具

工具	描述
list_folders	列出所有账户及其邮箱
create_folder	在账户中创建新邮箱／文件夹（幂等）
list_emails	分页列出邮箱中的邮件（按时间从新到旧）
get_email	读取邮件的完整标头和正文
search_emails	跨邮箱按发件人、主题和日期范围筛选
compose_email	创建草稿或立即发送新邮件
reply_email	回复邮件，打开为草稿或立即发送
move_email	将邮件移动到任意邮箱
move_matching	将所有符合筛选条件的邮件批量移动到某个邮箱
archive_email	移动到 Archive（iCloud）或 All Mail（Gmail）
move_to_junk	移动到 Junk（iCloud）或 Spam（Gmail）
flag_email	设置或清除邮件标记
mark_read	将邮件标记为已读或未读
delete_email	移动到 Deleted Messages（iCloud）或 Trash（Gmail）
create_rule	创建原生 Mail 规则，将发件人域名归档到文件夹（也可选择整理已有邮件）
list_rules	列出所有 Mail 规则及其目标文件夹和匹配的发件人域名
delete_rule	按名称删除 Mail 规则
get_pending_events	从 MailKit 桥接程序获取实时新邮件事件并清空队列
summarize_email	通过本地 AI 用 2-3 句话概述邮件
classify_email	通过本地 AI 按类别、优先级和是否需要采取行动进行分类
draft_reply	通过本地 AI 起草回复正文（发送前请审核）
triage_inbox	对最多 20 封邮件进行批量分类，并按优先级排序

---

要求

• macOS（已在 Sonoma／Sequoia／macOS 26 上测试）
• Apple Mail 已打开并配置至少一个账户
• Node.js 18+
• LM Studio（可选）——用于本地 AI 工具；任何兼容 OpenAI 的服务端均可

---

安装

npx（推荐）

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

{
  "mcpServers": {
    "apple-mail": {
      "command": "npx",
      "args": ["-y", "@jdot6/apple-mail-mcp"]
    }
  }
}

重启 Claude Desktop，然后询问：“我的邮件中有哪些文件夹？”

引导脚本

克隆此仓库、构建项目并自动修改 Claude 配置：

curl -fsSL https://raw.githubusercontent.com/jayvee6/apple-mail-mcp/master/install.sh | bash

手动安装

git clone https://github.com/jayvee6/apple-mail-mcp.git
cd apple-mail-mcp
npm install && npm run build

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

{
  "mcpServers": {
    "apple-mail": {
      "command": "/opt/homebrew/bin/node",
      "args": ["/path/to/apple-mail-mcp/dist/index.js"]
    }
  }
}

使用 which node 获取 Node 二进制文件的完整路径。重启 Claude Desktop。

自动化权限

首次使用邮件工具时，macOS 会询问是否允许 node 控制 Mail。点击 允许。如果不小心拒绝了，请前往 系统设置 → 隐私与安全性 → 自动化，为你的终端或 Node.js 运行时重新启用权限。

---

本地 AI（可选）

AI 工具可通过 LM Studio 或任何兼容 OpenAI 的服务运行任意本地 LLM。使用默认配置时，邮件数据不会离开你的设备。

在 claude_desktop_config.json 中通过环境变量进行配置：

{
  "mcpServers": {
    "apple-mail": {
      "command": "npx",
      "args": ["-y", "@jdot6/apple-mail-mcp"],
      "env": {
        "APPLE_MAIL_AI_PROVIDER": "lmstudio",
        "APPLE_MAIL_AI_ENDPOINT": "http://localhost:1234",
        "APPLE_MAIL_AI_MODEL": "gemma-4-it"
      }
    }
  }
}

变量	默认值	说明
APPLE_MAIL_AI_PROVIDER	lmstudio	lmstudio | openai | foundation | none
APPLE_MAIL_AI_ENDPOINT	http://localhost:1234	AI 服务的基础 URL
APPLE_MAIL_AI_MODEL	gemma-4-it	模型标识符
APPLE_MAIL_AI_API_KEY	(none)	远程提供方的 Bearer 令牌
APPLE_MAIL_AI_ENRICH_EVENTS	(off)	设置为 1，以自动分类新的邮件事件
APPLE_MAIL_AI_ALLOW_REMOTE	(off)	设置为 1，以允许使用非 localhost 的 AI 端点

隐私提示： 如果将 APPLE_MAIL_AI_ENDPOINT 指向远程服务（例如 OpenAI），完整邮件内容将发送到该服务。服务默认会阻止此操作——你必须设置 APPLE_MAIL_AI_ALLOW_REMOTE=1，以确认并启用此功能。

---

配套技能 — 邮件撰写审阅

此仓库中的 skill/SKILL.md 文件是一项 Claude 技能，可为 Claude 撰写的每封邮件添加多 Agent 审阅流水线。打开撰写窗口前，Claude 会让草稿经过五个并行审阅器的检查：

审阅器	检查内容
水文检测器	AI 写作痕迹、填充语、企业套话
文案编辑	拼写、语法、标点
主动语态	将被动结构改为主动结构
正确性	名称、日期、事实是否符合上下文
逻辑与清晰度	请求是否明确、结构是否合理、长度是否恰当

仲裁器会综合审阅结果，生成修订后的草稿和变更日志。Claude 会向你展示结果，并等待你批准后再在 Mail 中打开草稿。LLM 撰写的邮件绝不会使用 send: true——你需要自行从 Mail 发送。

要在 Claude Code 中安装此技能：

/skill install /path/to/apple-mail-mcp/skill/SKILL.md

---

工作原理

Claude ──stdio──▶ MCP server (Node.js)
                      │
                      ├── runScript("list_messages", [...args])
                      │        │
                      │        └── osascript scripts/applescript/list_messages.applescript
                      │                 │
                      │                 └── Apple Mail (AppleScript dictionary)
                      │
                      └── HTTP bridge  ◀── MailKit extension (optional)
                          localhost:27182

邮件引用是组合键，可在不依赖易变的整数索引的情况下唯一标识一封邮件：

{account}::{mailbox}::{RFC 2822 Message-ID}

e.g.  iCloud::INBOX::<[email protected]>

每个列表或搜索结果都包含一个 message_ref。针对单封邮件操作的工具（get_email、reply_email、move_email 等）会将此引用作为输入。账户和邮箱组件会将 AppleScript 查找范围限定在正确的邮箱中；RFC 2822 ID 则是稳定标识符。Mail 的 whose 谓词使得针对单封邮件的查找复杂度为 O(1)。

---

MailKit Bridge（可选）

MailKitBridge/ 目录包含一个 Xcode 项目，其中的 Mail 扩展会在收到新邮件时向 localhost:27182/event 发送本地 HTTP POST 请求。这会实时填充 get_pending_events，无需手动轮询。

无论扩展是否安装，MCP 服务都会在启动时启动 HTTP 监听器；若扩展未安装，则不会执行任何操作。

要构建并安装该扩展：在 Xcode 中打开 MailKitBridge/MailKitBridge.xcodeproj，构建 MailKitBridgeApp scheme，运行应用一次以注册扩展，然后在 Mail → Settings → Extensions 中启用扩展。

---

开发

npm run dev          # run with tsx (no build step)
npm run build        # compile TypeScript → dist/
npm run typecheck    # type-check without emitting

AppleScript 文件位于 scripts/applescript/ 中，并通过 osascript 直接调用——无需编译。你可以单独测试这些文件：

osascript scripts/applescript/list_folders.applescript
osascript scripts/applescript/list_messages.applescript "iCloud" "INBOX" "1" "5"

---

安全说明

• HTTP 桥接仅绑定到 127.0.0.1 — 无法从本机外部访问。
• 使用前会通过 path.basename() 验证脚本名称，以防止路径遍历。
• 参数通过 execFile 传递给 osascript（而非 shell），因此不存在 shell 注入风险。
• AppleScript 调用会在 30 秒后超时，以防 Mail 冻结或显示权限提示时一直挂起。
• AI 提示词中的电子邮件内容会用 XML 分隔符（<email>…</email>）括起来，以防邮件正文中的提示词注入攻击。
• 默认会阻止远程 AI 端点 — 设置 APPLE_MAIL_AI_ALLOW_REMOTE=1，即可明确选择将电子邮件数据发送到设备之外。

---

许可证

MIT