Apple Mail MCP Server

一个为 Apple Mail 提供编程式访问的 MCP 服务器，使 Claude 等 AI 助手能够在 macOS 上读取、发送、搜索和管理电子邮箱。

⚠️ Pre-1.0 —— 预计会有破坏性变更。 随着项目不断成熟，MCP 工具面（工具名称、参数、返回结构）仍在不断演进。请固定使用特定版本（例如 apple-mail-mcp==0.8.1），并在升级前查阅 CHANGELOG。

工具（23）、

核心： list_mailboxes、search_messages、get_messages、update_message 草稿生命周期： create_draft、update_draft、delete_draft 邮箱 CRUD： create_mailbox、update_mailbox、delete_mailbox 附件与管理： save_attachments、delete_messages 发现与规则： list_accounts、list_rules、get_thread、create_rule、update_rule、delete_rule 模板： list_templates、get_template、save_template、delete_template、render_template

完整的参数与返回结构文档请参阅 docs/reference/TOOLS.md。

Related MCP server: apple-mail-mcp

前提条件

• macOS 10.15（Catalina）或更高版本

• Python 3.10 或更高版本

• Apple Mail 已配置至少一个账户

• uv（推荐）或 pip

安装

# From source (recommended for development)
git clone https://github.com/s-morgan-jeffries/apple-mail-mcp.git
cd apple-mail-mcp
uv sync --dev

配置

将以下内容添加到 Claude Desktop 配置文件（~/Library/Application Support/Claude/claude_desktop_config.json）中：

{
  "mcpServers": {
    "apple-mail": {
      "command": "uv",
      "args": ["--directory", "/path/to/apple-mail-mcp", "run", "python", "-m", "apple_mail_mcp.server"]
    }
  }
}

权限

首次运行时，macOS 会提示是否允许自动化访问。请在以下位置授予权限： System Settings > Privacy & Security > Automation > Terminal（或你的 IDE 开发环境）

可选：通过 IMAP 实现更快的搜索

search_messages 开箱即用，基于 AppleScript。对于大型邮箱（数千封邮件），AppleScript 的 whose 子句每次查询可能需要 1–5 秒。若想要更快的服务器端搜索，您可以为每个账户启用 IMAP 委派，只需使用一条钥匙串条目即可。

How it works. 的原理。 如果账户存在钥匙串条目，服务器会使用 IMAP（快速的服务器端 SEARCH）。否则——或者遇到任何 IMAP 错误（离线、密码错误、请求超时）时——会静默回退到 AppleScript。功能从未缺失，你只会获得提升：只是配置了 IMAP 且可访问时，才能提速。无需配置标志，也无需环境变量；钥匙串条目的存在本身即视为选择启用。

每个账户的配置，一次性完成。

1．在当前服务提供商的网站上生成应用专用密码。流程因提供商而异：

• iCloud： appleid.apple.com/account/manage → App 专用密码。要求您的 Apple ID 已启用 2FA 验证（默认为开启）。

• Gmail： myaccount.google.com/apppasswords。要求您的 Google 账户已启用两步验证。

• Yahoo / Fastmail / AOL： 在提供商的账户安全设置中生成应用专属密码。

2.运行 setup-imap 子命令。它会提示输入密码（不出现在输入回显中），写入钥匙串条目，并通过连接到验证：

apple-mail-mcp setup-imap --account iCloud

