plan-to-eat

🍽️ plan-to-eat-mcp

别再手动输入食谱，直接说给它听。 通过 Model Context Protocol，让你最喜欢的大模型访问你的 Plan to Eat 食谱库、规划器 和购物清单。

一款即插即用的 MCP 服务、一个命令行工具，以及一个独立的 Node 客户端，可让 Claude、 ChatGPT、任何支持 MCP 的助手，或你自己的 Shell 完全读写你的 Plan to Eat 账户。

You:  "Save the Bon Appétit miso pasta from this URL and tag it weeknight."
LLM:  ✓ created recipe #48,872,094 — 7 ingredients, 25 min, tagged weeknight.

You:  "Plan dinner around it Tuesday and add the missing pantry items to my
       shopping list."
LLM:  ✓ event created 2026-05-05 / dinner / 4 servings.
      ✓ shopping list now reflects miso, mirin, and dashi.

……或者，如果你不想跟任何东西交谈：

$ plan-to-eat get-planner-week 2026-05-04
start_date  2026-05-04
end_date    2026-05-10

ID        DATE        SECTION    KIND        RECIPE_ID  RECIPE_TITLE        DESCRIPTION            SERVINGS
────────  ──────────  ─────────  ──────────  ─────────  ──────────────────  ─────────────────────  ────────
67698872  2026-05-05  breakfast  recipe      17314561   Breakfast Sandwich                         8
67483177  2026-05-05  dinner     ingredient                                 Asparagus (in season)  0
67710784  2026-05-06  dinner     note                                       Cucumber salad         0

3 rows

就是这样。无需重新输入食谱，无需把 URL 复制粘贴到手机应用。只需 开口说。

❤️ 为什么选择 Plan to Eat？

如果你还没在用，Plan to Eat 确实是我用过的最好的膳食规划应用：

• 随处剪藏食谱的导入器，在真实的美食博客上也确实好用。
• 拖放式每周规划器，会自动将食材汇总到购物清单中，并智能处理单位和储藏室去重。
• 永远属于你——你的食谱库可移植、可导出，不会被算法挟持。
• 适合家庭使用——可在应用内与朋友分享食谱和菜单。
• 14 天免费试用，无需信用卡。

👉 通过我的推荐链接注册 — 你可以获得试用资格，我会收到一份小小的感谢。双赢。

✨ 它能为你做什么

• 🤖 开箱即用的 MCP 服务——将 Claude Desktop、Claude Code、OpenClaw 或任何兼容 MCP 的宿主连接到它，即可开始与食谱库对话。
• ⌨️ 使用同一套工具的命令行工具——每个 MCP 工具也都是 plan-to-eat 子命令，可为用户显示表格，也可通过 --json 供脚本使用。同一个注册表 为两种接口提供支持，因此两者不会出现偏差。
• 🔐 自动身份验证与自动恢复——只需设置一次凭据，服务便会处理登录，将 Cookie 会话缓存到磁盘，并在 Plan to Eat 使会话失效时静默重新验证。
• 🧰 36 个工具，涵盖所有重要操作——完整的食谱 CRUD、完整的膳食规划器 CRUD（添加 / 移动 / 复制 / 删除食谱、备注和 食材条目）、重新排列时段中的事件、将剩菜作为一等工作流处理、跟踪冷冻食品、浏览课程、菜系和标签，以及统计队列中的项目数量。
• 🗓️ 真正掌控规划器——查看一周的计划并预先关联食谱标题、按日期安排食谱、附加准备备注、通过一次工具调用重新安排、更改份数、复制、查找重复项，以及重新排列同一时段中的事件。
• 🛒 真正实用的购物清单——读取清单及每件商品所属的商店和货架，添加商品（Plan to Eat 会猜测货架，并沿用你上次选择的商店）、修改条目名称或数量、在商店之间移动商品、移除商品，以及将商品放回清单。
• ❄️ 冷冻食品跟踪——烹饪后，使用 freeze_recipe_portions 标记 N 份冷冻食品；使用 list_frozen_recipes 查看冷冻库存；食用后消耗相应条目（软删除，保留历史记录）。
• 🍳 真正的 CRUD——包括具有正确计量单位的食材清单、做法、准备 / 烹饪时间、营养信息、评分和标签。
• 📦 精简的运行时——无需 Playwright、无头浏览器或原生模块。 只需 fetch、MCP SDK 和 Zod。不到一秒即可启动。
• 🦺 100% TypeScript——提供完整类型定义的 Recipe、Ingredient、PlannerEvent 结构，以及通用的 _json<T>，让工具无需猜测返回结果。
• 📚 同时也是一个库——core/client.ts 是简洁、纯 Node 的 API 客户端， 可直接用于任何脚本。
• 🧠 内置 Claude Code 技能——.claude/skills/plan-to-eat/SKILL.md 向任何 Agent 讲解常见工作流和注意事项（如 supper 与 dinner 的别名、 description 与 title 不匹配等），无需它重新摸索。

