apple-productivity-mcp

Apple Productivity MCP

一个本地 macOS MCP 服务，可通过 Codex、Claude Code、Claude Desktop 和其他 stdio MCP 客户端操作 Apple 的效率应用、文档、文件和媒体。

版本 3.0.0：17 个组共 133 个工具，另可选择执行明确列入允许列表的 Shortcuts。通过 Apple 的自动化接口在你的 Mac 上运行。无需托管服务、监听端口、订阅或 Apple API 密钥。

工具参考 · 机器可读架构 · 验证 · 源文档 · 更新日志 · 发布 · 目录状态

功能

应用 / 组	工具数	覆盖范围
Mail	12	账户和邮箱；邮件元数据 / 正文；按发件人 / 主题搜索；查看草稿；发送；已读 / 标记状态；移动 / 移至废纸篓；创建邮箱；附件。
Calendar	12	日历和事件；创建 / 更新 / 删除事件；事件备注、参与者和重复设置；创建 / 重命名 / 删除日历；显示提醒和事件 URL。
Reminders	15	账户 / 列表；提醒事项和标题搜索；备注、优先级和截止日期；创建 / 更新 / 删除；列表管理；完成 / 重新打开；标记和通知日期。
Notes	9	账户 / 文件夹；列出 / 搜索 / 读取笔记；创建文件夹和 HTML 笔记；更新和删除未锁定的笔记。
Contacts	9	搜索和联系人详情；群组和成员；创建联系人 / 群组；更新字段；添加 / 移除群组成员。
Pages	8	列出 / 打开 / 创建文稿；读取 / 替换 / 追加正文文本；保存；导出 PDF/DOCX；安全关闭，防止未保存的更改丢失。
Numbers	11	文稿、工作表、表格；创建表格；读取 / 写入限定范围的单元格区域；保存；导出 PDF/XLSX；关闭。
Keynote	9	文稿和幻灯片；创建演示文稿；添加 / 更新标题、正文和演讲者备注；保存；导出 PDF/PPTX；关闭。
TextEdit	7	文稿；创建 / 打开 / 读取 / 替换 / 追加文本；保存为 RTF；关闭。
Safari	6	标签页和页面文本；通过 URL 检查打开 / 导航 / 关闭标签页；阅读列表。
Music	9	播放列表、曲目和搜索；元数据；创建播放列表并添加曲目；播放和音量。
Photos	9	相簿 / 项目 / 搜索；元数据；创建相簿；添加项目；导入 / 导出；更新元数据。
Messages	3	账户 / 聊天；通过指定账户向明确指定的收件人发送文本。
Files	8	限定范围的文件夹列表；元数据 / 文本；创建文本文件 / 文件夹；复制；通过 Spotlight 搜索文件名；移至 Finder 废纸篓。
Finder	2	所选项目的元数据；显示允许路径。
Shortcuts	2 + 1 个可选项	列出快捷指令 / 文件夹；仅运行配置的允许列表中的名称。
System	2	发现已安装的应用 / 配置；启动已知的 Apple 应用。

原有的 18 个工具名称仍受支持。版本 3 扩展了默认目录；你可以在下方仅选择所需的应用组。

功能覆盖范围有限。 Apple 并未通过脚本开放每项应用功能。目前未实现 Messages 历史记录、Contacts 删除、Pages 布局文本框、完整文档样式、Calendar 邀请、Reminders 子任务 / 标签 / 重复设置、任意 Safari JavaScript 以及 Apple 私有数据库。没有专用的 Home、Health、Wallet、Find My 或 Freeform 编辑工具。用户创建并列入允许列表的 Shortcut 可以衔接其他应用中的受支持操作。完整的输入架构准确说明了各工具接受的内容。

要求

• macOS 和 Node.js 20 或更高版本。
• 必须已安装并配置要控制的 Apple 应用。Pages、Numbers 和 Keynote 需分别从 App Store 安装。
• 支持本地 stdio MCP 服务的客户端。
• macOS 自动化权限：启动客户端/进程必须有权控制每个应用。某些文件位置还需要“文件与文件夹”访问权限。

MCP 客户端连接时，服务才会启动。每次自动化调用都会使用固定脚本和 JSON 参数，并设置超时时间。iCloud、Exchange 或其他帐户同步仍遵循应用自身的设置。

安装

Codex

