recipal-mcp-unofficial

一个用于 ReciPal 营养标签 API 的 MCP 服务器。它让 AI 助手可以直接读取和编辑你的食谱、配料和子食谱——包括在网页界面中需要数小时才能完成的批量操作。

非官方。 与 ReciPal 无关联、未经其认可，也不受其支持。由该产品的用户基于其公开 API 构建。

过渡项目——本仓库将被归档。 ReciPal 正在构建官方的 MCP 服务器。当他们的版本发布后，本项目将更新以指向它，然后归档为只读。不要在其上构建任何关键功能。参见 SUNSET.md。

你需要一个有效的付费 ReciPal 订阅。 API 访问是付费功能；密钥来自你的账户设置中的 API access。没有它，这个服务器什么都做不了。

用途

ReciPal 的网页界面适合编辑单个食谱。但当你需要对四十个食谱做同样的操作时就很痛苦——修复整个目录中的份量、重命名带有 (copy) 后缀的配料，或构建一组仅一种配料不同的产品变体。这个服务器暴露了 API，让助手可以循环完成这些工作，并先进行试运行。

最有价值的工具是 bulk_clone_and_swap：将一个完全配置好的食谱作为模板，克隆 N 次，并在每个克隆中替换一种配料。标签设置、标签和份量都会继承，因此克隆出来的结果是一致的。

Related MCP server: cookwith-mcp

范围和分发

刻意保持狭窄，并且会一直如此：

• 你需要克隆并自行构建的源码。 没有一键插件包，没有 npx 包，也没有出现在任何 MCP 目录或市场中。这是对 ReciPal 的承诺，不是疏忽或待办事项。

• 不发布到 npm。 package.json 有意标记为 private。

• 按 ReciPal 的要求命名为 recipal-mcp-unofficial，以免被误认为是他们的官方服务器。

添加打包分发、市场提交或更友好的消费者安装路径的拉取请求将被拒绝。参见 CONTRIBUTING.md 了解哪些内容是受欢迎的。

安装

需要 Node.js 18 或更高版本。

git clone https://github.com/BlackBlack/recipal-mcp-unofficial.git
cd recipal-mcp-unofficial
npm install
npm run build

然后将其注册到你的 MCP 客户端。对于 Claude Code：

claude mcp add --transport stdio recipal-mcp-unofficial \
  --env RECIPAL_API_KEY=your_key_here \
  -- node /absolute/path/to/recipal-mcp-unofficial/build/index.js

对于 Claude Desktop，添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "recipal-mcp-unofficial": {
      "command": "node",
      "args": ["/absolute/path/to/recipal-mcp-unofficial/build/index.js"],
      "env": { "RECIPAL_API_KEY": "your_key_here" }
    }
  }
}

重启客户端，然后让它列出你的食谱。你应该会看到 19 个可用工具。完整教程见 docs/SETUP.md。

⚠️ 在将其指向你关心的目录之前，请先阅读此内容

confirm: true 和 dry_run 防护由模型提供，而不是由你提供。 它们可以阻止措辞模糊的提示造成损害。但它们无法阻止一个坚定或困惑的代理——一个决定删除食谱的助手会在同一次调用中传入 confirm: true。ReciPal 没有撤销功能。

因此，真正具有破坏性的工具默认关闭。启用它们是运行服务器的人的有意行为，而不是对话可以做到的事情：

其他所有内容——所有读取操作以及常规的创建/更新工具——开箱即用。批量工具始终可用，但默认为 dry_run: true，并且除非调用者同时传入 dry_run: false 和 confirm: true，否则拒绝执行。

无论何种情况都建议的做法：先针对一次性食谱进行操作。 多个端点的行为与文档所暗示的不同（参见已知限制）。

配置

参见 .env.example。

工具

共 22 个工具，默认暴露 19 个。包含每个参数的生成参考文档：docs/TOOLS.md。

† 默认禁用。

写入工具接受开放的 fields 对象，而不是固定的参数列表。ReciPal 发布的文档在完整的食谱属性列表之前就截断了，因此硬编码字段名意味着猜测；相反，fields 会被直接传递，以 Rails 风格的表单编码（recipe[name]=...）发送。未记录的属性无需修改代码即可工作。如果端点偏好 JSON，请设置 as_json: true。

在写入食谱之前，先读取一个真实的食谱。 对现有食谱执行 get_recipe 会显示你的账户使用的确切属性名。

已知限制

这些是真实的、已针对实时 API 验证过的问题，在基于此构建之前值得了解：

• create_recipe_shortcut 无法工作。 它对尝试过的每种配料数组格式都返回 HTTP 422。ReciPal 的文档在参数列表之前就截断了，因此正确的格式未知。请使用 create_recipe + create_recipe_ingredient，或使用 scale_recipe 克隆已配置的模板。该工具被保留，以便可以发现正确的格式——如果你弄清楚了，请提交 PR。

• PUT /recipe_ingredients/{id} 会静默忽略 ingredient_id。 它返回 HTTP 200，但原始配料仍然保留。将一种配料替换为另一种必须通过先删除再创建来完成，这正是 bulk_clone_and_swap 内部所做的。

• ReciPal 几乎对每个响应都进行双重包装——{recipe: {recipe_ingredients: [{recipe_ingredient: {…}}]}}。从外层信封读取字段会得到 undefined 且没有错误。如果你扩展这个服务器，请使用现有的 unwrap() / extractRecords() 辅助函数。

• scale_recipe 和 create_subrecipe 的参数名未发布。 它们通过透传的 fields 工作，但在循环之前，请针对一次性食谱各运行一次并读取响应。

• 文档将 /recipes/{id}/scale 列为 PUT；实际有效的是 POST。 未经测试不要"修复"这个问题。

• 没有分页辅助。 list_recipes 每页最多 100 条；请自行遍历页面。

速率限制

ReciPal 文档说明大约 175,000 次请求/周，1,000 次/分钟（超过则返回 HTTP 429），以及最多 5 个并发标签渲染。此服务器遵循 429 并使用 Retry-After 和指数退避，当剩余请求少于 100 次时在 stderr 上发出警告，并且每个批量循环都严格串行运行，带有可配置的延迟。不要并行化标签渲染。

开发

npm run typecheck   # tsc --noEmit
npm run build       # -> build/index.js
npm test            # offline smoke tests, no API key or network needed
npm run gen:docs    # regenerate docs/TOOLS.md from the running server
npm run verify      # all of the above

docs/TOOLS.md 通过启动构建后的服务器并询问其自身的工具列表来生成，因此参考文档不会与代码脱节。如果它过期了，CI 会失败。如果你添加或更改了工具，请运行 npm run build && npm run gen:docs 并提交结果。

欢迎在上述范围内贡献——从 CONTRIBUTING.md 开始，然后参阅 docs/TESTING.md 了解如何针对真实账户验证更改，以及 docs/DESIGN.md 了解各部分如何组合。

许可证

Apache-2.0。

"ReciPal" 是其所有者的商标，此处仅用于描述此软件所交互的对象。