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.

Related MCP server: Apple Shortcuts MCP Server

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

1. Download the latest .mcpb file from Releases

2. Double-click the .mcpb file or drag it onto Claude Desktop

3. Click "Install" in the Claude Desktop UI

4. 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:

• Claude Desktop

• LM Studio - Tested with models like gpt-oss and qwen3-1.7b (manual installation only)

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

Takes a few runs to build useful history - the tracking helps your AI assistant give better suggestions based on what actually works for you.

MCP Sampling for Usage Analytics

When your MCP client supports sampling, the server automatically generates statistics from your usage data. This includes:

• Success rate analysis across different shortcuts

• Performance timing patterns

• Usage trend identification

• Personalized shortcut recommendations

Current Status: Claude Desktop does not yet support MCP sampling, so analytics are not available. The server detects sampling capability automatically and enables these features when supported.

Interactive Shortcuts - Full Support

AppleScript integration enables complete interactive shortcut support. File pickers, dialogs, prompts, and menus all work normally for user interaction.

What Works

• Interactive workflows with file pickers, dialogs, and forms

• Location-based shortcuts with proper permission handling

• Automated processes that run without user input

• System integrations (Calendar, Messages, Notes)

How It Works

When running interactive shortcuts:

Run my "Create Contact" shortcut

Result: Forms and dialogs appear normally. You can fill out contact information, select files, or interact with any UI elements as if running the shortcut manually.

Error Handling:

• "User canceled": Dialog was dismissed or timed out

• "missing value": Interaction completed but returned no data

• Successful completion: Normal data output from interaction

Architecture Improvements

Hybrid Execution Model

AI Assistant ←→ MCP Server ←→ [AppleScript Execution + CLI Discovery] ←→ Shortcuts App ←→ Apple Ecosystem

AppleScript Execution: Reliable permission context for all shortcut types CLI Discovery: Fast listing and identification of available shortcuts Permission Awareness: Graceful handling of location services and system permissions

Reliability Enhancements

• Permission Context: AppleScript runs through "Shortcuts Events" with proper user permissions

• Apple CLI Bug Handling: Name resolution differences detected

• Logging: Timing, debugging, permission detection for troubleshooting

Building Shortcuts for Claude

All Shortcut Types Work

AppleScript integration supports interactive and automated shortcuts. Build shortcuts that take advantage of this:

• Interactive workflows with file selection and user input

• Automated processes for background execution

• Hybrid approaches combining interaction with automation

Output Design by Shortcut Type

For Data Retrieval Shortcuts: When your shortcut fetches information that your AI assistant should receive, explicit output configuration is essential. Without it, you'll get unexpected results.

Real Example: Weather Shortcut

The "Get The Weather" shortcut demonstrates proper output configuration. The "Text" action converts the weather data to the correct type, and the "Stop and output" action ensures the shortcut produces output that reaches the command line.

What happens without proper output configuration:

• Before: Shortcut gets weather data internally but returns timestamp: "2025-08-05T16:52:06.691Z"

• AI assistant tells user: "The current time is August 5th…"

• After: Text action converts data + Stop and output ensures delivery: "Partly cloudy, 72°F"

• AI assistant tells user: "The weather is partly cloudy, 72°F"

For System Action Shortcuts: When your shortcut changes system settings or performs actions, output configuration is optional:

Works fine without explicit output:

[Adjust Brightness] → [Set Focus Mode] → (no output configuration needed)

Your AI assistant receives action confirmation and can tell the user the changes completed successfully.

Key question: "Does the user expect their AI assistant to tell them specific information from this shortcut?"

• Yes (Data Retrieval) → Add Text action (conversion) + Stop and output action (delivery)

• No (System Action) → Output configuration optional, action confirmation is sufficient

Quick test: Run your shortcut in Terminal:

osascript -e 'tell application "Shortcuts Events" to run the shortcut named "Your Shortcut"'

If you see no output, your LLM won't get data either.

Design Approaches

Interactive: "Photo Editor" → File picker for images, processing menu, save results Automated: "Daily Backup" → Runs automatically, returns status summary Hybrid: "Custom Report" → User selects data source, automatic processing

For Best Claude Integration

While all shortcuts work, some integrate better with AI assistant workflows:

• Return clear text output that your AI assistant can understand and act on

• Provide completion messages rather than silent operations

• Include error handling with informative responses

• Design for both modes when possible (interactive + automated)

Examples:

• File Processing: "Organize Files" → Returns summary with file counts and locations

• Weather: "Get Weather Report" → Returns structured weather data as text

• System Tasks: "Deploy Project" → Returns deployment status and any issues

• Cross-Device: "Create Event" → Returns confirmation with calendar integration details

Real-World Interactive Examples

Note: These examples show what's possible - you need to create and configure these shortcuts in your Shortcuts app first.

• "Choose Files for Upload": File picker dialog for document selection

• "Custom QR Generator": Input form for text/URL entry with format options

• "Photo Processing Menu": Image picker followed by processing options menu

• "Contact Creator": Multi-field form for complete contact information entry

• "Project Template Selector": Menu-driven workflow setup with customization options

How It Works

Technical Implementation