codex mcp add apple-productivity-local -- \
  npx -y @gambadio/apple-productivity-mcp@latest
codex mcp get apple-productivity-local

Claude Code

claude mcp add --transport stdio --scope user apple-productivity-local -- \
  npx -y @gambadio/apple-productivity-mcp@latest
claude mcp get apple-productivity-local

Claude Desktop 和其他使用 JSON 配置的客户端

将以下内容添加到客户端的 MCP 配置中，然后重启客户端：

{
  "mcpServers": {
    "apple-productivity-local": {
      "command": "npx",
      "args": ["-y", "@gambadio/apple-productivity-mcp@latest"]
    }
  }
}

如需可复现的安装，请将 @latest 替换为 @3.0.0。GitHub 发布页提供经过测试的本地 .mcpb bundle 和校验和。请参阅打包说明自行构建。此软件包必须在用户的 Mac 上运行，无法从 Linux 容器或远程托管服务访问用户的应用。

配置

所有设置均为可选。将其放入 MCP 客户端的服务环境中，然后启动新的 MCP 进程。

变量	默认值	行为
APPLE_MCP_ENABLED_GROUPS	所有组	使用逗号分隔的组名，名称取自上表且需为小写，例如：mail,calendar,reminders,notes。留空表示全部启用。未知组会导致启动失败。
APPLE_MCP_READ_ONLY	false	1 或 true 仅注册只读工具。0 或 false 还会启用所选组的写入工具。
APPLE_MCP_FILE_ROOTS	[]	JSON 数组，包含现有绝对目录，供“文件”工具、Finder 显示位置、Mail 附件保存和 Shortcut 文件输入使用。使用这些操作时必须设置。解析到这些根目录之外的路径将被拒绝。
APPLE_MCP_SHORTCUTS	[]	JSON 数组，包含获准运行的快捷指令名称/标识符。列表为空时，将完全省略 apple_shortcuts_run。

以下示例启用 Notes、提醒事项、文件，以及一个获准使用的 Shortcut：

{
  "mcpServers": {
    "apple-productivity-local": {
      "command": "npx",
      "args": ["-y", "@gambadio/[email protected]"],
      "env": {
        "APPLE_MCP_ENABLED_GROUPS": "system,notes,reminders,files,finder,shortcuts",
        "APPLE_MCP_FILE_ROOTS": "[\"/Users/YOUR_NAME/Documents\"]",
        "APPLE_MCP_SHORTCUTS": "[\"Prepare daily note\"]"
      }
    }
  }
}

将 YOUR_NAME 和快捷指令名称替换为 Mac 上实际存在的值。可以使用 iCloud Drive 目录，但须填写其真实的本地绝对路径。

文件根目录仅限制上述通用文件工具，并不是 Apple 应用的沙盒。iWork/TextEdit 的打开、保存和导出，以及 Photos 的导入和导出，使用这些应用在 macOS 权限范围内可访问的显式路径。快捷指令可以执行其内容中已有的任何操作，包括发送信息或更改其他位置的数据。将快捷指令加入允许列表前，请先检查其内容。应用组筛选和只读模式控制对外提供的工具；MCP 注解只是给客户端的提示，并非授权机制。

请求示例

• “查找标题中包含‘invoice’的提醒事项，然后显示其备注和截止日期。”
• “在此帐户中创建一个 Notes 文件夹，并将我的会议摘要放进去。”
• “读取这份 Pages 文稿，并在其旁边导出 PDF。”
• “列出我的 Numbers 工作簿中的工作表和表格，然后将这些值填入单元格 B2:D6。”
• “添加一张 Keynote 幻灯片，包含此标题、正文和演讲者备注。”
• “查找此发件人的 Mail 邮件，并将选定的附件保存到我获准访问的 Documents 文件夹。”
• “列出我的 Photos 相簿，并将选定项目导出到一个空文件夹。”
• “运行我加入允许列表的‘Prepare daily note’快捷指令。”

请从发现工具开始。使用返回的 ID/名称，并检查工具架构以确认确切字段。apple_system_capabilities 会识别已安装的应用，但不会预先授予这些应用权限，也无法证明你拥有相应权限。写入请求会修改真实数据，因此请明确指定目标和要进行的更改。

数据处理与保护措施

