Apple Tools (Unified)

Apple-Tools-MCP

适用于 macOS 上 Apple 应用的统一 MCP 服务。

一个入口即可使用 Mail、Calendar、Reminders、Messages、Contacts、Notes、Shortcuts、Files、System 和 Maps。此服务封装了各个独立服务，并提供统一的 MCP 接口。

功能

• 跨多个 Apple 应用读取上下文
• 在所有应用中执行统一操作
• 用于日程规划、通信事项分类和会议准备的提示词
• 为邮件、日历、提醒事项、笔记和通信路由设置持久默认值
• 为始终采用特定路由方式的联系人设置个性化偏好
• 用于通信路由、邮件归档、后续事项记录和协作摘要的辅助工作流
• 在同一位置使用邮件线程辅助工具和 Contacts 联系方式编辑功能
• 对可撤销的操作进行预览、审计和撤销
• 在指定根目录范围内使用 Files 处理附件和文档的工作流
• 利用最前台应用、剪贴板、通知、正在运行的应用以及与助手相关的 macOS 设置，构建感知 System 状态的工作流
• 提供准确的 Focus 上下文和组合系统快照，用于简报和路由
• 显式写入 macOS 设置，包括外观、Finder、Dock 和关键辅助功能偏好
• 当原生应用域 MCP 无法直接完成任务时，提供有限范围的 GUI 回退工具
• 通过 Apple Files 支持感知 Finder 的文件工作流、Finder 标签、最近访问的位置和 iCloud Drive
• 使用 Apple Maps 搜索地点并估算路线，支持感知出行的工作流
• 提供每日简报、每周简报和通信事项分类工具
• 通过 apple_list_prompts 和 apple_get_prompt 回退获取提示词
• 一个安装目标，无需分别配置十个服务

适用场景

• 跨多个 Apple 应用的个人助手工作流
• 跨应用操作（例如，同时使用 Calendar 和 Reminders）
• 无需分别接入各个独立 MCP，简化设置

工具发现

Apple-Tools-MCP 通过 tools/list 暴露完整的工具集，并提供 readOnlyHint/destructiveHint 注释和结构化输出架构——现代客户端会自行延迟加载大型工具集。对于上下文受限的客户端：

• search_tools 可按名称、别名和域标签查找工具
• get_tool_info 可按需加载一个工具的完整架构和示例
• 生成的代码模式封装导出在 generated/tool_wrappers/python 下

在这台 Mac 上安装

uvx apple-tools-mcp

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

在 AI Agent 中安装

{
  "mcpServers": {
    "apple-tools": {
      "command": "uvx",
      "args": ["apple-tools-mcp"],
      "env": {
        "APPLE_MAIL_MCP_SAFETY_PROFILE": "safe_manage",
        "APPLE_CALENDAR_MCP_SAFETY_MODE": "safe_manage",
        "APPLE_REMINDERS_MCP_SAFETY_MODE": "safe_manage",
        "APPLE_FILES_MCP_ALLOWED_ROOTS": "/Users/you/Desktop,/Users/you/Documents,/Users/you/Downloads,/Users/you/Library/Mobile Documents/com~apple~CloudDocs",
        "APPLE_FILES_MCP_SAFETY_MODE": "safe_manage",
        "APPLE_SYSTEM_MCP_SAFETY_MODE": "safe_manage",
        "APPLE_CONTACTS_MCP_SAFETY_MODE": "safe_manage",
        "APPLE_NOTES_MCP_SAFETY_MODE": "full_access",
        "APPLE_MESSAGES_MCP_SAFETY_MODE": "full_access",
        "APPLE_SHORTCUTS_MCP_SAFETY_MODE": "full_access"
      }
    }
  }
}

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

