Apple Mail MCP

Apple Mail MCP

唯一支持全覆盖正文搜索的 Apple Mail MCP 服务——在大型邮箱中也能可靠运行，而基于 AppleScript 的服务会超时。提供 8 个用于读取、搜索和提取邮件内容的工具。

阅读文档，查看完整指南。

快速开始

Claude Code（插件）

claude plugin marketplace add imdinu/apple-mail-mcp
claude plugin install apple-mail@imdinu

Claude Desktop（一键安装包）

从最新版本 下载 apple-mail-mcp-<version>.mcpb，然后双击。

插件和安装包都会通过轻量启动器运行已发布到 PyPI 的软件包（uvx → pipx → 私有 venv，使用可用的方式）——不包含 vendored 代码，行为与手动安装完全相同。它们使用 --watch 启动服务；请向启动应用（Claude Code / Claude Desktop）授予“完全磁盘访问权限”，以保持索引最新。

任意 MCP 客户端

pipx install apple-mail-mcp

添加到 MCP 客户端：

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

构建搜索索引（推荐）

# Requires Full Disk Access for Terminal
# System Settings → Privacy & Security → Full Disk Access → Add Terminal

apple-mail-mcp index --verbose

配置（可选）

apple-mail-mcp init   # writes ~/.apple-mail-mcp/config.toml

此操作会写入带注释的配置文件，你可以编辑它来设置默认值，例如主要账户或邮箱。每个键都有对应的 APPLE_MAIL_* 环境变量，也可以使用基于环境变量的配置。完整的配置结构和优先级规则请参阅配置。

工具

工具	用途
list_accounts()	列出电子邮件账户
list_mailboxes(account?)	列出邮箱
get_emails(filter?, limit?)	获取邮件——全部、未读、已标记、今天、最近 7 天
get_email(message_id)	获取单封邮件的完整内容和附件
search(query, scope?, before?, after?, highlight?)	搜索——全部、主题、发件人、正文、附件
get_email_links(message_id)	提取邮件中的链接
get_email_attachment(message_id, filename)	提取附件内容
get_attachment(message_id, filename)	已弃用——请使用 get_email_attachment()

性能

在真实的约 7.3 万封邮件邮箱上，与另外 6 个 Apple Mail MCP 服务进行了测试：

• 唯一支持全覆盖正文搜索的服务。 大多数竞品完全不支持正文搜索；唯一支持的竞品（BastianZim）只会实时扫描最近的 5000 封邮件——更早的邮件会被悄然漏掉。我们的 FTS5 索引覆盖整个邮箱。
• 单封邮件获取约需 3 毫秒，通过优先从磁盘读取 .emlx 实现（无需 JXA 往返）。
• list_accounts 约需 1 毫秒，列出 50 封邮件约需 5 毫秒，通过直接读取 Envelope-Index SQLite 实现（0.4+）——与 BastianZim/rusty/pl-lyfx 使用相同路径，并以 JXA 作为正确性回退方案。
• 主题搜索约需 7 毫秒，通过 FTS5 实现——在相同操作上可与原生 Rust 相媲美。
• 在 7.3 万封邮件的邮箱上，所有 6 项基准测试操作均可靠；基于 AppleScript 的服务会超时、抛出语法错误，或跳过不支持的操作。

配置

Apple Mail MCP 开箱即用。若要自定义默认设置，请运行 apple-mail-mcp init 以生成 config.toml 模板，或使用 相应的 APPLE_MAIL_* 环境变量。完整的配置架构以及 CLI > env > file > default 优先级，请参阅 配置文档。

也可以通过 MCP 客户端的启动配置按客户端覆盖环境变量：

{
  "mcpServers": {
    "mail": {
      "command": "apple-mail-mcp",
      "args": ["--watch"],
      "env": {
        "APPLE_MAIL_DEFAULT_ACCOUNT": "Work"
      }
    }
  }
}

CLI 用法

所有工具也都可作为独立的 CLI 命令使用（无需 MCP 服务）：

apple-mail-mcp search "quarterly report" --scope subject
apple-mail-mcp search "invoice" --after 2026-01-01 --limit 10
apple-mail-mcp read 12345
apple-mail-mcp emails --filter unread --limit 10
apple-mail-mcp accounts
apple-mail-mcp mailboxes --account Work
apple-mail-mcp extract 12345 invoice.pdf

所有命令均输出 JSON。生成一个用于通过 CLI 访问的 Claude Code 技能：

apple-mail-mcp integrate claude > ~/.claude/skills/apple-mail.md

开发

git clone https://github.com/imdinu/apple-mail-mcp
cd apple-mail-mcp
uv sync
uv run ruff check src/
uv run pytest

许可证

GPL-3.0-or-later