Shortcut Forge (Apple Shortcuts MCP)

shortcut-forge：能生成真正可运行快捷指令的 Apple 快捷指令 MCP 服务

向 Claude、Codex 或 ChatGPT 描述一项自动化 → 获取经过签名的 .shortcut 文件 → 在 iPhone 上轻点即可。
Apple 快捷指令 MCP · iOS 快捷指令生成器 · 面向 AI Agent 的 Siri 快捷指令 · 适配 iOS 27 · macOS 自动签名 · 开源快捷指令库

英语 · 한국어 · 日本語 · 简体中文

---

问题所在（你可能说过下面这些话）

“我让 ChatGPT 帮我做一个快捷指令，结果得到 14 个需要手动逐步点选的步骤。”

“文件导入成功了。然后出现：‘为此操作的每个参数选择一个值。’”

“iOS 27 可以根据描述构建快捷指令，但只能在我的 iPhone 15 Pro 上一次做一个，而且我无法审查或追踪它所做更改的版本。”

“我找到的每个快捷指令 MCP 服务都只能运行我已有的快捷指令。”

“每次我修复家庭快捷指令，所有人都得重新下载。”

Apple 快捷指令是 iPhone 上最强大的自动化层，却仍然是最难让 AI 生成的东西。文件格式没有文档说明，即便 plist 结构有效，也仍可能在设备上出错；只有当你盯着手机上的错误信息时，才能发现问题。

解决方案

shortcut-forge 是一个 MCP 服务、一个 Claude 插件和一个 Python 库，可将*“帮我做一个快捷指令，用来……”*转变为经过签名的 .shortcut 文件，并针对快捷指令在 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“描述快捷指令”（iOS 27）	向聊天机器人提问	其他快捷指令 MCP 服务	shortcut-forge
可通过 Claude、Codex、ChatGPT、Cursor 等使用	–	✓	部分支持	✓
无需新款 iPhone	需要 iPhone 15 Pro+ / Apple silicon	✓	✓	✓
输出可读取、比较差异、管理版本和审查	–	文本	不一	JSON 规格 + plist
根据真实设备故障进行检查	不适用（原生功能）	–	仅检查结构	15 条语义规则
已签名，可导入 iPhone	✓（原生功能）	–	很少	✓ macOS 上自动签名
无需重新下载即可更新	–	–	–	远程配置 + 更新检查
可共享、可改编的库	–	–	–	✓ 20+ 条目

Apple 内置的构建器很适合快速创建个人的一句话快捷指令，而且就在 App 中；不妨直接使用。若想让你已经在用的 AI 构建更复杂、可审查、可分享的内容，就用 shortcut-forge。

安装

Claude Code（插件 = MCP 服务 + 技能 + /shortcut 命令）

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

Claude Desktop：从 Releases 双击 shortcut-forge.mcpb，或：

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

OpenAI Codex

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

ChatGPT、Gemini 及任何聊天机器人：通过 HTTP 连接（shortcut-forge mcp --http），或者完全不使用 MCP，粘贴 prompts/LLM_PROMPT.md，再将生成的 JSON 放入 Mac 监视文件夹（见下文）。 Cursor、VS Code、Windsurf、Gemini CLI：参见 docs/CLIENTS.md。

Python / 命令行

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

Mac 自动签名：放入规范文件，获取快捷指令

iOS 只会导入已签名的快捷指令，而且只有 Mac 能为其签名。shortcut-forge 让这一切变得无形：

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

用手机上的 ChatGPT 编写规范文件，将其存入“文件”应用，在你喝完咖啡之前，同一部手机上就能用上快捷指令。在 Mac 上使用 Claude Desktop / Claude Code 时，签名会在工具调用中完成。

大家用它构建的内容

来自 Open Shortcut Library。每个快捷指令都有易读的规范文件，并且通过 CI 检查。

	快捷指令	功能
🌤	Morning Brief	将你杂乱的想法整理成计划 → 由 Apple Intelligence 生成 3 行内容 → 添加提醒事项
🎯	Focus Block	从现在开始，在日历中安排 25/50/90 分钟的专注时段
✅	Meeting → Action Items	输入笔记，输出提醒事项，并将摘要复制到剪贴板
🌐	Clipboard Translate	翻译你复制的内容，并将结果放回剪贴板
☕️	Caffeine Log	轻点一下 → 记录到 Apple Health，摄入量超过 400 mg 时发出警告
💸	Expense Log	金额 + 类别 → 保存为 Stored Content 中的 CSV → 粘贴到你的表格
🅿️	Parking Spot	保存停车位置，之后在 Maps 中打开
📡	Webhook Trigger	向 n8n / Zapier / Home Assistant 发送 POST JSON
🐙	GitHub Issue	用手机创建 issue
🍱	Lunch Picker	从 JSON URL 读取选项：只需编辑一次，所有手机都会更新，无需重新安装
💊	영양제 체크 (the original)	真正包含 1,073 个操作的快捷指令，也是本项目的起点。支持两人、十个时段、隔日服用，以及 Health + Reminders + Apple Intelligence

……还有更多内容：情绪日记、睡眠日记、购物清单、天气语音简报、低电量提醒、饮水记录。

构建了什么？分享吧 → 告诉你的 AI：“将这个提交到 shortcut-forge 库”。

使用方法

自然语言，适用于任何 MCP 客户端：

• “创建一个快捷指令，询问我的睡眠情况，并在每周日让 Apple Intelligence 总结这一周。”
• “从库中的费用记录快捷指令开始，但使用韩元和我自己的类别。”
• “这是我导出的快捷指令。为什么会崩溃？” → shortcut_lint + shortcut_inspect