• 覆盖所有应用的健康检查和概览工具
• 跨应用提示词
• 来自 Mail、Calendar、Reminders、Messages、Contacts、Notes、Shortcuts、Files、System 和 Maps 的委托工具
• 建议和权限指南
• Files、System 和 Maps 资源与提示词
• Focus、系统上下文、在 Finder 中显示、打开文件和文件标记的统一封装
• 偏好设置工具：获取、检测和更新默认设置及联系人偏好
• 通信工具：准备、发送、预览
• 工作流：归档、使用默认值创建提醒和笔记、预览这些默认值写入、记录后续事项、预览后续事项记录，以及总结活动协作
• 启动加固工具：严格的 Maps 封装、重复联系人检测、摘要文件夹辅助工具，以及 Shortcut 桥接路由
• 审计工具：列出近期操作并撤销
• 简报：每日、每周和通信分类处理
• 提示词回退：apple_list_prompts 和 apple_get_prompt
• Mail 会话工具：获取、回复、归档
• Contacts 修改：使用带标签的方法创建、更新和删除
• Calendar 和 Messages 权限诊断
• Messages 中显示联系人姓名：如果已获准访问 Contacts，参与者和发件人会附带 display_name / contact_id；每条 Messages 响应都会通过 contact_names_status（ok、permission_denied、unavailable）说明缺少姓名的原因。只有完全匹配的联系人才会显示姓名；不同区号的号码不会借用联系人的姓名。
• 启动和恢复：apple_health、apple_permission_guide、apple_recheck_permissions

助手默认设置

Apple-Tools-MCP 可以保存一个轻量级助手状态文件，其中包含以下默认设置：

• 默认邮件帐户
• 默认归档邮箱
• 默认日历
• 默认提醒事项列表
• 默认备忘录文件夹
• 首选通信渠道：messages、mail 或 auto
• 首选消息目标类型：phone、email 或 auto
• 针对特定联系人的首选渠道和目标覆盖设置

apple_detect_defaults() 会返回已保存的偏好设置，并将 probe_status: "not_probed"，且不会写入状态文件。用户请求发现缺失目标后，调用 apple_detect_defaults(probe_apps=true) 来发现并保存这些目标。此项显式探测可能会打开 Mail 或 Notes，并请求 macOS 权限。该工具会声明它可以写入偏好设置。使用 apple_get_preferences 查看默认设置，并使用 apple_update_preferences 直接设置。

apple_health、apple_recheck_permissions、apple_overview 和 apple://overview 不会向应用发送 Apple Events，也不会请求新权限。Overview 会保留其资源键，但对于需要权限的应用数据，会返回 ok: false 和 status: "not_probed"。用户请求相关数据时，读取对应的领域资源或调用对应工具。最近文件扫描也会延后，因为受保护的文件夹可能需要权限。快捷指令库枚举同样会延后。其显式资源 shortcuts://all 可以运行多条 CLI 命令，每条命令的默认超时时间为 300 秒。Maps 的可用性元数据仍会包含在内。显式应用操作仍会进行权限检查，并可能启动用户请求的应用。

提醒事项或备忘录操作需要但缺少目标位置时，只会为相应领域发现默认设置。

默认情况下，状态文件存储在 ~/.apple-tools-mcp/preferences.json。使用 APPLE_AGENT_MCP_STATE_FILE 覆盖此路径。

Apple-Tools-MCP 还会将最近的助手操作存储在 ~/.apple-tools-mcp/actions.json 中，以便统一服务提供审计历史记录，并支持撤销可逆操作。

归档、提醒事项、备忘录和 Mail 后续操作的预览不会更改已保存的偏好设置和操作历史记录，包括需要发现默认设置或无法解析目标位置的情况。显式指定的提醒事项列表或备忘录文件夹 ID，仅当其与默认设置匹配时才会使用已保存的标签；其他 ID 会直接显示在预览中。

归档发现仅限于所选帐户。显式覆盖帐户时，不会复用其他帐户已保存的归档邮箱，也不会替换已保存的默认设置。如果该帐户没有可发现的归档邮箱，请显式传入其邮箱。

使用方法

