intents-mcp

intents-mcp

你的 Mac 已自带上千种 App 操作。intents-mcp 通过 Shortcuts，仅使用公开 API，将你选择的操作提供给 Claude Code、Codex 或任何 MCP 客户端。

https://github.com/user-attachments/assets/3db14186-e1c6-4724-80da-f9aced0f1fb5

$ intents-mcp census
This Mac declares 1,304 App Intents actions (1,249 unique)
in 224 metadata files, across 91 apps and system components.

  discoverable in Shortcuts  945
  simple tier                 47  background, plain inputs, returns output
  need an entity (a note…)   657  not supported yet
  …

_{作者 Mac 上的真实输出（macOS 27.0，2026-09-26）。运行 intents-mcp census 获取你的结果。}

App 会在 App Intents 元数据中描述供 Siri 和 Shortcuts 使用的操作。 intents-mcp 会读取这些元数据，让你选择 Agent 可以使用哪些操作，为每个操作创建一个小型签名 Shortcut，并通过 stdio 将其作为 MCP 工具提供。Agent 调用工具时， Shortcut 会运行 App 的操作，intents-mcp 会在可行的情况下读取并返回结果：

> Add a reminder to call the dentist tomorrow at 10.
reminders_add → {"ok": true, "output": "Call the dentist", "verified": true,
                 "detail": "read back through Shortcuts: due 26 Sep 2026 at 10:00"}

目前可用的功能

在真实运行中检查过的工具（macOS 27.0、Claude Code 2.1 和 Codex 0.157）：

工具	App	是否读取结果
reminders.add	Reminders	是（标题、截止日期）
calendar.create-event	Calendar	是（标题、开始时间）
notes.create	Notes	否
Writing Tools：总结、校对	Writing Tools	否

任何属于简单级别的操作（在后台运行，输入为纯文本／数字／日期／选项，并返回输出）都可以通过其元数据启用。这些工具会标记为尚未在真实运行中检查。测试时，3 个工具中有 2 个首次运行成功。第 3 个（Notes 的“Create Folder”）始终未能完成，因此已停用；依赖新工具之前，请先检查它。

安装

brew install VladUZH/tap/intents-mcp     # prebuilt for Apple silicon; no dependencies

Intel Mac 需要从源代码构建，这需要 Xcode。

还没有 Homebrew？它的安装程序会要求你输入密码，然后等待你按 RETURN；下载期间可能会安静几分钟。这是正常现象。如果你已经安装了 Homebrew，请先运行 brew update。

在 macOS 27 上，这需要当前版本的 Homebrew（7.0 或更高版本）；较旧版本会从源代码构建，并要求安装 Xcode 27。也可以从克隆的仓库构建：运行 swift build -c release，然后使用 .build/release/intents-mcp。 需要 macOS 26 或更高版本（已在 27.0 上测试），以及 macOS 自带的 shortcuts 命令。

设置（每个工具约一分钟）

intents-mcp census                       # what your Mac has
intents-mcp list --tier simple           # checked tools first, then actions from metadata
intents-mcp enable reminders.add calendar.create-event
claude mcp add --scope user mac -- intents-mcp serve   # Claude Code, in every folder
codex mcp add mac -- intents-mcp serve                  # Codex

坦白说，手动步骤如下：

1. enable 会在 Shortcuts 中打开每个包装器。点击一次 Add Shortcut。Shortcuts 没有公开方式可以在不点击的情况下添加 Shortcut。
2. 工具首次运行时，Shortcuts 可能会请求权限。选择 Always Allow。测试时，每当数据写入另一个 App（Notes、 CotEditor、MacWhisper）时，它都会询问；而 Reminders 和 Calendar 大多不会询问。升级包装器后，它可能会再次询问，因为升级后的包装器是一个新的 Shortcut。

需要读取结果的工具还需要再点击一次 Add Shortcut：Reminders 和 Calendar 各自会添加一个小型结果读取辅助项（“intents-mcp verify.reminders”和 “intents-mcp verify.calendar”），供该 App 的所有工具共用。跳过此步骤后，这些工具仍会运行，但会报告“not verified”。

Claude Code 会在正在运行的会话中获取已启用或已停用的工具；其他客户端（例如 Codex）可能需要重启。

隐私与安全