根据线上 Web 应用逆向工程得出。Plan to Eat 没有公开 API， 但桌面网站内部使用的也是这些端点。使用风险自负——这些端点可能随时发生任何变化。

🚀 快速开始

npx -y plan-to-eat-mcp          # run the MCP server
npm i -g plan-to-eat-mcp        # …or install both bins on PATH

需要 Node 18+（用于内置的 fetch）以及一个 Plan to Eat 账户。

该软件包提供两个可执行文件：plan-to-eat-mcp（MCP 服务）和 plan-to-eat（命令行工具）。如需通过 npx 运行命令行工具而不安装，请注意 必须显式选择该工具，因为默认可执行文件是服务：

npx -y -p plan-to-eat-mcp plan-to-eat --help

git clone https://github.com/alex-zwingli/plan-to-eat-mcp.git
cd plan-to-eat-mcp
npm install
npm run build

配置

命令行工具也会读取工作目录中的 .env（Shell 变量优先）。MCP 服务不会读取——MCP 主机会显式传入环境变量，如下所示。

🤖 与 Agent 搭配使用

任何能够启动本地 stdio MCP 服务的主机都可以使用。该服务只需要一个命令和两个环境变量，无需其他配置——无需端口、OAuth 或守护进程。

Claude Code，简便方式：安装插件

此仓库以 Claude Code 插件的形式提供——一步即可安装 MCP 服务和两个技能：

export [email protected]
export PLAN_TO_EAT_PASSWORD=hunter2

git clone https://github.com/alex-zwingli/plan-to-eat-mcp.git
cd plan-to-eat-mcp && npm install && npm run build

claude plugin marketplace add "$(pwd)"
claude plugin install plan-to-eat@plan-to-eat

安装后将包含：

使用 claude plugin details plan-to-eat@plan-to-eat 和 claude mcp list 确认。服务会从启动 Claude Code 时的环境中读取 PLAN_TO_EAT_USERNAME / PLAN_TO_EAT_PASSWORD，因此请在 Shell 配置文件中导出这些变量，而不要将其提交到任何地方。

Claude Code，手动配置

claude mcp add plan-to-eat \
  --env [email protected] \
  --env PLAN_TO_EAT_PASSWORD=hunter2 \
  -- npx -y plan-to-eat-mcp

添加 --scope user，即可在所有项目中使用，而不仅限于当前项目。使用 claude mcp list 检查连接状态，或在会话中输入 /mcp。

Claude Desktop

编辑 claude_desktop_config.json——Settings → Developer → Edit Config，或者：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "plan-to-eat": {
      "command": "npx",
      "args": ["-y", "plan-to-eat-mcp"],
      "env": {
        "PLAN_TO_EAT_USERNAME": "[email protected]",
        "PLAN_TO_EAT_PASSWORD": "hunter2"
      }
    }
  }
}

重启 Claude Desktop，就可以开始烹饪了。

