shortcut-forge

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.

Related MCP server: Shortcuts MCP

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'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.

…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

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:

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.