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.
Local-First
Runs on your machine with no cloud account required. AI features use your own API keys with the providers you choose.
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 or formatted output. "List all my shortcuts organized by folder" or "Create a summary of my scheduled tasks". The AI can render 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.
Available Chat Tools
The AI has access to these tools when chatting with you:
Shortcut Discovery & Execution
list_enabled_shortcuts
Lists all shortcuts available for execution, with names, folders, and descriptions.
run_enabled_shortcut
Execute a specific shortcut by name, optionally passing input parameters.
list_all_shortcuts
List all shortcuts in the system (not hidden from AI), optionally filtered by folder.
list_shortcut_folders
List all folders that contain shortcuts.
get_shortcut_details
Get detailed metadata about a shortcut including its actions and dependencies.
get_shortcut_dependency_graph
Display the dependency graph showing what other shortcuts it calls and which call it.
AI & Automation
perform_task
Perform an AI-powered task using available shortcuts and tools to accomplish a goal.
create_html_page
Create rich HTML reports, dashboards, or visualizations displayed inline in the chat.
Scheduling
list_scheduled_jobs
List all scheduled jobs with their status, timing, and metadata.
request_schedule_shortcut
Schedule a shortcut to run at a specific time, interval, or with a delay.
request_schedule_ai_task
Schedule an AI task to run automatically on a schedule.
request_manage_scheduled_job
Pause, resume, cancel, or immediately run an existing scheduled job.
Settings & Maintenance
get_shortcut_ai_settings
Get the current AI settings for a shortcut (visibility, executability, privacy).
request_update_shortcut_ai_settings
Update AI settings for a shortcut (enable/disable, privacy settings).
refresh_shortcut_metadata
Refresh cached metadata when you've edited a shortcut in Apple Shortcuts.
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 custom column layouts, sort orders, and filters as reusable presets
- Active filters display — Always see which filters are applied at a glance
- Inline actions — Run shortcuts, open in Shortcuts app, view details, download backups, see dependency graphs, configure AI settings, and more — all from the table row
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
Self-Contained Downloads
Share complex shortcuts as a single file. When a shortcut calls other shortcuts via "Run Shortcut" actions, Shortcuts Toolbox can inline all dependencies into one self-contained shortcut — no need to share each dependency separately.
The Problem
Apple Shortcuts lets you modularize workflows by calling other shortcuts with the "Run Shortcut" action. But when you want to share a shortcut that depends on others, the recipient needs to install every dependency individually. If a single piece is missing, the shortcut breaks.
The Solution
Download Self-Contained resolves the entire dependency tree and inlines each child shortcut's actions directly into the parent. The result is a single, self-contained shortcut file that anyone can install and run without needing any of the original dependencies.
How It Works
Open a shortcut with dependencies
Navigate to any shortcut that calls other shortcuts. The Download Self-Contained button appears in the download dropdown menu.
Click Download Self-Contained
Shortcuts Toolbox walks the full dependency tree, inlines every child shortcut's actions, and stitches the variable references together.
Share the file
The self-contained shortcut is automatically signed (if signing is enabled) and downloaded as a single .shortcut file ready to share.
What Happens Under the Hood
Dependency Tree Resolution
Recursively resolves all "Run Shortcut" actions, including grandchild dependencies, up to 10 levels deep. Circular dependencies are detected and skipped with a warning.
Variable Stitching
Input and output variable references are remapped at each boundary so data flows correctly between the inlined actions — just as it did when the shortcuts were separate.
UUID Remapping
Each inlined shortcut's internal action UUIDs are regenerated to prevent collisions, while preserving all internal cross-references.
Variable Namespacing
Named variables from child shortcuts are prefixed with the child's name (e.g., [Child] My Variable) to avoid collisions with the parent's variables.
Limitations
- Dynamic targets — If a "Run Shortcut" action determines its target from a variable at runtime, it cannot be inlined and will be left as-is
- Self-referencing shortcuts — Recursive shortcut calls (a shortcut that calls itself) are skipped
- Missing dependencies — If a dependency isn't installed on the system, the "Run Shortcut" action is left unchanged
In all of these cases, the compose operation continues and produces a warning so you know exactly what couldn't be inlined.
The Download Self-Contained button only appears in the download dropdown for shortcuts that have at least one "Run Shortcut" dependency.
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"
}
}
}
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
stdiosseremoteMCP Aggregation
Shortcuts Toolbox acts as an MCP aggregator — similar to Docker's MCP Toolkit gateway feature. When you connect external MCP servers as clients, their tools are automatically aggregated and exposed through the Shortcuts Toolbox MCP server.
This means external AI clients (like Claude Desktop or Cursor) connecting to Shortcuts Toolbox get access to:
- All your Apple Shortcuts (as MCP tools)
- All tools from any connected external MCP servers
- Built-in Shortcuts Toolbox tools (scheduling, AI tasks, etc.)
Think of it as a single MCP endpoint that unifies all your automation tools in one place. Configure one connection in Claude Desktop, get access to everything.