其他 MCP 主机

Cursor、Windsurf、Zed、Cline、Continue、OpenClaw、VS Code 的 MCP 支持以及自定义 SDK 客户端，都只需要相同的三项配置。请将它们指向：

大多数主机使用与上文 Claude Desktop 相同的 mcpServers JSON 配置块——通常位于 .cursor/mcp.json、.vscode/mcp.json，或主机的设置界面中。

如果你进行了全局安装（npm i -g plan-to-eat-mcp），请将 plan-to-eat-mcp 可执行文件用作命令，并完全省略参数。如果你从克隆的仓库构建，命令为 node，参数为 ["/absolute/path/to/plan-to-eat-mcp/dist/mcp/server.js"]。

绝对路径很重要，尤其是从克隆的仓库运行时。MCP 主机不会从你的项目目录启动服务，因此相对路径会解析失败。上述 npx 命令则完全避免了这个问题。

验证是否正常运行

[email protected] PLAN_TO_EAT_PASSWORD=hunter2 npx -y plan-to-eat-mcp

你应该会在 stderr 中看到 [plan-to-eat] mcp server ready on stdio (36 tools)。这表示服务正在等待客户端——按 Ctrl-C 退出。如果看到的是凭据错误，请先修复，再配置主机；否则出错时会更难发现。

教会你的 Agent 使用工作流

.claude/skills/ 中附带了两个技能，涵盖常见流程和容易出错的地方（supper 与 dinner 的别名、笔记条目中 description 与 title 不匹配，以及安排日程前检查重复项）：

• plan-to-eat — 供调用 MCP 工具的 Agent 使用。
• plan-to-eat-cli — 供有 shell 但没有 MCP 服务的 Agent 使用。具备相同的 30 项功能，通过子命令调用，并提供 --json 以便解析。

上文的插件安装会注册这两个技能。使用其他宿主的 Agent 可以将它们作为普通上下文读取——将文件提供给它们，或把其中一个粘贴到系统提示词中。

也可以通过 skills.sh CLI 将技能单独安装到 18 种以上的 Agent 中：

npx skills add alex-zwingli/plan-to-eat-mcp

这会将两个 SKILL.md 文件复制到 .agents/skills/，并为 Claude Code、Cursor、Codex、Copilot、Gemini CLI 等创建符号链接。添加 --skill plan-to-eat-cli 可只安装一个。请注意，这安装的是技能，而不是服务——每个技能的设置部分都会引导 Agent 构建 MCP 服务或 CLI（如果尚未构建）。

对于 OpenClaw Agent，这两个技能都已发布到 ClawHub：

clawhub install plan-to-eat        # MCP tools
clawhub install plan-to-eat-cli    # shell / CLI

它们的 frontmatter 会在 metadata.openclaw 中声明各自所需的凭据和二进制文件，因此 ClawHub 可以在安装时检查你的环境。

⌨️ 在终端中使用

每个 MCP 工具也都是一个子命令。下划线会转换为短横线；两种写法都有效。

npm i -g plan-to-eat-mcp
plan-to-eat --help

也可以不安装直接使用——注意 -p，因为软件包的默认可执行文件是 MCP 服务，而不是 CLI：

npx -y -p plan-to-eat-mcp plan-to-eat --help

$ plan-to-eat list-frozen-recipes
ID      RECIPE_ID  COUNT  SERVINGS  FROZEN_ON
──────  ─────────  ─────  ────────  ──────────
227854  44676380   6      1.0       2025-05-04
227908  17314561   3      1.0       2025-05-05

2 rows

$ plan-to-eat add-planner-note "Defrost chicken" 2026-05-05 dinner
id       67710999
date     2026-05-05
section  dinner

$ plan-to-eat get-counts --json | jq .frozen
10