• 先通过 Contacts 查找联系人，再根据已保存的默认设置决定使用 Messages 还是 Mail。
• 为始终偏好特定沟通渠道的联系人设置单独的偏好。
• 当客户端需要确认时，预览有风险的操作和使用默认值的创建流程。
• 用户提到的是一段对话而非单条消息时，使用 Mail 线程辅助工具。
• 尽早设置默认项（归档邮箱、日历、提醒事项列表、备忘录文件夹），避免助手反复询问。
• 保持联系人信息最新，以确保通信路由可靠。
• 请求涉及本地文档时，先使用 Files，再考虑 Mail、Messages、Notes 或 Shortcuts。
• 执行可能打断用户的操作前，先检查 System 上下文，尤其是在前台应用、剪贴板或电池状态会影响操作时。
• 如实说明 Focus 支持情况，并尽力而为。若可用则使用；如果 MCP 报告本地设置不支持，就不要编造当前的 Focus 模式。
• 更改 macOS 偏好设置时使用 apple_update_system_setting；只有原生应用域工具无法完成任务时，才使用 apple_control_frontmost_app。
• 如果请求实际上是更改 macOS 偏好设置，优先使用明确的 System 设置工具，而非通用 GUI 自动化。
• 仅当原生领域 MCP 无法完成任务且客户端已授予辅助功能权限时，才使用 GUI 回退工具。通过 application 或 bundle_id 指定目标应用；该应用必须列在 APPLE_SYSTEM_MCP_GUI_ALLOWED_APPS 中（参见 GUI 输入）。
• 地图搜索和路线规划使用原生 Maps MCP 工具。验证 Maps 支持的行为时，不要改用 shell、网页或外部地图服务。
• 缺少原生领域支持时，使用 Shortcuts 作为明确的桥接方式，而不要临时改用 shell 或 GUI 操作。
• 将每日或每周简报保存到 Notes 前，先使用专用的摘要文件夹辅助工具。
• 当路线或出行时间会影响日程安排或沟通时，使用 Maps。
• 对于可撤销的操作，使用 apple_list_recent_actions 和 apple_undo_action。
• Mail 必须使用特定发件人身份时，在 from_account 中传入准确的发件人邮箱，而不仅仅是账户昵称。

macOS 权限

• Mail 需要 Mail 的自动化权限
• Calendar 需要日历权限
• Reminders 需要提醒事项权限
• Messages 需要 Messages 的自动化权限，以及用于读取历史记录的完全磁盘访问权限
• Contacts 需要通讯录权限
• 要在 Messages 响应中显示联系人姓名，必须先运行明确的 Contacts 工具（它会构建 Contacts 辅助工具并请求访问权限）；Messages 读取操作不会构建该辅助工具或请求权限，而是报告 contact_names_status
• Notes 需要 Notes 的自动化权限
• Shortcuts 通常无需单独的隐私权限提示
• Files 访问权限由 APPLE_FILES_MCP_ALLOWED_ROOTS 控制，不受 macOS 隐私权限提示控制
• System 操作可能会根据宿主应用触发 System Events、辅助功能或自动化权限提示
• 在未签名的本地安装中，Focus 状态只能尽力获取，但会如实报告
• 如果 macOS 无法清晰提供通知中心历史记录，则不会声称可以读取
• Maps 无需隐私权限提示，但搜索和路线规划要求本地 Swift 辅助工具能够编译

启动检查清单

• 将 uvx apple-tools-mcp（或克隆项目中的 Apple-Tools-MCP/start.sh / 已安装的 .venv/bin/apple-tools-mcp 入口）添加到 MCP 客户端
• 重新加载或重新连接客户端，以便加载 Apple-Tools-MCP 工具集并纳入上下文
• 首先调用 apple_health，验证每个领域
• 如果某个领域受阻，调用 apple_permission_guide
• 更改 macOS 权限后，调用 apple_recheck_permissions

传输方式和协议验证

