Mac Shortcuts — Claude Code MCP server: what it does, how to install
Lets AI agents inspect your macOS Calendar, Reminders, Notes, and Contacts through Apple Shortcuts. Operates locally without external cloud accounts.
claude mcp add mac-shortcuts-mcp -- npx -y mac-shortcuts-mcpWhat Mac Shortcuts — read your Mac from any agent does
AI coding assistants lack native operating system permissions to query Apple applications directly. This server delegates read operations to Shortcuts.app, which already has those access rights, and returns clean text back to the model. Retrieved contents are marked explicitly as data rather than instructions, preventing prompt injections hidden inside personal notes.
Built-in tools cover calendar events, task lists, contacts by query, clipboard text, local coordinates, weather, and active media playback. The package also embeds action-catalog.json, detailing 539 action schemas extracted from the macOS 27 registry. Because mac_run_shortcut can trigger custom local shortcuts that send messages or modify files, the environment does not enforce a strict read-only sandbox.
Getting started requires running npx -y mac-shortcuts-mcp setup to sign and add XML property lists inside the Shortcuts app. The tool runs on macOS only. A locked display handles calls normally, but Mac system sleep halts background execution entirely. When your Mac sleeps, the server cannot respond.
What it helps with
- check upcoming calendar appointments for the week
- pull search matches and body text from Apple Notes
- retrieve phone numbers and email details from Contacts
- inspect current clipboard content and device battery status
- verify parameter keys across 539 macOS Shortcuts actions
Example prompts for the agent
- Show me all events scheduled on my calendar for the next three days.
- Find the note regarding apartment repairs and print its text.
- Look up Alex in my contacts and give me his phone number.
How to install Mac Shortcuts — read your Mac from any agent
Platform CLI
claude mcp add mac-shortcuts-mcp -- npx -y mac-shortcuts-mcpPlatform CLI
codex mcp add mac-shortcuts-read-your-mac-from-any-agent -- npx -y mac-shortcuts-mcpConfig file
{
"mcpServers": {
"mac-shortcuts-read-your-mac-from-any-agent": {
"command": "npx",
"args": [
"-y",
"mac-shortcuts-mcp"
]
}
}
}Config file
{
"servers": {
"mac-shortcuts-read-your-mac-from-any-agent": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"mac-shortcuts-mcp"
]
}
}
}Platform CLI
gemini mcp add mac-shortcuts-read-your-mac-from-any-agent npx -y mac-shortcuts-mcpStep by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about Mac Shortcuts — read your Mac from any agent
How to install Mac Shortcuts in Claude Code?
First, run npx -y mac-shortcuts-mcp setup in your terminal to import the recipes into the Shortcuts app. Next, connect the server by running claude mcp add mac-shortcuts-mcp -- npx -y mac-shortcuts-mcp.
What does the Mac Shortcuts MCP server do?
It provides local tools for agents to query Apple Notes, Reminders, Contacts, and Calendar through the native macOS Shortcuts engine. Retrieved text is passed safely as a data payload to prevent prompt injection.
Does it work when the Mac is locked or asleep?
It runs reliably while the screen is locked. Once the Mac enters system sleep, all processes pause, meaning the MCP server will stop responding until the computer wakes up.