• 位置参数或标志参数 — get-recipe 123 和 get-recipe --id 123 等效。<command> --help 会列出哪些参数可以按位置传入。
• --json 会输出原始数据，而不是表格，便于通过管道传给 jq。
• 数组可重复使用标志参数（--event_ids 11 --event_ids 22），也可传入 JSON（--event_ids '[11,22]'）。对象参数需使用 JSON： --ingredients '{"title":"bread","amount":"2"}'。
• 验证使用与 MCP 服务相同的 Zod schema，因此无效的枚举值或格式错误的日期在两种调用方式下都会以相同方式报错。

🧰 36 个工具

每个工具既是 MCP 工具，也是一个 CLI 子命令——add_planner_recipe 工具在 shell 中对应 plan-to-eat add-planner-recipe。完整参考文档包含输入架构和返回格式：docs/TOOLS.md。

食谱

计划表 — 读取

计划表 — 写入

冷冻柜

购物清单

清单项通过其 item_ids 数组定位，而不是单个 id——Plan to Eat 会将重复食材合并为一行，并保留其所有底层行 id。

查找表和其他功能

📚 将客户端用作库

import { PlanToEat, type Recipe } from 'plan-to-eat-mcp';

const pte = new PlanToEat();
await pte.login(process.env.PLAN_TO_EAT_USERNAME!, process.env.PLAN_TO_EAT_PASSWORD!);
// Or restore: pte.importSession(JSON.parse(fs.readFileSync('session.json', 'utf8')));

const recipes = await pte.listRecipes();                    // every active recipe
const [dumplings] = await pte.listRecipes({ search: 'pork chive' });
const detail: Recipe = await pte.getRecipe(dumplings.id);  // ingredients + directions

const created = await pte.createRecipe({
  title: 'Grilled cheese',
  servings: 1,
  directions: 'Butter bread. Cheese. Pan. Flip.',
  ingredients: [
    { title: 'bread',  amount: '2', unit: 'slice', position: 1 },
    { title: 'cheese', amount: '1', unit: 'slice', position: 2 },
  ],
  tag_titles: 'easy,lunch',
});

await pte.updateRecipe(created.id, { rating: 5 });
await pte.deleteRecipe(created.id);

客户端会在首次登录时在内部保存凭据，以便在缓存的 cookie 于会话期间过期时自动重新进行身份验证。

工具注册表也已导出，你可以基于相同的 36 项功能构建自己的适配器：

import { toolsByName, createSession } from 'plan-to-eat-mcp';

const { pte, ensure } = createSession();
await ensure();

const getRecipe = toolsByName.get('get_recipe')!;
console.log(getRecipe.description);          // same text the MCP host sees
const recipe = await getRecipe.run(pte, { id: 123 });

🧪 API 参考（可用部分）

所有路径均位于 https://app.plantoeat.com 下。