AppleScript Integration: Native osascript execution bypasses subprocess permission limitations that caused location-based shortcuts to hang

Dual-Layer Security:

• Shell escaping for command construction safety

• AppleScript string escaping for script content protection

Error Detection:

• Permission error codes (1743) detected with solution guidance

• Timeout behaviors managed gracefully

MCP Integration

1. Tools:

• run_shortcut - AppleScript execution with case-insensitive name resolution and purpose annotations

• shortcuts_usage - Read and update local preferences, usage tracking, and shortcut annotations

• view_shortcut - Open shortcuts in the editor for interactive UI workflows

1. Resources (automatically embedded):

• shortcuts://available - JSON map of shortcuts with IDs and purpose annotations

• context://system/current - System state for time-based suggestions

• context://user/profile - User preferences and usage patterns

• statistics://generated - AI-generated statistics from execution history (when sampling supported)

1. Prompts: Shortcut recommendation based on available shortcuts and usage history

2. Local Data Storage: Performance tracking, permission detection, debugging information (stays on your computer)

Real-World Examples

Note: These examples show what's possible - you need to create and configure these shortcuts in your Shortcuts app first.

Location-Based Workflows

• "Find Coffee Shops": Location services handled properly via AppleScript context

• "Weather for Current Location": Geographic permissions work reliably

System Integration

• "Backup Notes": File system operations with proper permissions

• "System Status Report": Hardware monitoring and reporting

• "Network Diagnostics": System-level network analysis

Development

Prerequisites

• Node.js 22+

• macOS with Shortcuts app

• TypeScript knowledge for contributions

Setup

# Clone repository
git clone https://github.com/foxtrottwist/shortcuts-mcp.git
cd shortcuts-mcp

# Install dependencies
pnpm install

# Development mode with hot reload
pnpm dev

# Build for production
pnpm build

# Build .mcpb bundle
pnpm build:mcpb

Project Structure

src/
├── server.ts              # MCP server configuration
├── shortcuts.ts           # AppleScript + CLI integration
├── shortcuts-usage.ts     # Local execution tracking and preferences
├── sampling.ts            # AI-driven statistics generation via MCP sampling
├── helpers.ts             # Security and utility functions
├── shortcuts.test.ts      # AppleScript execution tests
├── shortcuts-usage.test.ts # Usage tracking and analytics tests
└── helpers.test.ts        # Security function tests

Core Functions

// AppleScript execution with structured logging
await runShortcut(log, "Shortcut Name", "input");

// CLI discovery and management
await listShortcuts(); // Fast shortcut enumeration
await viewShortcut(log, "Shortcut Name"); // Editor opening

// Security utilities
shellEscape(userInput); // Shell injection protection
escapeAppleScriptString(content); // AppleScript safety

Testing

83 tests covering AppleScript integration, user context tracking, security functions, name resolution, annotations, and error handling:

pnpm test        # Run complete test suite (83 tests)
pnpm lint        # Linting and type checking
pnpm format      # Code formatting

Troubleshooting

Common Issues

"Permission denied" or Error 1743 Grant automation permissions in System Preferences → Privacy & Security → Automation. Allow Terminal/Claude Desktop to control "Shortcuts Events."

"Shortcut not found" with CLI commands Apple CLI has name resolution bugs. AppleScript execution is more forgiving. Use exact names from Available Shortcuts resource. Note: UUID fallback only works with CLI commands (like shortcuts view), not with AppleScript execution.

Location-based shortcuts not working Ensure Location Services are enabled for Shortcuts app in System Preferences → Privacy & Security → Location Services.

Interactive shortcuts opening in editor This is expected behavior. Interactive shortcuts cannot display UI in MCP context but can be completed manually in the editor.

Debugging

Check shortcut execution directly:

# Test CLI discovery
shortcuts list --show-identifiers

# Test AppleScript execution
osascript -e 'tell application "Shortcuts Events" to run the shortcut named "My Shortcut"'

Check structured logging in your MCP client console for timing, permission detection, and error details.

Execution Characteristics

• Permission Context: Reliable execution vs CLI subprocess limitations

• Logging Detail: Performance timing, debugging info, permission detection

Compatibility

• macOS: 12+ (Monterey and later)

• Shortcuts: All shortcut types with permission-aware handling

• MCP Clients: Full MCP protocol compatibility

• Node.js: 22+ recommended

What's Next

• AppleScript integration with permission handling

• Structured logging and error detection

• MCPB bundle format and automated releases

• Structured logging and error detection

• Purpose annotations and smart shortcut discovery

• Case-insensitive name resolution

• JSON shortcuts cache with annotation merging

• Workflow chaining capabilities

• Performance monitoring and analytics

Contributing

1. Fork the repository

2. Create a feature branch: git checkout -b feature/amazing-feature

3. Make your changes with tests covering AppleScript integration

4. Run the test suite: pnpm test

5. Submit a pull request

License

MIT License - see for details.

Author

Law Horne

• Website: lawrencehorne.com

• Email: hello@lawrencehorne.com

• MCP Projects: lawrencehorne.com/mcp

Part of the Model Context Protocol ecosystem - enabling AI assistants to interact with external tools and data sources.