请按 Mail.app 中显示的名称完全替换账户名——即 Mail.app 中的标签名（例如 iCloud 等Gmail、`"Yahoo!""）。该 CLI 会：

• 从 Mail.app 查询账户的主邮箱地址（可用 --email 覆盖），

• 通过 getpass 提示输入，因此密码不会遗留在 shell 历史（即不再出现于 shell 历史中），

• 在钥匙串中写入 apple-mail-mcp.imap.<account>（幂等——用新密码重新运行会更新已有条目），

• 建立 IMAP 连接，并执行真实的 LOGIN 以确认密码有效。如果不成功，将回滚钥匙串条目，以便继续重试，同时不会留下损坏条目。

3.如果接下来被 IMAP 支持的一句话操作中出现一次性提示："security wants to use the 'login' keychain"，请点击 Always Allow。

若日后需要移除该条目：apple-mail-mcp setup-imap --account iCloud --uninstall。

验证该配置。 setup-imap 命令会替你完成验证。若想事后抽查：

uv run python -c "from apple_mail_mcp.mail_connector import AppleMailConnector; \
    print(AppleMailConnector().search_messages(account='<ACCOUNT_NAME>', limit=1))"

IMAP能够正常工作时，调用约 1 秒内返回。如果它记录了关于回退的 WARNING（使用 --log-level=DEBUG 可见），请检查账户名称是否与 Mail.app 中的账户名称完全匹配，以及钥匙串条目中的邮箱是否与 email addresses of account 返回的邮箱一致。

目前已知的服务商差异。

• iCloud： IMAP 服务器接受 @icloud.com / @me.com 别名作为 LOGIN 用户名，而不是 Apple ID 邮箱。因此服务器（和 setup函数也是）会读取来自 Mail.app 的 email addresses of account 邮箱地址。

• Yahoo： 应用英文专用密码已被逐步弃用；部分账户可能无法显示该选项。若 Yahoo 的账户安全页面未提供该选项，则该账户无法设置 IMAP，只能走 AppleScript 路径。

• Gmail： 需要先启用两步验证。如果您的 Google Workspace 管理员在租户级别禁用了应用专用密码，则无法为该账户设置 IMAP。

• Gmail 里的主线程检索——是否在 IMAP 中显示 All Mail 的权衡。 find_thread_members（线程感知查询的内部实现）在 IMAP 暴露 [Gmail]/All Mail 时速度最快——该路径约 5 次往返，与邮箱数量规模无关。许多用户会隐藏 All Mail（通过 邮箱Settings → Forwarding and POP/IMAP → Folder 大小限制 → “Do not show in IMAP"），因为 All Mail 邮只会重复出现每封邮件一次。当隐藏不可用时，连接器会回退到按邮箱的 X-GM-THRID 迭代（这仍比通用 BFS 快约 6 倍，但与标签数量成正比——在92个标签的账户上约需 25 秒）。想获取最佳速度，就显示 All 邮箱；更偏好清爽的 IMAP 文件夹列表，则保持隐藏。

写入操作related (create_draft、update_draft，包括 send_now=true 的发送路径）无论 IMAP 的配置情况，都会使用 AppleScript —— 这些操作需要 Mail.app 的撰写界面。

开发

# Setup
uv sync --dev

# Common commands
make test              # Run unit tests
make lint              # Lint with ruff
make typecheck         # Type check with mypy
make check-all         # All checks (lint, typecheck, test, complexity, version-sync, parity)
make coverage          # Coverage report
make test-integration  # Integration tests (requires Mail.app)

# Validation scripts
./scripts/check_version_sync.sh          # Version consistency
./scripts/check_client_server_parity.sh  # Connector-server alignment
./scripts/check_complexity.sh            # Cyclomatic complexity
./scripts/check_applescript_safety.sh    # AppleScript safety audit

分支规范

{type}/issue-{num}-{description} —— 例如 feature/issue-42-thread-support

架构

server.py (FastMCP tools — thin orchestration)
  -> mail_connector.py (AppleScript bridge — domain logic)
     -> subprocess.run(["osascript", ...])
        -> Apple Mail.app

• server.py —— MCP 工具注册、输入验证、响应格式化

• mail_connector.py —— 所有 AppleScript 生成与执行

• security.py —— 输入清理、审计日志记录、确认流程

• utils.py —— 纯函数：转义、去引号、验证

• exceptions.py —— 类型化异常层级

安全性

• 仅本地执行（无云端处理）

• 使用现有的邮件应用中已有账户逻辑（无凭据保存）

• 所有输入清洗后进行 AppleScript 转义

• 破坏性操作需要确认

• 操作审计日志

• 策略见 SECURITY.md ，详细分析见 docs/SECURITY.md

贡献

详见 CONTRIBUTING.md ，涵盖开发流程、代码规范与 PR 流程。

许可

MIT