JSON 端点（/api/v1/*）

规划写入端点（/planner/*）

风格不同：请求体采用表单编码，响应为 text/javascript（空内容）。服务器会修改状态，UI 会单独重新获取数据。必需请求头：X-CSRF-Token、X-Requested-With: XMLHttpRequest、Accept: text/javascript。由于响应体为空，客户端通过比较 /api/v1/events 前后的差异来获取新事件 ID。

section 的取值为 breakfast、lunch、dinner、snacks。请注意，服务器可能会根据用户的账户偏好，将 dinner 规范化为 supper；读取时会返回规范名称。

身份验证

基于 Cookie。客户端支持两种流程：

1. 登录。 使用 login[email] 和 login[password] 向 POST /login 发送请求，并附上从 GET /login 页面 meta 标签中获取的 authenticity_token。服务器返回 302 并设置 Cookie。
2. 复用 Cookie。 “记住我”对应的 ptermid2（用户 ID）和 ptermxt2（长期有效的令牌）单独就足够使用——保存这两个值，在它们失效前无需重新登录。

写入请求需要 X-CSRF-Token 标头。客户端会按需从 /recipes 页面上的 <meta name="csrf-token"> 标签中获取该值。

不支持对 /api/v1/... 使用 HTTP Basic 身份验证（会返回 401）。

食谱负载结构

单个食谱的响应包含 65 个字段。POST/PUT 请求中可写入的字段包括： title、description、source、url、servings、yield、scaling、 prep_time、cook_time、total_time（分钟）、 course_id、cuisine_id、main_ingredient_id、tag_titles（逗号分隔的列表）、 directions（自由文本）、private、draft、rating、 营养信息字符串（calories、sodium 等）以及食材。

食材使用 Rails 嵌套属性——实际传输字段为 recipe_ingredients_attributes，而不是 ingredients。客户端以及 create_recipe / update_recipe 工具接受更易用的名称 ingredients，并会进行转换。每个条目如下：

{ "title": "water", "amount": "1", "unit": "cup", "note": "", "position": 1 }

更新时如需删除已有食材，请包含其 id 和 "_destroy": true。服务器会补全 amount_float、metric_amount、 metric_unit 和 similar_titles。

📁 目录结构

一个软件包，三层结构。逻辑位于 core/；MCP 服务和 CLI 是基于同一注册表构建的轻量适配器。

src/
  core/
    client.ts     API client — no MCP, no CLI, no I/O beyond fetch
    tools.ts      the tool registry: name, description, Zod shape, handler
    session.ts    credentials + cookie-cache bootstrap, shared by both adapters
    version.ts    version read from package.json at runtime
  mcp/server.ts   registry -> MCP tools (stdio transport)
  cli/
    main.ts       registry -> subcommands, help, dispatch
    args.ts       argv -> Zod-validated arguments
    render.ts     results -> tables (or raw JSON under --json)
  scripts/        smoke tests and the docs coverage check
  tests/          offline unit tests (fetch is stubbed)
  index.ts        public entrypoint for library consumers
  server.ts       back-compat shim, see below

添加工具只需在 src/core/tools.ts 中添加一条记录。 它会同时出现在 MCP 服务和 CLI 中，并使用相同的名称、架构和描述——二者不会出现偏差。

其他值得了解的文件：

• docs/TOOLS.md — 各工具的参考文档，包含输入/输出结构和注意事项。 手动编写；如果文档与注册表中工具列表不一致，npm run check:docs 会失败。
• .claude/skills/plan-to-eat/SKILL.md — 如何有效使用 MCP 工具。
• .claude/skills/plan-to-eat-cli/SKILL.md — CLI 的使用方法。
• .claude-plugin/ — Claude Code 插件和市场清单。
• .mcp.json — 插件的 MCP 服务声明。
• dist/ — 由 npm run build 生成。

从 ≤0.4 版本升级？ 服务入口从 dist/server.js 移至 dist/mcp/server.js。旧路径仍可使用——它是一个会加载新入口的垫片——因此现有主机配置和部署仍可运行。新配置应使用新路径或 plan-to-eat-mcp 可执行文件。

逆向工程期间使用了 Playwright；为未来可能开展的 API 探索工作，仍将其作为开发依赖保留。运行时仅依赖 fetch、MCP SDK 和 Zod。

脚本

verify* 和 test 脚本会访问你的真实账户（test:unit 不会）。它们会创建并删除各自的测试数据，但并非试运行——详情请参阅 CONTRIBUTING.md。

🤝 贡献

欢迎提交错误报告、新端点和上游破坏性变更的修复——请参阅 CONTRIBUTING.md。先说明一点：测试脚本会使用一个真实的 Plan to Eat 账户，并创建真实数据 （之后会清理这些数据）。请使用你自己的账户。

🙏 支持 Plan to Eat

这个项目的存在完全是因为 Plan to Eat 很棒。如果你觉得这个项目有用，最好的支持方式是 通过我的推荐链接试用 Plan to Eat。 免费试用 14 天，无需银行卡。

许可证

MIT——请参阅 LICENSE。你想怎么用都行；只是如果 Plan to Eat 发布了破坏性变更，别怪我。