Python：变量可在 f-string 中使用。

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（MCP 工具和聊天机器人生成的内容）：支持 50 多种步骤类型，另有 raw 逃生口，可用于任何操作。

{"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 工具

工具	功能
shortcut_build	JSON 规格 → .shortcut，始终经过 lint 检查，并在 macOS 上签名
shortcut_library	浏览／获取 20 多个社区快捷指令，作为起点
shortcut_from_template	supplement-tracker（多用户）、water-log
shortcut_lint	为任何未签名的快捷指令提供 15 条规则（SF000–SF014）检查，包括从应用导出的快捷指令
shortcut_inspect	以缩进大纲形式查看快捷指令
shortcut_sign	shortcuts sign 封装器，验证 AEA1 标头
shortcut_publish	签名并生成 manifest.json，以便已安装的副本自行更新
shortcut_submit	打包你的快捷指令及提交到库的 PR 命令
shortcut_llm_prompt	为不支持 MCP 的聊天机器人提供系统提示词
shortcut_reference	spec · pitfalls · lint-rules · health-types · templates · library · ios27

实战笔记：为什么“导入成功”不代表“能正常运行”

我们让 Claude 生成 plist，做了一个双人追踪器。经过十几轮“导入 → 运行 → 截图”才完成。每次失败在构建时都无从察觉：

我们写的内容	iPhone 的表现	规则
将「存储内容」设为一个变量	保存了空内容，没有报错	SF001
B12 健康样本“77.4 mcg”	记录为77,400,000 mcg（单位字符串被当作克读取）	SF003
If <dictionary value> is "Lunch"	比较字段为空 → 运行中止	SF005
删除一个不存在的已存储键	错误 16	SF002
将找到的提醒事项标记为已完成	运行中途弹出选择器	SF007
每次运行都获取 URL 内容	离线一次 → 整个快捷指令中止	SF014
创建明天的提醒事项	每次运行都会重复创建	构建器

构建器无法避免这些问题；lint 检查器能在任何快捷指令中捕捉到它们。完整说明见： PITFALLS.md。

什么是 .shortcut 文件？

• .shortcut 文件（不是 .short 或 .shortcuts）是 Apple「快捷指令」工作流：一种二进制属性列表 （WFWorkflowActions、WFWorkflowIcon 等），其中每个操作都是类似 is.workflow.actions.gettext 的标识符，并带有参数。变量是带 UTF-16 偏移量的“令牌字符串”。
• 从 iOS 15 开始，共享的快捷指令文件必须经过签名。已签名文件是 Apple 加密存档，开头 字节为 AEA1。未签名的 plist 可在 Mac 上导入，但 iOS 会拒绝。
• 签名模式：anyone（任何设备都能导入）或 people-who-know-me（仅限联系人）。只有 macOS 可以签名 （shortcuts sign），因此 shortcut-forge 会自动处理 Mac 端的操作。
• .wflow 是旧版 Workflow 应用（后来成为「快捷指令」）使用的格式；iCloud 链接（icloud.com/shortcuts/…） 是从应用创建的快照，无法通过编程方式生成或更新。

常见问题

我需要 Mac 吗？ 签名需要（这是 Apple 的规定）。构建和 lint 检查可在任何设备上运行；监视文件夹 Agent 可让 一台 Mac 为你拥有的所有设备签名。 我的数据会离开我的设备吗？ 不会。服务在本地运行；不会上传任何内容。使用 remote_config 的库中快捷指令只会获取其指定的 JSON URL。 这与 Apple 或 Anthropic 有关联吗？ 没有。这是一个独立的开源项目。 iOS 26 或更早版本呢？ 大多数操作都能运行；「存储内容」需要 iOS 27，「使用模型」需要 Apple Intelligence（ lint 检查器会将这些标记为 SF013）。

路线图：更新难题（欢迎贡献）

目前，每次修复快捷指令都意味着重新签名 → 重新分享 → 所有人重新下载并点击“替换”。v0.2 首次提供了解决方案 （用于数据的 remote_config，用于代码的 update_check + publish，以及签名监视文件夹）。下一步是 Shortcut Hub：通过一条命令发布到 GitHub、始终提供最新版本的稳定安装 URL、更新后仍能保留的设置、面向团队的签名中继，以及一种实验性加载器模式。 阅读 ROADMAP.md，挑选一项参与。来自真实 iPhone 的设备报告是最有价值的贡献。

贡献

• 分享快捷指令 → LIBRARY.md
• 发现了快捷指令失效的新方式？ 请提交一个 陷阱 问题，并附上错误截图和最小规格；它 会转化为 lint 规则和构建器修复。
• 代码 → CONTRIBUTING.md · Agent 请阅读 AGENTS.md

采用 MIT 许可。与 Apple Inc. 或 Anthropic 无关联。“Shortcuts”和“Siri”是 Apple Inc. 的商标。

如果 shortcut-forge 帮你省去了一轮错误截图，点个 ⭐ 能让其他人更容易找到它。

_{关键词：Apple Shortcuts MCP、iOS Shortcuts MCP 服务、Siri Shortcuts AI 生成器、以编程方式创建 .shortcut 文件、使用 macOS CLI 为快捷指令签名、Claude Shortcuts、Codex Shortcuts、ChatGPT Shortcuts、iOS 27 Shortcuts Stored Content、Apple Health 快捷指令、快捷指令库。}