Apple Shortcuts

Apple Shortcuts MCP

MCP server for Apple Shortcuts on macOS.

Provides access to shortcuts for discovery, inspection, and execution. Run shortcuts with structured input and output handling.

When to use

• Triggering existing Apple Shortcuts from agents
• Local automation without shell orchestration
• Smaller scope than the all-in-one server

What It Does

• List shortcuts and folders
• Inspect shortcut details
• Run shortcuts with input/output handling
• Tool discovery helpers search_tools and get_tool_info for context-constrained clients
• Shortcut resources and execution prompts
• Health and state checks: shortcuts_health, shortcuts_permission_guide, shortcuts_refresh_state

Install On This Mac

Quick start (uvx, from PyPI)

With uv installed:

uvx apple-shortcuts-mcp

No clone, no venv management.

From a clone

git clone https://github.com/JonathanRReed/Apple-MCPs.git

cd Apple-MCPs uv sync --all-packages

This builds one workspace environment with every server's entry point in .venv/bin (for example .venv/bin/apple-shortcuts-mcp). You can also point an MCP client at AppleShortcuts-MCP/start.sh, which prefers uv run and falls back to a plain venv bootstrap (Python 3.11+ required).

Install In AI Agents

Generic MCP client config

{

"mcpServers": { "apple-shortcuts": { "command": "uvx", "args": ["apple-shortcuts-mcp"], "env": { "APPLE_SHORTCUTS_MCP_SAFETY_MODE": "full_access" } } } }

Running from a clone instead? Use /path/to/Apple-MCPs/AppleShortcuts-MCP/start.sh as the command with empty args.

Claude Code example

claude mcp add --transport stdio --scope user apple-shortcuts -- uvx apple-shortcuts-mcp

--scope user makes the server available in every project. To share it with one repository through its .mcp.json instead, use --scope project.

Transport

stdio is the default and recommended transport. Set APPLE_SHORTCUTS_MCP_TRANSPORT=streamable-http (with optional APPLE_SHORTCUTS_MCP_HOST and APPLE_SHORTCUTS_MCP_PORT) to serve Streamable HTTP instead.

Output Folders

shortcuts_run_shortcut writes output_path only inside the allowed folders and returns PATH_NOT_ALLOWED for any other path. Set APPLE_SHORTCUTS_MCP_ALLOWED_ROOTS to a comma-separated list of folders (~ means your home folder), or "Folders Shortcuts may write to" in the Claude Desktop extension settings. Without it, Shortcuts uses APPLE_FILES_MCP_ALLOWED_ROOTS, then the same defaults as Files: Desktop, Documents, Downloads and iCloud Drive, where they exist.

macOS Requirements

• the built-in shortcuts CLI must be available

Launch Checklist

• Add uvx apple-shortcuts-mcp (or a clone's AppleShortcuts-MCP/start.sh) to your MCP client
• Reload or reconnect the client so the Shortcuts tool surface is loaded into context
• Call shortcuts_health first
• If the CLI is unavailable, call shortcuts_permission_guide
• After changing the Shortcuts catalog, call shortcuts_refresh_state

Prompting Notes

• tools/list returns the full Shortcuts tool surface. Context-constrained clients can use search_tools first, then get_tool_info for the Shortcuts tool they need.
• If the user asks for a shortcut vaguely, list available shortcuts first.
• Run a shortcut only after confirming which shortcut to run.

Related

• Apple-Tools-MCP