stdio 是默认且推荐的传输方式。设置 APPLE_AGENT_MCP_TRANSPORT=streamable-http（可选设置 APPLE_AGENT_MCP_HOST 和 APPLE_AGENT_MCP_PORT），即可改用 Streamable HTTP 进行服务——下文将用于协议验证。

官方 MCP 一致性测试

以一致性测试模式启动 Apple-Tools-MCP：

cd /path/to/Apple-MCPs/Apple-Tools-MCP
APPLE_AGENT_MCP_TRANSPORT=streamable-http \
APPLE_AGENT_MCP_PORT=8765 \
APPLE_AGENT_MCP_CONFORMANCE_MODE=1 \
./start.sh

然后运行官方主动测试套件：

npx -y @modelcontextprotocol/conformance server \
  --url http://127.0.0.1:8765/mcp \
  --suite active

APPLE_AGENT_MCP_CONFORMANCE_MODE=1 会添加一个可选的 MCP 一致性测试界面，涵盖内容类型、资源、资源模板、提示词、进度和完成（有意不包含规范 2026-07-28 移除的功能对应的测试夹具）。此模式用于 CI 和协议测试，不适用于日常助手使用。

简报和分流工具（apple_generate_daily_briefing、apple_generate_weekly_briefing、apple_triage_communications_task）是标准的同步工具——它们此前使用的实验性 MCP tasks API 已从规范（SEP-1686）和 SDK 中移除，工具名称和结果保持不变。

发布文档

• 黄金工作流
• 故障模式
• 兼容性与版本固定
• 代码模式
• 演示脚本
• 清单模板提示词

Inspector CLI 冒烟测试

在此服务目录中运行：

npx -y @modelcontextprotocol/inspector --cli bash ./start.sh --method tools/list
npx -y @modelcontextprotocol/inspector --cli bash ./start.sh --method prompts/list
npx -y @modelcontextprotocol/inspector --cli bash ./start.sh --method resources/list

如需运行覆盖整个仓库的完整冒烟测试，请运行：

cd /path/to/Apple-MCPs
bash scripts/inspector_smoke.sh

Agent 路由提示词

<apple_tools>
`tools/list` returns the full tool surface. If context is constrained, use `search_tools` first, then `get_tool_info` only for the tools you plan to call.

<routing>
  <imessage trigger="text, message, msg, iMessage">
    Resolve recipient via Contacts first. Confirm if multiple matches.
    Omit service_name parameter entirely.
  </imessage>

  <contacts trigger="lookup, phone number, email, contact">
    Run before any iMessage or Mail action.
  </contacts>

  <mail trigger="email, mail, inbox, draft, reply">
    Search requires a query string (sender, subject, or "*" as wildcard). No list-all endpoint.
    If text vs. email is ambiguous, ask once.
  </mail>

  <calendar trigger="calendar, event, schedule, appointment, meeting, block time">
    Confirm date, time, duration, and title before writing.
  </calendar>

  <reminders trigger="remind me, task, to-do, don't forget">
    Reminders are organized into lists. Identify available lists on first use and set a default.
    due_date requires timezone offset: yyyy-MM-ddTHH:mm:ss-HH:00
  </reminders>

  <notes trigger="note, jot down, write this down, save this">
    Multiple accounts may have a "Notes" folder. Identify them on first use and set a default.
    Use for reference only. Time-sensitive items go to Reminders or Calendar.
  </notes>

  <shortcuts trigger="shortcut, automation, run shortcut">
    List available shortcuts before running if request is vague.
  </shortcuts>

  <files trigger="file, folder, attachment, document, download, desktop">
    Use Files before Mail, Messages, Notes, or Shortcuts when the request references local paths or attachments.
    Confirm the exact path before mutation or send actions.
  </files>

  <system trigger="clipboard, frontmost app, battery, notification, open app">
    Use System when local desktop context affects the next action.
    Keep writes scoped unless the user clearly asked for a notification, clipboard update, or app launch.
  </system>

  <maps trigger="map, directions, route, commute, eta, address, place">
    Use Maps when place lookup or travel time affects scheduling or communication.
    Confirm origin, destination, and transport mode for time-sensitive plans.
  </maps>