• 在你的 Mac 上运行。仅使用公开 API。 它会读取应用元数据文件、构建快捷指令，并通过 Apple 的 shortcuts 命令运行这些快捷指令。不使用私有框架，不更改 SIP 或 AMFI，也不会通过辅助功能模拟点击。
• 签名涉及 Apple。 shortcuts sign 会使用你的 iCloud 账户，Apple 会收到每个封装快捷指令的副本以供验证（Apple 的快捷指令指南对此有说明）。签名后的封装快捷指令还包含你的 Apple Account 签名身份（账户标识符，以及经过哈希处理的电子邮件地址和电话号码），因此 intents-mcp 一旦发现快捷指令已添加到你的快捷指令库中，就会立即删除签名文件（在 enable 后，或下次运行 enable、doctor、serve 或调用该工具时）。不要分享已签名的 .shortcut 文件。添加的快捷指令会保存在你的快捷指令库中，并通过 iCloud 同步。
• 由你选择每个工具。 在你运行 enable 之前，不会公开任何内容。名称或描述暗示可能会删除、发送、购买或分享的操作会被标记，需要使用 --allow-risky（采用范围较广的词语列表，因此一些无害操作也会被标记）。Agent 会看到这些操作被标记为 destructiveHint。
• 没有遥测，也不会自行联网。 MCP 服务只通过 stdio 与启动它的客户端通信。
• 每次调用都会在本地记录（intents-mcp log）：工具、时间、耗时、是否成功以及是否经过验证。记录会在调用开始和结束时写入，因此即使调用中断，也会留下记录。不会记录参数和结果。
• 如果存在读取操作，就会回读结果：辅助程序会查找标题与刚使用的标题相同、且确认是在本次调用期间创建的项目。（如果运行 Agent 的应用已拥有完整的 Reminders 或 Calendar 访问权限，则会改用 EventKit 完成；请参阅 PRIVACY.md。）如果有标题相同的旧项目或其他不同项目，则会报告 verified: false，绝不会误报成功。
• 结果不明确时会明确说明。 如果运行超时或结束时没有返回结果，工具会说明操作可能已经执行（outcomeUnknown），以便 Agent 在重试前进行检查。若调用从未开始（已取消或在队列中等待时超时），工具也会说明这一点。

命令

intents-mcp census [--json]                   count the actions this Mac declares
intents-mcp list [--app <name>] [--tier simple|entity|unsupported|all] [--json]
                                              (--json: metadata actions only, with a status
                                              field; the checked tools are at the top of the
                                              text output)
intents-mcp enable <tool>... [--allow-risky]  make actions available to agents (alias or id)
intents-mcp disable <tool>...                 stop exposing them (alias or id)
intents-mcp call <tool> '<json args>'         run a tool as an agent would
intents-mcp tools                             the enabled tools
intents-mcp log [--last <n>]                  what agents called
intents-mcp doctor                            check this Mac is ready
intents-mcp serve                             MCP over stdio

在终端中，census、list、doctor、tools、log、enable 和 disable 的文本输出会逐行显示：每行间隔约 40 ms，最多会使命令增加 2 秒耗时。超过 300 行的输出（例如完整的 list）、管道、文件和 --json 则会一次性输出。 INTENTS_MCP_LINE_DELAY_MS 用于设置间隔的毫秒数：0 会关闭此功能，较大的值（如 120）则会减慢输出速度，适合屏幕录制（此时可能会使命令增加最多 10 秒耗时）。 在终端中，输出还会使用少量颜色（绿色表示正常，黄色表示需要你处理，红色表示失败）。设置 NO_COLOR=1 可关闭颜色；管道、文件和 --json 输出始终不会着色。

限制

• 目前尚不支持实体操作，即针对现有备忘录、提醒事项或列表执行的操作。在作者的 Mac 上，可发现的 945 个操作中有 657 个属于此类。测试时，一个本应在匹配后选中指定备忘录的快捷指令“查找”步骤却选错了备忘录，因此在能够安全匹配之前，这些操作都会保持关闭。
• 已声明不代表可用。 有些已声明的操作会被 Mac 上的快捷指令拒绝，有些则会忽略其已声明的参数名称。Reminders 和 Calendar 则通过快捷指令内置操作运行。
• CLI 无法删除快捷指令。 运行 disable 后，请自行在快捷指令应用中删除封装快捷指令。
• Mac 必须处于唤醒状态。 Mac 休眠时，快捷指令不会运行。另一个项目报告称，屏幕锁定时也能运行；但我们尚未对此进行测试。
• 目前支持 App Intents 的第三方应用不多。 在作者的 Mac 上，50 款应用中有 8 款支持。

为什么不用 Siri？

如果 Siri 能满足你的需求，就用它。intents-mcp 面向的是你已经在使用的 Agent：Claude Code、Codex 或任何 MCP 客户端都可以在任务进行中操作你的 Mac（“添加一个提醒，跟进这个 PR”）。你可以为它选择每项可执行的操作，每次调用都会记录在你的 Mac 上，并且在可能的情况下会读回结果。无论你使用哪种模型和客户端，它都能正常工作。

工作原理

1. 索引。 它会读取 /Applications 和 /System 下的每个 Metadata.appintents/extract.actionsdata。无需任何权限。它会将每项操作映射到你熟悉的应用，并按层级分类。
2. 封装。 每个工具都会变成一个快捷指令：JSON 输入 → 每个参数对应一个“获取词典值” → 应用的操作 →“获取文本” →“停止并输出”。 签名命令为 shortcuts sign --mode people-who-know-me。
3. 运行。 使用 shortcuts run <UUID> --input-path … --output-path … 运行，stdin 来自 /dev/null，并设有超时。由于快捷指令会静默忽略它不认识的键，因此会先检查参数。
4. 提供服务。 一个通过 stdio 运行的小型 MCP 服务：initialize、tools/list、tools/call。它兼容 Claude Code 和当前版本的 Codex。

许可证

MIT