Shortcuts Toolbox Documentation
Shortcuts Toolbox is a powerful, local-first application for managing, automating, and supercharging your Apple Shortcuts with AI. It combines an Express backend with an Angular frontend, a built-in MCP server, multi-provider AI chat, scheduling, dependency visualization, and a comprehensive REST API.
AI-Powered
Chat with AI to run, analyze, and manage your shortcuts. Supports OpenAI, Anthropic, and Google.
MCP Server
Expose shortcuts as tools for Claude Desktop, Cursor, and any MCP-compatible client.
Scheduling
Run shortcuts and AI tasks on intervals, at specific times, or on delay with cron expressions.
Privacy-First
Runs entirely on your machine. Your shortcuts and data never leave your local environment.
Installation
Shortcuts Toolbox is a downloadable macOS application. No coding required — just download, configure, and run.
Prerequisites
- macOS 13 (Ventura) or later
- Apple Shortcuts app installed
- At least one AI provider API key (OpenAI, Anthropic, or Google) for AI features
Setup
- Download the latest release from the homepage
- Unzip and move Shortcuts Toolbox to your Applications folder
- Launch the app — it will guide you through initial configuration
Quick Start
After starting Shortcuts Toolbox, here's how to get productive fast:
Authenticate
Enter your API token on the login screen. This secures your local instance against unauthorized access.
Configure AI Providers
Navigate to Settings → AI Providers and add your API keys for OpenAI, Anthropic, or Google to enable AI features.
Enable Shortcuts
From the Shortcuts Library, select which shortcuts should be visible and executable by AI. Toggle the checkbox next to each shortcut to control access.
Start Chatting
Go to AI → Chat, create a new conversation, and ask the AI to run shortcuts, explain them, schedule tasks, or generate reports.
AI Chat Interface
The AI Chat is the heart of Shortcuts Toolbox. Almost everything you can do in the app can be done through conversation. Instead of navigating menus or memorizing features, just tell the AI what you want to accomplish in plain English.
Think of the AI as your personal automation assistant. It knows about all your shortcuts, understands scheduling, can generate reports and visualizations, and orchestrates complex multi-step workflows — all through natural conversation. You stay in control of what the AI can access and execute.
What You Can Do Through Chat
Run Any Shortcut
Just say "Run my Morning Routine shortcut" or "Execute the backup script with input 'documents'". The AI handles parameters and shows you the results.
Schedule Anything
"Run this every weekday at 9am", "Remind me to check backups in 2 hours", or "Schedule a weekly report every Monday". Natural language scheduling — no cron syntax required.
Find & Explore Shortcuts
"What shortcuts do I have for photos?", "Show me all shortcuts in my Work folder", or "Which shortcuts use the Calendar app?". The AI helps you discover and understand your library.
Generate Reports & Dashboards
Ask for summaries, statistics, or visualizations. "Show me a chart of my shortcut usage this week" or "Create a report of all my scheduled tasks". The AI renders rich HTML output inline.
Analyze Dependencies
"What shortcuts does Morning Routine call?", "Show me orphaned shortcuts", or "Which shortcuts would break if I delete this one?". Understand your shortcut ecosystem.
Chain Multiple Actions
"First run the cleanup script, then if it succeeds, run the backup, and finally send me a notification". The AI orchestrates complex workflows in a single conversation.
Use External MCP Tools
If you've connected external MCP servers, the AI can use those tools too. "Use the weather service to check tomorrow's forecast" or combine tools from multiple sources.
Get Help & Explanations
"Explain what my Backup shortcut does step by step", "How do I set up scheduling?", or "What's the difference between AI Tasks and chat?". The AI is your built-in documentation.
Example Conversations
Multi-Provider Support
Choose your preferred AI model for each conversation. Shortcuts Toolbox supports OpenAI (GPT-4o, GPT-4, etc.), Anthropic (Claude), and Google (Gemini). Switch models anytime — different models may work better for different tasks.
Conversation History
All your conversations are saved and searchable. Pick up where you left off, reference past discussions, or search across all chats to find that workflow you set up months ago. The AI maintains context within each conversation, so you can have extended back-and-forth discussions.
AI Controls
You control exactly what the AI can see and do. For each shortcut, configure:
- Visible to AI — Whether the AI knows this shortcut exists
- Executable by AI — Whether the AI is allowed to run this shortcut
- Private contents — Whether to hide the shortcut's internal actions from the AI
This gives you fine-grained control over privacy and what automations the AI can help with.
Shortcuts Library
The Shortcuts Library provides a comprehensive table view of all your Apple Shortcuts. It's your central hub for browsing, searching, and managing your shortcut library.
Key Features
- Searchable columns — Filter by name, folder, action count, or any metadata field
- Folder filtering — Quickly scope the view to specific shortcut folders
- Column picker — Customize which columns are visible in the table
- Saved views — Save and recall your filter/column presets
- Active filters display — Always see which filters are applied at a glance
- Inline actions — Run shortcuts, view details, or jump to the dependency graph directly from the table
AI Tasks
AI Tasks are reusable automation templates. Define a prompt, select eligible shortcuts, configure scheduling, and let the AI execute complex multi-step workflows automatically.
Creating an AI Task
- Navigate to AI → Tasks and click New Task
- Give the task a descriptive name
- Write detailed AI instructions describing what the task should accomplish
- Select which shortcuts the AI is allowed to use for this task
- Configure MCP server/tool integrations if needed
- Set up scheduling (cron expression, interval, or one-time delay)
- Save the task
Task Execution
When a task executes, the AI processes the instructions using the configured model, calls any necessary shortcuts or MCP tools, and produces output. The execution history is preserved, including all tool calls, outputs, and any errors that occurred.
Scheduling
The built-in scheduler lets you automate shortcut runs and AI tasks using flexible timing options. Jobs are managed centrally and their execution history is fully tracked.
Schedule Types
0 9 * * 1-5 for weekdays at 9am)Dependency Graphs
Visualize the relationships between your shortcuts with interactive graphs. Understand which shortcuts call each other, find orphaned shortcuts, and explore your shortcut ecosystem at a glance.
Graph Features
- Interactive visualization — Zoom, pan, and drag nodes to explore the graph
- Color-coded nodes — Different colors for different shortcut types and states
- Adjustable depth — Control how many levels of dependencies to show
- Missing shortcut detection — Optionally show shortcuts that are referenced but don't exist
- App Store link toggle — Show or hide connections to App Store shortcuts
- Single or multi-shortcut view — Focus on one shortcut's dependencies or see the full ecosystem
Shortcut Management
Beyond the library table view, Shortcuts Toolbox provides a rich detail view for each shortcut.
Shortcut Detail View
- Full metadata display — See all metadata including name, folder, action count, creation date, and more
- JSON structure view — Inspect the raw shortcut structure
- Run with parameters — Execute the shortcut directly, optionally passing input parameters
- Scoped dependency graph — View the dependency graph centered on this shortcut
- AI explanation — Let the AI analyze and explain what a shortcut does
- Execution history — View all past runs of the shortcut with their results
- AI settings — Configure visibility, executability, and privacy per shortcut
- iCloud link generation — Generate shareable iCloud links for your shortcuts
Backups & Maintenance
Shortcuts Toolbox includes a built-in backup system to protect your configuration and shortcut data.
Backup Features
- Automatic backups — Schedule backups on any cron interval
- Manual backups — Trigger a backup at any time with one click
- Custom naming — Name your backups for easy identification
- Download backups — Download backup archives for off-site storage
- Restore from backup — Upload and restore from any previous backup file
- Backup folder selection — Choose where backups are stored on your filesystem
Maintenance Tools
- Metadata refresh — Force a re-sync of all shortcut metadata from Apple Shortcuts
- AI-assisted cron — Get help writing cron expressions with natural language
Audit Log
Every shortcut execution, AI tool call, and MCP interaction is logged in the unified audit log. This gives you complete visibility into what happened, when, and what the results were.
Tracked Events
- Shortcut runs (manual and scheduled)
- AI task executions
- AI tool calls (shortcuts executed by AI)
- Internal Shortcuts Toolbox tool calls
- MCP tool calls (from external servers)
- MCP server tool calls (from external clients)
Audit entries can be individually deleted or bulk-cleared. All entries include timestamps, duration, input parameters, output data, and any errors.
MCP Server Setup
Shortcuts Toolbox includes a built-in MCP (Model Context Protocol) server that exposes your shortcuts as tools to any MCP-compatible AI client, including Claude Desktop, Cursor, Windsurf, and more.
Supported Transports
Claude Desktop Configuration
Add the following to your claude_desktop_config.json:
{
"mcpServers": {
"shortcuts-toolbox": {
"url": "http://localhost:4724/api/mcp"
}
}
}
Remote Access
For remote access (e.g., via Cloudflare Tunnel), OAuth 2.0 with PKCE is supported for secure authentication. See the OAuth & Security section for details.
Available MCP Tools
When an MCP client connects to Shortcuts Toolbox, it gets access to the following tools:
list_shortcuts
List all enabled shortcuts with their names, folders, and action counts.
run_shortcut
Execute a specific shortcut by name, optionally passing input parameters. Returns the shortcut's output.
get_shortcut_details
Get detailed metadata about a shortcut including its actions, dependencies, and AI settings.
perform_ai_task
Delegate a complex task to the Shortcuts Toolbox AI, which can orchestrate multiple shortcuts and tools.
Only shortcuts that are marked as "enabled" in the Shortcuts Toolbox UI will be visible and executable via MCP. Additionally, any external MCP servers you've connected as clients will also have their tools exposed.
MCP Client
Beyond acting as an MCP server, Shortcuts Toolbox can also connect to other MCP servers as a client. This means the AI chat and AI tasks can use tools from external MCP servers in addition to your local shortcuts.
Connecting External Servers
Navigate to Settings → MCP Client and add your external MCP server configurations:
{
"mcpServers": {
"my-external-server": {
"type": "sse",
"url": "http://example.com/mcp",
"enabled": true
},
"local-stdio-server": {
"type": "stdio",
"command": "node",
"args": ["./my-server.js"],
"enabled": true
}
}
}
Supported Client Transport Types
stdiosseremoteOAuth & Security
For remote MCP connections, Shortcuts Toolbox implements a full OAuth 2.0 Authorization Server with PKCE support. This allows MCP clients to securely authenticate without exposing API tokens directly.
OAuth Endpoints
/.well-known/oauth-protected-resource/.well-known/oauth-authorization-server/oauth/register/oauth/authorize/oauth/tokenRegistration Window
For security, dynamic client registration is disabled by default. You can open a temporary registration window from Settings → MCP Server to allow new clients to register. The window automatically closes after the configured timeout.