• 不设服务端账户、遥测服务、网络监听器或凭据存储。
• 固定的 JXA 程序通过 JSON 参数接收用户值，不会将其插入可执行源代码中。没有任意代码或 Shell 执行工具。
• 新建文件副本时不会覆盖现有文件。文本写入和文档保存/导出操作需要显式指定覆盖选项，才能替换路径。导出照片时，目标文件夹必须为空。
• 通用文件操作需要显式指定根目录，并检查解析后的路径。文件删除会移至 Finder 废纸篓；没有清空废纸篓的工具。
• 集合读取以及文本/单元格范围均有限制。不会读取或修改已锁定的备忘录。Safari 标签页变更会比对预期 URL，以防索引发生偏移。
• 只读模式会隐藏变更操作。每个工具都会声明只读、破坏性、幂等和开放世界注释。
• 邮件、信息、文档变更、提醒事项、联系人和媒体编辑可能会同步或发送给其他人。发送结果表示已提交至应用，并不代表已独立确认送达。
• 超时或多步骤错误可能导致部分变更。重试写入前，请检查目标。
• 返回给 MCP 客户端的数据会成为该客户端当前模型会话的一部分，并受其数据控制措施约束。本地执行并不意味着内容不会进入模型会话。具有足够操作系统权限的本地进程可以看到 JSON 输入。

开发与验证

npm ci
npm test
npm run docs:tools
npm audit --omit=dev
npm pack --dry-run

测试会针对应用固定数据执行静态自动化程序，在临时文件夹中测试文件系统边界，并初始化实际的 stdio MCP 服务。测试不会发送信息，也不会编辑个人应用数据。

对于现有的只读 Mail/Calendar/Reminders 集成测试套件，在授予自动化权限后：

npm run test:integration

实时验证因应用而异。 发布开发用 Mac 未安装 Pages、Numbers 和 Keynote；这些工具有固定数据覆盖，但未进行实时 iWork 验证。请参阅验证结果与限制和实现源代码。不要将工具数量理解为所有操作都已在每个应用/macOS 版本中测试过。

故障排查

自动化不可用 / 未获授权 / 超时： 打开“系统设置”→“隐私与安全性”→“自动化”，允许相关 Apple 应用被启动客户端访问。超时也可能是因为应用繁忙或 iCloud 数据加载缓慢；请勿盲目重试写入操作。更改权限/配置后，请重启客户端。

找不到应用： 安装应用，启动一次，并验证 apple_system_capabilities。操作系统进程沙盒也可能限制 LaunchServices。请使用具有相应 macOS 访问权限的本地客户端。

需要指定文件根目录 / 路径位于允许的根目录之外： 将 APPLE_MCP_FILE_ROOTS 配置为包含现有绝对目录的 JSON 数组。无法通过符号链接绕过此列表。请先创建缺失的父文件夹。

找不到对象 / 名称不明确： 重新获取应用当前的账户、列表、文档或对象 ID。名称因语言/提供方而异。按名称编辑前，请关闭或重命名重复文档。

联系人中有未保存的更改： 使用变更操作前，请在“联系人”中保存或放弃待处理的编辑，因为“联系人”的脚本保存操作会影响所有待处理更改。

缺少工具： 检查应用组/只读设置，启动新会话，并在客户端中验证 mcp get/mcp list。只有在允许列表非空时，才会显示快捷指令执行功能。即使未安装应用，其工具也可能会显示。

spawn ... ENOENT： 确保桌面客户端的 PATH 中可以访问 Node 和 npx；如有需要，请使用 command -v npx 返回的完整路径。

更新或移除

启动新的 MCP 进程时才会解析 @latest；发布版本后，请重启客户端。现有进程会继续运行已加载的版本。若要在 v3 中保留原有应用范围，请设置 APPLE_MCP_ENABLED_GROUPS=mail,calendar,reminders。

codex mcp remove apple-productivity-local
claude mcp remove apple-productivity-local --scope user

移除注册不会删除 Apple 数据，也不会清除 npm 的缓存。

分发

规范来源：GitHub。软件包：npm。注册表标识：io.github.gambadio/apple-productivity-mcp。

目录状态区分了已上线的列表、等待审核的提交、登录要求，以及不兼容或已暂停的发布渠道。第三方列表中的文案可能未及时更新以反映源代码版本。是否收录及是否推荐由各维护方决定。

许可证

MIT。独立项目；与 Apple 无关联，也未获 Apple 背书。