Shortcuts MCP
A TypeScript MCP server that connects LLMs to your macOS Shortcuts library. Interactive workflows with file pickers, dialogs, and prompts work through AppleScript integration, while CLI handles discovery and management.
Why This Exists
I wanted to integrate my existing automation workflows with AI assistance. Rather than manually triggering shortcuts outside of my LLM and then copying results back, this server lets me run shortcuts directly within AI conversations for better automation.
What You Get
- Purpose Annotations: Record what shortcuts do as you use them, building discoverable intent across sessions
- Smart Discovery: Browse shortcuts by what they do, not just their name — intent matching without prompting
- Case-Insensitive Names: Pass shortcut names as-is; resolution handles casing automatically
- Interactive Support: File pickers, dialogs, and prompts work normally through AppleScript execution
- Hybrid Integration: AppleScript for compatibility + CLI for discovery and management
- Permission Handling: Location services, system integrations work with proper permission context
- All Shortcut Types: Interactive workflows and automation both work reliably
- Reliable Execution: No hanging on permission requests or interactive elements
- Local Usage Tracking: Execution history and preferences stored only on your computer
- Usage Analytics: Automatic pattern analysis via MCP sampling (when supported)
Installation
Option 1: MCP Bundle (.mcpb) - Recommended
- Download the latest
.mcpb file from Releases
- Double-click the .mcpb file or drag it onto Claude Desktop
- Click "Install" in the Claude Desktop UI
- Restart Claude Desktop
Option 2: Manual Installation
Clone and build locally for development:
git clone https://github.com/foxtrottwist/shortcuts-mcp.git
cd shortcuts-mcp
pnpm install
pnpm build
Add to your MCP client configuration. For Claude Desktop:
{
"mcpServers": {
"shortcuts-mcp": {
"command": "node",
"args": ["/absolute/path/to/shortcuts-mcp/dist/server.js"]
}
}
}
Tested MCP Clients
This server has been tested with the following MCP clients:
How to Use It
Interactive Workflows
Run my "Photo Organizer" shortcut
File pickers and dialogs appear normally for user interaction. All shortcut types work including location-based and permission-requiring workflows.
Finding the Right Shortcut
What shortcuts do I have for file processing?
What shortcuts have I used this week?
Which of my shortcuts work best for photo editing?
Your AI assistant can browse your complete shortcuts library, check your usage history (stored locally), and suggest options based on what's worked for you before.
Examples That Work
Run my "Get Weather" shortcut
Run "Create QR Code"
Execute my "File Organizer"
Both automated and interactive shortcuts work reliably through AppleScript execution.
Purpose Annotations
Every time a shortcut runs with a purpose (e.g. "check weather forecast"), the server stores that annotation. Over time, this builds a map of what each shortcut actually does. Your AI assistant uses these annotations to match your intent to the right shortcut without asking — even in new conversations.
Annotations persist in ~/.shortcuts-mcp/user-profile.json and appear in the shortcuts://available resource alongside each shortcut's name and ID.
Execution Tracking - Local Organization
The server keeps track of your shortcut usage to help organize your workflow. All execution history and preferences stay on your computer - no data is transmitted anywhere.
What Gets Tracked
- Which shortcuts you run and when
- Purpose annotations describing what each shortcut does
- Execution success/failure for debugging
- Basic preferences you set through your AI assistant
- Usage patterns for shortcut suggestions
Privacy Note: Shortcut inputs and outputs are not stored locally. Be cautious when running shortcuts containing sensitive information, as you control what data is shared with your AI assistant.
Privacy-First Design
- Everything stored in
~/.shortcuts-mcp/ on your Mac
- No cloud sync, no data sharing, no external connections
- You can delete the folder anytime to reset
- Only you and your AI assistant (locally) can access this information
Practical Benefits
After using shortcuts for a while, you can ask your AI assistant things like:
What shortcuts have I used this week?
Which shortcuts failed recently?
Remember I prefer the "Photo Editor Pro" shortcut for image work