shortcut-forge: the Apple Shortcuts MCP server that ships shortcuts that actually run

Describe an automation to Claude, Codex or ChatGPT → get a signed .shortcut file → tap it on your iPhone.
Apple Shortcuts MCP · iOS Shortcuts generator · Siri Shortcuts for AI agents · iOS 27 aware · macOS auto-signing · open shortcut library

English · 한국어 · 日本語 · 简体中文

---

The problem (you've probably said one of these)

"I asked ChatGPT for a shortcut and got fourteen steps to tap in by hand."

"The file imported fine. Then: 'Choose a value for each parameter of this action.'"

"iOS 27 can build a shortcut from a description, but only on my iPhone 15 Pro, one shortcut at a time, and I can't review or version what it changed."

"Every MCP server I found for Shortcuts only runs shortcuts I already have."

"Every time I fix the family shortcut, everyone has to download it again."

Apple Shortcuts is the most powerful automation layer on the iPhone, and still the hardest thing to get an AI to produce. The file format is undocumented, a structurally valid plist can still break on the device, and nothing catches the difference until you're staring at an error on your phone.

The fix

shortcut-forge is an MCP server, a Claude plugin and a Python library that turns "make me a shortcut that…" into a signed .shortcut file that has been checked against the ways shortcuts really fail on iPhone.

You:     "Every time I take my vitamins, log them to Apple Health, tick off today's reminder
          and set up tomorrow's, but never create duplicates."
Claude:  → shortcut_library("supplements") → shortcut_from_template("supplement-tracker", …)
         ✓ 750 actions · 0 lint errors · signed on your Mac
         → ~/Downloads/shortcut-forge/Supplement Check.shortcut   (AirDrop / iCloud Drive → tap → Add)

	Apple "Describe a Shortcut" (iOS 27)	Asking a chatbot	Other Shortcuts MCPs	shortcut-forge
Works from Claude, Codex, ChatGPT, Cursor…	–	✓	some	✓
No new iPhone required	needs iPhone 15 Pro+ / Apple silicon	✓	✓	✓
Output you can read, diff, version, review	–	text	varies	JSON spec + plist
Checked against real on-device failures	n/a (native)	–	structure only	15 semantic rules
Signed and importable on iPhone	✓ (native)	–	rarely	✓ auto on macOS
Updates without re-downloading	–	–	–	remote config + update check
Shared, remixable library	–	–	–	✓ 20+ entries

Apple's built-in builder is great for quick personal one-liners and lives right in the app; use it. Reach for shortcut-forge when you want an AI you already use to build something bigger, reviewable and shareable.

Install

Claude Code (plugin = MCP server + skill + /shortcut command)

/plugin marketplace add Hyunki6040/shortcut-forge
/plugin install shortcut-forge@shortcut-forge

Claude Desktop: double-click shortcut-forge.mcpb from Releases, or:

{ "mcpServers": { "shortcut-forge": { "command": "uvx", "args": ["shortcut-forge", "mcp"] } } }

OpenAI Codex

codex mcp add shortcut-forge -- uvx shortcut-forge mcp

ChatGPT, Gemini, any chatbot: connect over HTTP (shortcut-forge mcp --http) or, with no MCP at all, paste prompts/LLM_PROMPT.md and drop the JSON it writes into the Mac watch folder (below). Cursor, VS Code, Windsurf, Gemini CLI: see docs/CLIENTS.md.

Python / CLI

uv tool install shortcut-forge        # or: pipx install shortcut-forge
shortcut-forge template supplement-tracker --sign

Mac auto-signing: drop a spec, get a shortcut

iOS only imports signed shortcuts, and only a Mac can sign them. shortcut-forge makes that invisible:

shortcut-forge mac install-agent      # launchd agent, starts at login

iCloud Drive/Shortcut Forge/          ← drop *.json specs or *.unsigned.shortcut (from any device or AI)
iCloud Drive/Shortcut Forge/Signed/   ← signed .shortcut appears in seconds → open it on your iPhone
iCloud Drive/Shortcut Forge/Failed/   ← anything that failed lint, with a .log explaining why

Ask ChatGPT on your phone for a spec, save it to Files, and the shortcut is ready on the same phone before you finish your coffee. In Claude Desktop / Claude Code on a Mac, signing happens inside the tool call.

What people build with it

From the Open Shortcut Library. Every one is a readable spec, lint-clean in CI.

	Shortcut	What it does
🌤	Morning Brief	Your messy thoughts → a 3-line plan by Apple Intelligence → a reminder
🎯	Focus Block	Blocks 25/50/90 min on your calendar from right now
✅	Meeting → Action Items	Notes in, reminders out, summary on the clipboard
🌐	Clipboard Translate	Translate whatever you copied, result back on the clipboard
☕️	Caffeine Log	One tap → Apple Health, warns past 400 mg
💸	Expense Log	Amount + category → CSV in Stored Content → paste into your sheet
🅿️	Parking Spot	Save where you parked, open it in Maps later
📡	Webhook Trigger	POST JSON to n8n / Zapier / Home Assistant
🐙	GitHub Issue	File an issue from your phone
🍱	Lunch Picker	Reads options from a JSON URL: edit once, every phone updates, no reinstall
💊	영양제 체크 (the original)	The real 1,073-action shortcut that started this project. Two people, ten time slots, alternate-day doses, Health + Reminders + Apple Intelligence

…and more: mood journal, sleep diary, grocery list, weather voice brief, low-battery nudge, water log.

Built something? Share it → Tell your AI "submit this to the shortcut-forge library".

Use it

Plain language in any MCP client:

• "Make a shortcut that asks how I slept and every Sunday has Apple Intelligence summarise the week."
• "Start from the library's expense log, but in won and with my categories."
• "Here's my exported shortcut. Why does it crash?" → shortcut_lint + shortcut_inspect

Python: variables work in f-strings.

from shortcut_forge import Shortcut

sc = Shortcut("Hello", version="1.0.0")
name = sc.ask("What's your name?")
with sc.if_(name, "contains", "Claude") as br:
    sc.notify("Hi twin", f"Nice to meet another Claude, {name}")
    br.otherwise()
    sc.notify("Hi", f"Welcome, {name}")
sc.storage_set("last_name", name)       # iOS 27 Stored Content, done right
sc.health_log("Vitamin D", "50")        # mcg → mg handled for you
sc.save("Hello.unsigned.shortcut")

JSON (what the MCP tools and chatbots write): 50+ step types, plus a raw escape hatch for any action.

{"name": "Hello", "version": "1.0.0", "actions": [
  {"ask": "What's your name?", "as": "name"},
  {"if": ["{{name}}", "contains", "Claude"],
   "then": [{"notify": "Hi twin", "body": "{{name}}"}],
   "else": [{"notify": "Hi", "body": "Welcome, {{name}}"}]}
]}

MCP tools

Tool	What it does
shortcut_build	JSON spec → .shortcut, always linted, signed on macOS
shortcut_library	Browse / fetch 20+ community shortcuts as starting points
shortcut_from_template	supplement-tracker (multi-user), water-log
shortcut_lint	15 rules (SF000–SF014) for any unsigned shortcut, including ones exported from the app
shortcut_inspect	Indented outline of a shortcut
shortcut_sign	shortcuts sign wrapper, verifies the AEA1 header
shortcut_publish	Sign + manifest.json so installed copies can update themselves
shortcut_submit	Package your shortcut + PR commands for the library
shortcut_llm_prompt	System prompt for chatbots without MCP
shortcut_reference	spec · pitfalls · lint-rules · health-types · templates · library · ios27

Field notes: why "it imported" isn't "it works"

We built a two-person tracker by having Claude generate the plist. It took more than a dozen import → run → screenshot rounds. Every failure was invisible at build time:

What we wrote	What the iPhone did	Rule
Stored Content set from a variable	Saved nothing, no error	SF001
Health sample "77.4 mcg" of B12	Logged 77,400,000 mcg (the unit string is read as grams)	SF003
If <dictionary value> is "Lunch"	Comparison field empty → run aborted	SF005
Delete a stored key that isn't there	Error 16	SF002
Mark found reminders as done	A picker popped up mid-run	SF007
Get Contents of URL on every run	Offline once → whole shortcut aborts	SF014
Create tomorrow's reminder	Duplicates on every run	builder

The builder can't produce these; the linter catches them in any shortcut. Full notes: PITFALLS.md.

What is a .shortcut file?

• A .shortcut file (not .short or .shortcuts) is an Apple Shortcuts workflow: a binary property list (WFWorkflowActions, WFWorkflowIcon, …) where every action is an identifier like is.workflow.actions.gettext plus parameters. Variables are "token strings" with UTF-16 offsets.
• Since iOS 15, shared shortcut files must be signed. A signed file is an Apple Encrypted Archive whose first bytes are AEA1. Unsigned plists import on a Mac but iOS refuses them.
• Signing modes: anyone (any device can import) or people-who-know-me (contacts only). Only macOS can sign (shortcuts sign), which is why shortcut-forge automates the Mac side.
• .wflow was the format of the old Workflow app that became Shortcuts; iCloud links (icloud.com/shortcuts/…) are snapshots created from the app and can't be generated or updated programmatically.

FAQ

Do I need a Mac? To sign, yes (Apple's rule). Building and linting run anywhere; the watch-folder agent lets one Mac sign for every device you own. Does my data leave my machine? No. The server runs locally; nothing is uploaded. Library shortcuts that use remote_config fetch only the JSON URL they name. Is this affiliated with Apple or Anthropic? No. It is an independent open-source project. iOS 26 or older? Most actions work; Stored Content needs iOS 27 and Use Model needs Apple Intelligence (the linter flags these as SF013).

Roadmap: the update problem (help wanted)

Today every shortcut fix means re-sign → re-share → everyone re-downloads and taps "Replace". v0.2 ships the first answers (remote_config for data, update_check + publish for code, a signing watch folder). Next is a Shortcut Hub: one-command publish to GitHub, a stable install URL that always serves the latest version, settings that survive updates, a signing relay for teams, and an experimental loader pattern. Read ROADMAP.md and pick something. Device reports from real iPhones are the most valuable contribution of all.

Contributing

• Share a shortcut → LIBRARY.md
• Found a new way shortcuts break? Open a pitfall issue with the error screenshot and the smallest spec; it becomes a lint rule and a builder fix.
• Code → CONTRIBUTING.md · agents read AGENTS.md

MIT licensed. Not affiliated with Apple Inc. or Anthropic. "Shortcuts" and "Siri" are trademarks of Apple Inc.

If shortcut-forge saved you a round of error screenshots, a ⭐ helps the next person find it.

_{Keywords: Apple Shortcuts MCP, iOS Shortcuts MCP server, Siri Shortcuts AI generator, create .shortcut file programmatically, sign shortcut macOS CLI, Claude Shortcuts, Codex Shortcuts, ChatGPT Shortcuts, iOS 27 Shortcuts Stored Content, Apple Health shortcut, shortcut library.}