plan-to-eat-mcp

# 🍽️ plan-to-eat-mcp

> **Stop typing recipes. Start telling them.**
> Hand your favorite LLM the keys to your Plan to Eat recipe book, planner,
> and shopping list — over the Model Context Protocol.

A drop-in MCP server, a CLI, and a standalone Node client that give Claude,
ChatGPT, any MCP-aware assistant, or your own shell full read/write access to
your [Plan to Eat](https://www.plantoeat.com/ref/d7d2327524) account.

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

…or, when you'd rather not talk to anything:

```console
$ 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
```

That's it. No recipe re-typing. No copy-pasting URLs into a phone app. Just
talk.

---

## ❤️ Why Plan to Eat?

If you're not already using it, [Plan to Eat](https://www.plantoeat.com/ref/d7d2327524)
is genuinely the best meal-planning app I've ever used:

- **A clip-anywhere recipe importer** that actually works on real-world food blogs.
- **Drag-and-drop weekly planner** that automatically rolls ingredients into a
  shopping list, with smart units and pantry deduplication.
- **Yours forever** — your recipe book is portable, exportable, and not held
  hostage by an algorithm.
- **Family-friendly** — share recipes and menus with friends in-app.
- **14-day free trial, no credit card needed.**

👉 **[Sign up with my referral link](https://www.plantoeat.com/ref/d7d2327524)** —
you get the trial, and I get a tiny thank-you. Win/win.

---

## ✨ What this gives you

- 🤖 **MCP server out of the box** — point Claude Desktop, Claude Code, OpenClaw,
  or any MCP-compatible host at it and start talking to your recipe book.
- ⌨️ **A CLI over the same tools** — every MCP tool is also a `plan-to-eat`
  subcommand, with tables for humans and `--json` for scripts. One registry
  feeds both surfaces, so they can't drift.
- 🔐 **Auto-auth & auto-recovery** — set your credentials once, the server
  handles login, caches the cookie session to disk, and silently re-auths
  whenever Plan to Eat invalidates it.
- 🧰 **36 tools, all the verbs that matter** — full recipe CRUD, full
  meal-planner CRUD (add / move / duplicate / delete recipes, notes, and
  ingredient entries), reorder events in a slot, leftovers as a first-class
  workflow, freezer tracking, browse courses & cuisines & tags, count what's
  in your queue.
- 🗓️ **Real planner control** — view a week's plan with recipe titles
  pre-joined, schedule recipes on dates, attach prep notes, reschedule with
  one tool call, change servings, duplicate, search for duplicates, reorder
  same-slot events.
- 🛒 **A shopping list you can actually work with** — read it with the store
  and aisle each item is filed under, add items (Plan to Eat guesses the aisle
  and reuses the store you last picked), retitle or re-quantify a line, move
  items between stores, remove them, put them back.
- ❄️ **Freezer tracking** — after cooking, mark N portions as frozen with
  `freeze_recipe_portions`; check what's stashed with `list_frozen_recipes`;
  consume entries when you eat them (soft-delete, history preserved).
- 🍳 **Real CRUD** — including ingredient lists with proper units, directions,
  prep/cook times, nutrition, ratings, and tags.
- 📦 **Tiny runtime** — no Playwright, no headless browser, no native modules.
  Just `fetch`, the MCP SDK, and Zod. Boots in under a second.
- 🦺 **100% TypeScript** — fully typed `Recipe`, `Ingredient`, `PlannerEvent`
  shapes plus a generic `_json<T>` so your tools never have to guess what
  comes back.
- 📚 **A library too** — `core/client.ts` is a clean, plain-Node API client you
  can drop into any script.
- 🧠 **Bundled Claude Code skill** — `.claude/skills/plan-to-eat/SKILL.md`
  teaches any agent the common workflows and gotchas (the supper-vs-dinner
  alias, the `description`-vs-`title` mismatch, etc.) so it doesn't have to
  rediscover them.

> Reverse-engineered from the live web app. There's no public Plan to Eat API,
> but the desktop site uses these same endpoints internally. Use at your own
> risk — they could change anything at any time.

---

## 🚀 Quick start

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

Requires Node 18+ (for built-in `fetch`) and a
[Plan to Eat](https://www.plantoeat.com/ref/d7d2327524) account.

The package ships two bins: `plan-to-eat-mcp` (the MCP server) and
`plan-to-eat` (the CLI). To run the CLI through `npx` without installing, note
that you have to select it explicitly, since the default bin is the server:

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

<details>
<summary>Building from a clone instead (for development, or the Claude Code plugin)</summary>

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

The build emits CommonJS to `dist/`.
</details>

### Configuration

| Var | Required | Default | Description |
|---|---|---|---|
| `PLAN_TO_EAT_USERNAME` | yes | — | Plan to Eat login email |
| `PLAN_TO_EAT_PASSWORD` | yes | — | Plan to Eat password |
| `PLAN_TO_EAT_SESSION_FILE` | no | `~/.plan-to-eat-session.json` | Where the cookie session is cached. Set to `""` to disable caching. |

The CLI also reads a `.env` in the working directory (shell variables win). The
MCP server does not — MCP hosts pass env explicitly, as shown below.

---

## 🤖 Use it with an agent

Any host that can launch a **local stdio MCP server** works. The server needs
one command, two env vars, and nothing else — no ports, no OAuth, no daemon.

### Claude Code, the easy way: install the plugin

The repo ships as a Claude Code plugin — MCP server *and* both skills in one
step:

```bash
export PLAN_TO_EAT_USERNAME=you@example.com
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
```

That gives you:

| Component | What it is |
|---|---|
| MCP server `plan-to-eat` | all 36 tools |
| Skill `plan-to-eat` | how to *use* the MCP tools well — workflows and gotchas |
| Skill `plan-to-eat-cli` | the same, for agents driving the CLI instead |

Confirm with `claude plugin details plan-to-eat@plan-to-eat` and `claude mcp list`.
The server reads `PLAN_TO_EAT_USERNAME` / `PLAN_TO_EAT_PASSWORD` from the
environment Claude Code was launched with, so export them in your shell profile
rather than committing them anywhere.

### Claude Code, manually

```bash
claude mcp add plan-to-eat \
  --env PLAN_TO_EAT_USERNAME=you@example.com \
  --env PLAN_TO_EAT_PASSWORD=hunter2 \
  -- npx -y plan-to-eat-mcp
```

Add `--scope user` to make it available in every project instead of just this
one. Check it connected with `claude mcp list`, or `/mcp` inside a session.

### Claude Desktop

Edit `claude_desktop_config.json` — **Settings → Developer → Edit Config**, or:

- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`

```jsonc
{
  "mcpServers": {
    "plan-to-eat": {
      "command": "npx",
      "args": ["-y", "plan-to-eat-mcp"],
      "env": {
        "PLAN_TO_EAT_USERNAME": "you@example.com",
        "PLAN_TO_EAT_PASSWORD": "hunter2"
      }
    }
  }
}
```

Restart Claude Desktop, and you're cooking.

### Any other MCP host

Cursor, Windsurf, Zed, Cline, Continue, OpenClaw, VS Code's MCP support, and
custom SDK clients all take the same three things. Point them at:

| Field | Value |
|---|---|
| Transport | stdio |
| Command | `npx` |
| Args | `["-y", "plan-to-eat-mcp"]` |
| Env | `PLAN_TO_EAT_USERNAME`, `PLAN_TO_EAT_PASSWORD` |

Most of them use the same `mcpServers` JSON block as Claude Desktop above —
often in `.cursor/mcp.json`, `.vscode/mcp.json`, or the host's settings UI.

If you installed globally (`npm i -g plan-to-eat-mcp`), use the
`plan-to-eat-mcp` bin as the command and drop the args entirely. If you built
from a clone, the command is `node` with
`["/absolute/path/to/plan-to-eat-mcp/dist/mcp/server.js"]`.

> **Absolute paths matter** for the clone route. MCP hosts don't launch servers
> from your project directory, so a relative path will fail to resolve. The
> `npx` command above sidesteps this entirely.

### Verify it works

```bash
PLAN_TO_EAT_USERNAME=you@example.com PLAN_TO_EAT_PASSWORD=hunter2 npx -y plan-to-eat-mcp
```

You should see `[plan-to-eat] mcp server ready on stdio (36 tools)` on stderr.
That's the server waiting for a client — Ctrl-C out. If instead you get a
credentials error, fix that before wiring up a host, where the failure is
harder to see.

### Teach your agent the workflows

Two skills ship in `.claude/skills/`, covering the common flows and the sharp
edges (the supper-vs-dinner alias, the `description`-vs-`title` mismatch on
note entries, checking for duplicates before scheduling):

- **`plan-to-eat`** — for agents calling the MCP tools.
- **`plan-to-eat-cli`** — for agents that have a shell but no MCP server. Same
  30 capabilities, driven throu