Apple Mail

Apple Mail MCP

适用于 macOS 上 Apple Mail 的 MCP 服务。

提供对邮箱的访问，以及邮件搜索、阅读和撰写功能。在让 Agent 能够搜索、阅读、撰写和发送邮件的同时，继续以 Mail 作为系统记录来源。

适用场景

• 仅使用 Mail 的工作流
• 相比一体化服务，权限控制更严格
• 通过原生 Mail 应用撰写和发送邮件的工作流

功能

• 列出邮箱
• 搜索和阅读邮件
• 创建草稿并发送邮件
• 回复、转发、标记为已读／未读、移动和删除邮件
• 为上下文受限的客户端提供工具发现辅助功能 search_tools 和 get_tool_info
• 线程辅助功能：mail_get_thread、mail_reply_latest_in_thread、mail_archive_thread
• 邮箱资源和面向回复的提示词
• 健康状态和权限检查：mail_health、mail_permission_guide、mail_recheck_permissions

工具

mail_health、mail_permission_guide、mail_recheck_permissions、mail_list_mailboxes、mail_search_messages、mail_get_message、mail_get_thread、mail_compose_draft、mail_send_message、mail_reply_message、mail_forward_message、mail_mark_message、mail_move_message、mail_delete_message、mail_reply_latest_in_thread、mail_archive_thread、mail_list_prompts、mail_get_prompt，以及发现辅助工具 search_tools 和 get_tool_info。

在此 Mac 上安装

uvx apple-mcp-mail

git clone https://github.com/JonathanRReed/Apple-MCPs.git
cd Apple-MCPs
uv sync --all-packages

在 AI Agent 中安装

{
  "mcpServers": {
    "apple-mail": {
      "command": "uvx",
      "args": ["apple-mcp-mail"],
      "env": {
        "APPLE_MAIL_MCP_SAFETY_PROFILE": "safe_manage",
        "APPLE_MAIL_MCP_VISIBLE_DRAFTS": "true"
      }
    }
  }
}

claude mcp add --transport stdio --scope user apple-mail -- uvx apple-mcp-mail

安全模式

通过 APPLE_MAIL_MCP_SAFETY_PROFILE 设置模式：

• safe_readonly，仅可阅读和搜索
• safe_manage，可阅读、创建草稿、回复、转发为草稿、标记、移动、删除和归档邮件线程；禁止发送新邮件。回复会立即发送，因此此模式仍可能向线程中已有的联系人发送邮件。转发可以发送到任意地址，因此会在 Mail 中保存为未发送的草稿，供用户审核；切换到 full_access 可直接发送转发邮件
• full_access，可使用本仓库中完整的 Mail 工具集，包括发送新邮件

删除或归档邮件无需从 safe_manage 切换到 full_access。

默认模式取决于服务的安装方式：

要在 Claude Desktop 中更改此设置，请打开 Settings > Extensions，选择 Apple Mail，点击 Configure，然后设置“Mail safety mode”。在其他客户端中，将 APPLE_MAIL_MCP_SAFETY_PROFILE 设置在服务的 env 块中，然后重启客户端。如果某个工具被阻止，其错误信息会指出相关设置及应使用的值。值无效或为空时，将选择 safe_readonly；mail_health 会在 safety_mode_warning 中说明原因。

附件默认关闭，除非你将 APPLE_MAIL_MCP_ALLOWED_ATTACHMENT_ROOT（bundle 设置：“Mail attachment folder”）设为专用文件夹。

传输方式

stdio 是默认且推荐的传输方式。设置 APPLE_MAIL_MCP_TRANSPORT=streamable-http（可选设置 APPLE_MAIL_MCP_HOST 和 APPLE_MAIL_MCP_PORT）即可改用 Streamable HTTP。

macOS 权限

• 需要获得对 Mail 的自动化访问权限

排查移动／删除错误

问题 #23 报告了包含 item ... of every message/mailbox/account 的 AppleScript -1728 错误。现在，移动和删除脚本会将账户／邮箱匹配项解析为具体对象，并通过 Mail 的数字 ID 在原邮箱中查找邮件，而不是保留位置式 repeat 循环引用。遇到目标不存在或匹配不明确时，脚本会拒绝执行，且不会自动重试修改操作。

请使用 mail_search_messages 返回的 message_id，不要更改。如果邮件已移动，或者该 ID 在原邮箱中无法解析，请重新搜索，而不是编辑 ID。ACCOUNT_AMBIGUOUS、MAILBOX_AMBIGUOUS 及其对应的 TARGET_ 错误，表示配置的名称无法唯一确定所请求的对象；请先明确选择，再重试。其他原生错误（包括权限错误）仍会显示。