</routing>

<disambiguation>
  1. Has due date/time -> Reminders
  2. Reference material, no action -> Notes
  3. Involves another person -> iMessage or Mail (Contacts first)
  4. Text vs. email unclear -> ask once
</disambiguation>

<known_gotchas>
  - service_name on iMessage calls causes error (-1728). Omit it.
  - Bare timestamps without timezone offset fail on Reminders.
  - Mail has no "list recent" endpoint. Always pass a search query.
  - Use `search_tools` plus `get_tool_info` to inspect tools without loading every schema into context.
  - Multiple Notes folders exist across accounts. Pick one default.
  - Files access is limited to APPLE_FILES_MCP_ALLOWED_ROOTS.
  - Some System actions depend on host app automation approval.
  - GUI input needs application or bundle_id, and the app must be in APPLE_SYSTEM_MCP_GUI_ALLOWED_APPS. Terminals and script editors are always refused.
  - Maps search and directions depend on the local Swift helper and Xcode command line tools.
</known_gotchas>
</apple_tools>

相关服务

• Apple Files MCP
• Apple System MCP
• Apple Maps MCP
• Apple Mail MCP
• Apple Calendar
• Apple Reminders MCP
• Apple Messages MCP
• Apple Contacts MCP
• Apple Notes MCP
• Apple Shortcuts MCP

GUI 输入

apple_control_frontmost_app 和委托的 system_gui_* 输入工具只会向列在 APPLE_SYSTEM_MCP_GUI_ALLOWED_APPS 中的应用发送输入。该变量默认为空，因此 GUI 输入默认关闭，直至你设置它。列出菜单栏项目（list_menu_bar_items）只会读取信息，无需允许列表。

• 格式：以逗号分隔的 bundle id，例如 com.apple.TextEdit,com.apple.Safari。要查找应用的 bundle id，请运行 osascript -e 'id of app "TextEdit"'。
• 设置位置：此服务在 MCP 客户端配置中的 env 块，例如 "APPLE_SYSTEM_MCP_GUI_ALLOWED_APPS": "com.apple.TextEdit,com.apple.Safari"。在 Claude Desktop 中，打开 Settings > Extensions，配置 Apple Tools，并填写“允许接受 GUI 输入的应用”。之后重启客户端。
• 每个输入操作（click_menu_path、press_keys、type_text、click_button、choose_popup_value）都必须指定 application 或 bundle_id。输入绝不会发送到当前恰好位于前台的应用。
• 终端、脚本编辑器和自动化应用（Terminal、iTerm2、Ghostty、Warp、Script Editor、Automator、Shortcuts、Xcode、VS Code、Cursor、JetBrains IDE、Raycast、Alfred 等类似应用）始终会被拒绝，即使它们已列入允许列表也不例外。

邮件附件

在将本地文件附加到草稿或待发邮件之前，请将 APPLE_MAIL_MCP_ALLOWED_ATTACHMENT_ROOT 设置为专用目录。未设置此变量时，附件功能会被禁用。独立 Mail 服务和统一 Apple Tools 服务均受相同的目录限制。

在 calendar_list_calendars 中按显示名称和来源选择日历，然后原样传入其返回的 calendar_id。更改 Calendar 权限并重启 MCP 服务后，请重新列出日历。要完整编辑提醒，请使用原生日历 ID 列出事件，并使用返回的原生事件 ID；现有的 applescript:: ID 仍会使用自动化方式。请参阅选择日历和事件标识符。

日历提醒编辑遵循独立服务的约定：完整编辑以及同时显式更新提醒和字段，均需要原生 EventKit。在自动化回退模式下，编辑普通字段时请省略提醒。仅提醒的初始提示和空列表无操作，要求所有提醒集合均可读取且为空。插入失败或变更中断时，结果可能未知；重试前请检查事件。请参阅日历提醒支持。