Mac Shortcuts — read your Mac from any agent MCP server

mac-shortcuts-mcp

Let any AI agent read your Mac. Calendar, Reminders, Notes, Contacts, Clipboard, Location, Weather, now playing — through Apple Shortcuts. Read-only, local, no account, no server.

Works with Claude Code, Claude Desktop, Cursor, Codex, or any MCP client.

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

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

Then ask your agent: "What's on my calendar this week?" · "Find the note about the lease." · "What's Jane's number?"

Why this exists

Your agent cannot read Apple's first-party apps. It has no permission to, and there is no API. Shortcuts can. This server hands the job to Shortcuts.app, which does have those permissions, and gives you back the text.

That is the whole trick. Nothing here is clever — it is just wired up.

What it can do

The bundled recipes are read-only. macrunshortcut can run any installed Shortcut, including one that writes data or sends messages. Its description asks the agent to check with you when the behavior is unknown; this is not an enforced read-only sandbox.

Everything read from your Mac comes back tagged as data, not instructions, so a note that says "ignore your previous instructions" is handed to the agent as text rather than as a command.

The action catalog

action-catalog.json in this package documents 539 Shortcuts actions — for each one, the parameter keys it accepts, their types, labels, output type and required permissions.

Apple does not publish this. It was extracted from the live WFActionRegistry on macOS 27.

It matters because a wrong parameter key does not raise an error — it is silently ignored, and your shortcut returns a confident wrong answer. We measured exactly that: a composed shortcut with a plausible-but-wrong key returned 0 instead of 3, with no warning.

Use macactioncatalog to look up a key, or just read the JSON. MIT, take it.

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

Coverage: 497 harvested from the registry, 9 inferred from cached definition strings, 33 not present on macOS (iOS-only actions, plus a few strings that are not actions at all — including one Apple typo).

Setup, honestly

mac-shortcuts-mcp setup signs the bundled recipes on your Mac and opens each in the Shortcuts app. You click Add Shortcut once per recipe.

The package ships readable XML plists, not signed binaries. Open recipes/*.plist and see exactly what you are installing. An open-source tool that asks you to install opaque blobs is not really open.

Pass --auto and it will click Add Shortcut for you using the Accessibility API. That needs Accessibility permission, so it is off by default — a tool should not quietly ask for that.

The first time a recipe touches Contacts or Calendar, macOS asks for permission. That prompt belongs to Shortcuts, not to this server.

Limits

Shortened. The full README is on GitHub.