归档时，请调用 mail_list_mailboxes 并传入实际的目标名称。不要假设账户中一定存在名为 Archive 的邮箱，尤其是在使用本地化标签或嵌套的 Gmail 标签时。跨账户移动时，请明确指定目标账户。

mail_health 成功响应并不能验证移动／删除操作的完整往返流程。验证新安装时，请使用主题唯一的临时邮件：先搜索，再执行一次所需操作，并在 Mail 中确认结果。归档邮件会逐封移动，并非事务性操作；发生错误后，请先检查 Mail，再重试整个邮件会话。

升级后请重启 MCP 客户端。GitHub 上合并的修复，在包含该修复的软件包版本发布之前，不会出现在通过 PyPI 安装的 uvx 版本中。可按照上方的克隆说明测试源码检出版本；统一服务请使用 Apple-Tools-MCP/start.sh。如果错误仍然存在，请报告已安装的版本或源码提交、macOS 版本、操作以及已删去敏感信息的错误文本。请勿发布邮件正文或私人账户详情。

启动检查清单

• 将 uvx apple-mcp-mail（或克隆项目中的 AppleMail-MCP/start.sh）添加到 MCP 客户端
• 重新加载或重新连接客户端，以便将 Mail 工具集加载到上下文中
• 首先调用 mail_health，确认服务可访问
• 如果 Mail 自动化受到阻止，请调用 mail_permission_guide
• 更改 macOS 权限后，请调用 mail_recheck_permissions

提示词说明

• 如果用户说的是某个人而不是电子邮件地址，请先运行 Contacts，再发送或回复。
• tools/list 会返回完整的 Mail 工具列表。上下文受限的客户端可以先调用 search_tools，再对计划调用的确切 Mail 工具调用 get_tool_info。
• mail_search_messages 需要查询字符串。可以使用发件人、主题片段或通配符 *。
• 传入 account（mail_list_mailboxes 返回的账户名称）可搜索单个账户。如果不传入此参数，系统会按照 Mail 中的顺序搜索账户，并在收集到 limit 条结果后停止，因此，若第一个账户邮件较多，就可能填满整个结果集，并隐藏其他账户中同名的邮箱。
• 没有列出所有近期邮件的端点。
• 用户指的是对话而非单条邮件时，请使用 mail_get_thread。
• 需要由 Agent 回复对话中的最新邮件时，请使用 mail_reply_latest_in_thread。
• 用户想要整理整个对话，且预期使用“归档”邮箱时，请使用 mail_archive_thread。
• 如果用户可能指的是短信或电子邮件，请先询问一次，再选择 Messages 或 Mail。
• Mail 必须使用特定身份发送邮件时，请在 from_account 中传入准确的发件人电子邮件地址。
• from_account 通过 Mail 自身的 sender 属性生效（格式为 Full Name <address>；名称中包含逗号或引号时需加引号），无需额外的 macOS 权限。只有 Mail 不接受该设置时，服务才会回退为通过 System Events 选择“发件人”弹出菜单；此时还需要授予 System Events 的自动化权限，以及运行服务的进程的辅助功能权限。
• 每次 AppleScript 调用都受 APPLE_MAIL_MCP_SCRIPT_TIMEOUT_SECONDS 限制（以整秒计，默认值为 120，最小值为 5；无效值或小于最小值的值会使用默认值），因此，待处理的 macOS 权限请求会显示为错误，而不会导致请求挂起。默认值为缓慢但合理的搜索预留了足够时间：在一个含有 4,900 条邮件的 Exchange 邮箱中，按主题或发件人搜索耗时约 56 秒。
• 如果 mail_send_message、mail_reply_message、mail_reply_latest_in_thread 或发送邮件的 mail_forward_message 超时，结果会是 SEND_STATUS_UNKNOWN，而不是发送失败：Mail 可能已经发送了邮件。重试前，请检查该账户的“已发送”邮箱（将 mailbox 设为 Sent Messages 调用 mail_search_messages，或使用 mail_list_mailboxes 显示的名称，例如 Sent Items），否则邮件可能会发送两次。

相关内容

• Apple-Tools-MCP

附件访问

默认情况下，文件附件处于禁用状态。设置 APPLE_MAIL_MCP_ALLOWED_ATTACHMENT_ROOT 为你选择的目录（例如 ~/Documents/Mail Attachments）即可启用附件。此设置适用于 草稿和发送操作，包括通过 Apple Tools 进行的调用。服务会解析符号链接，并且只接受该目录内的普通文件。目录外的文件、 目录本身以及包含附件传输分隔符的路径都会被拒绝。不带附件的 Mail 操作会继续使用现有的安全配置。