Mac Shortcuts — read your Mac from any agent

mac-shortcuts-mcp

让任何 AI Agent 都能读取你的 Mac。 日历、提醒事项、备忘录、联系人、剪贴板、位置、天气、正在播放的内容——通过 Apple 快捷指令实现。只读、本地运行、无需账号或服务端。

适用于 Claude Code、Claude Desktop、Cursor、Codex 或任何 MCP 客户端。

npx -y mac-shortcuts-mcp setup      # install the read recipes (once)

{
  "mcpServers": {
    "mac": { "command": "npx", "args": ["-y", "mac-shortcuts-mcp"] }
  }
}

然后询问你的 Agent：“我这周的日历上有什么？” · “查找关于租约的备忘录。” · “简的电话号码是多少？”

为什么要做这个

你的 Agent 无法读取 Apple 的第一方应用。它没有相应权限，也没有 API。 快捷指令可以。 此服务将任务交给 Shortcuts.app，它拥有这些权限，并将文本返回给你。

窍门就是这么简单。这里没有什么高明之处——只是把它们连接起来。

它能做什么

工具	读取内容
mac_calendar	未来 N 天的事件
mac_reminders	提醒事项，可指定单个列表
mac_notes	符合搜索条件的备忘录及其正文
mac_contacts	按姓名查找联系人
mac_clipboard	当前剪贴板内容
mac_location	地址和坐标
mac_weather	这台 Mac 所在位置的天气
mac_device	设备名称和电池电量
mac_now_playing	当前正在播放的曲目
mac_shortcuts_list	这台 Mac 上的所有快捷指令
mac_run_shortcut	按名称运行你创建的快捷指令
mac_action_catalog	搜索快捷指令操作目录——见下文
mac_setup / mac_status	安装只读配方，检查准备情况

随附的配方均为只读。 mac_run_shortcut 可以运行任何已安装的快捷指令，包括会写入数据或发送消息的快捷指令。其描述会要求 Agent 在行为未知时先向你确认；但这并不是强制执行的只读沙箱。

从 Mac 读取的所有内容都会标记为数据，而非指令，因此，写着“忽略你之前的指令”的备忘录会作为文本交给 Agent，而不会被当作命令。

操作目录

此软件包中的 action-catalog.json 记录了 539 项快捷指令操作——每项操作都列出了其接受的参数键、参数类型、标签、输出类型和所需权限。

Apple 并未公开这些信息。它们是从 macOS 27 上运行的 WFActionRegistry 中提取的。

这很重要，因为错误的参数键不会引发错误——而是被静默忽略，你的快捷指令则会返回一个看似可信的错误答案。我们对此进行了精确测量：一个组合快捷指令使用了一个看似合理但实际错误的键，结果返回了 0 而不是 3，且没有任何警告。

使用 mac_action_catalog 查询键，也可以直接查看 JSON。MIT 许可，随意使用。

is.workflow.actions.addnewevent  — 새로운 이벤트  [harvested]
  출력: EKEvent
  권한: calendar, contacts, needs-interaction
  · WFCalendarItemTitle (text) — 제목
  · WFCalendarItemStartDate (date) — 시작일
  …

覆盖情况：497 项从注册表中采集，9 项根据缓存的定义字符串推断，33 项在 macOS 上不存在（仅限 iOS 的操作，加上少数并非操作的字符串——其中包括一处 Apple 拼写错误）。

如实说明设置过程

运行 mac-shortcuts-mcp setup 会在你的 Mac 上为随附配方签名，并在“快捷指令”App 中逐个打开。你需要为每个配方点击一次添加快捷指令。

此软件包提供的是可读的 XML plist 文件，而非已签名的二进制文件。打开 recipes/*.plist，就能确切查看你要安装的内容。一个要求你安装不透明文件的开源工具，并不能算真正开源。

传入 --auto 后，工具会使用辅助功能 API 为你点击添加快捷指令。这需要辅助功能权限，因此默认关闭——工具不应悄悄索取该权限。

配方首次访问联系人或日历时，macOS 会请求权限。此提示来自“快捷指令”，而非此服务。

限制

Mac 进入睡眠时，此工具无法运行。 进程会停止，无法进行通信。锁屏没有影响——我们测得，屏幕锁定时 63 次调用中有 62 次成功，速度与解锁时相同。真正的限制是睡眠。

随附配方只读取数据；任意已安装的快捷指令则可能产生副作用。仅适用于 macOS。结果会发送给你连接的 Agent。

需要一台永不休眠的设备时

装在包里的 Mac 无法响应。口袋里的手机可以。

Askew 能在锁定的 iPhone 上完成同样的事情——你的 Agent 会在手机上运行快捷指令，并在大约 3 秒内获得结果，屏幕关闭，手机就在口袋里。它不是免费的，而且解决的是另一个问题：需要推送中继、端到端加密和应用。这个工具不需要这些。

许可证

MIT。欢迎提交问题和拉取请求。

---

韩语

让 Agent 读取我的 Mac。 通过 Apple 快捷指令读取日历、提醒事项、备忘录、联系人、剪贴板、位置和天气。只读、本地、无账户、无服务端。

npx -y mac-shortcuts-mcp setup      # 읽기 레시피 설치 (처음 한 번)

Agent 无法读取第一方应用，是因为没有权限，也没有 API。快捷指令可以读取。 此服务会把工作交给 Shortcuts.app，然后只取回结果文本。

默认配方为只读。 但 mac_run_shortcut 也可以运行已安装的快捷指令，包括写入和发送消息。虽然会提示先询问用户是否了解其行为，但它并不是强制只读的隔离环境。从 Mac 读取的所有内容都会标记为资料，而非指令。

我们还公开了包含 539 种操作的目录。每种操作接受哪些参数键，这些值 Apple 并未提供文档说明。键名不对就会被静默忽略，不报错，并返回错误答案——我们实际测试过。任何人都可以执行操作，但要创建操作，就需要这份清单。

限制：Mac 休眠后，什么都做不了。 锁定屏幕没有问题（锁定状态下 63 次中成功 62 次，速度也相同）。休眠才是障碍。

如果你需要一台不会休眠的设备，那就是手机。Askew 可以在锁定的 iPhone 上完成同样的事情。无需点亮屏幕，大约 3 秒就能返回结果。它不是免费的，而且解决的是另一个问题——需要推送中继、端到端加密和应用。这个工具不需要这些。