MCP server

Cook MCP (cook-mcp) is a local MCP server that gives AI agent tools — Claude Code, Claude Desktop, Cursor, and any other MCP client — access to your Cooklang recipe collection, plus nutrition evaluation and report rendering. Recipes stay as plain .cook and .menu files in a folder you own. It talks stdio, so it runs as a subprocess of the client rather than as a network service, and the nutrition tools call the same HTTP API documented on this site.

Add it to your client

Claude Code:

claude mcp add cook -- npx -y @cookmd/mcp

Any client that takes an mcpServers config:

{
  "mcpServers": {
    "cook": {
      "command": "npx",
      "args": ["-y", "@cookmd/mcp"],
      "env": { "COOK_RECIPES_DIR": "/path/to/recipes" }
    }
  }
}

Set COOK_RECIPES_DIR to your recipe folder; the recipe tools need it. If it is not set, the client's working directory is the recipe root. Every path the tools take, including the render_report recipe and template paths, is relative to that folder.

The server is published on npm as @cookmd/mcp; the source is at cook-md/cook-mcp. The old @cookmd/nutrition-mcp package still works: it now runs @cookmd/mcp. To switch, change the package name in your config.

First-use auth

The recipe, pantry and shopping-list tools run locally with no account. The nutrition tools need a cook.md login with Cook Basic or Pro. Ask the agent to run the login tool — it walks through a cook.md device login (shows a code

URL to approve in the browser, then authenticates in the background). Alternatively, set NUTRITION_API_TOKEN to an org API key to skip login entirely. auth_status reports the current login, plan and import allowance at any time.

Tools

Local (no login)

Tool	What it does
`list_recipes`	List recipes, meal plans or report templates.
`read_recipe`	Read a recipe or menu: source plus parsed ingredients, cookware, steps and metadata; optional scaling.
`search_recipes`	Search names and contents, optionally filtered by tag.
`validate`	Check a file, a folder, the whole collection, or unsaved content for errors and broken references.
`write_recipe`	Save a `.cook` recipe (validated first).
`write_menu`	Save a `.menu` meal plan (validated first).
`write_config`	Save `config/aisle.conf`, `config/pantry.conf`, or a `.jinja` report template.
`shopping_list`	Build a shopping list from recipes and/or menus: merges duplicates, groups by aisle, subtracts the pantry.
`pantry_list`	Show the pantry, by section.
`pantry_expiring`	Items expiring soon.
`pantry_depleted`	Items at or below their low-stock threshold.
`pantry_recipes`	Which recipes you can cook with what is in the pantry.
`pantry_update`	Add, update or remove pantry items.
`render_report`	The iterate-on-templates loop: renders a jinja report against a `.cook` recipe or `.menu` plan and returns `{rendered, checks, resolve_failures}` so an agent can fix the template or recipe and re-render until clean. Plain templates need no login; nutrition functions inside them need Cook Basic or Pro.

Cook Basic / Pro (cook.md login)

Tool	What it does
`login`	cook.md device login.
`auth_status`	Report login, plan and import allowance.
`get_nutrition`	Nutrition facts for one ingredient amount.
`aggregate_nutrition`	Sum nutrition across many ingredient lines (a whole recipe).
`lookup_ingredient`	Fuzzy-search the ingredient catalog.
`convert_units`	Convert an amount between units (volume to mass needs a density).
`check_category`	Check whether an ingredient belongs to a category slug.
`branded_lookup`	Look up a branded/packaged product by UPC or text search.
`reference_intakes`	Daily reference-intake tables (RDA/DV) for a standard.
`import_recipe`	Convert a web page, photos or pasted text to Cooklang. Returns text; the agent validates it and calls `write_recipe`.

Workflow prompts

The server also ships workflow prompts that MCP clients surface as slash commands:

meal-planning — build or evaluate a .menu meal plan.
shopping-list — build a shopping list from recipes or a plan.
pantry — track and use the pantry.
import-recipe — import a recipe from a page, photos or text.
edit-recipe — edit an existing recipe safely.
nutrition-report — write a nutrition report template for a recipe or plan and iterate with render_report until every check passes.
nutrition-goals — adjust a recipe or plan until it hits numeric nutrition targets.

Environment variables

Env var	Effect
`COOK_RECIPES_DIR`	Recipe root. Every path is relative to it. Default: the client's working directory.
`NUTRITION_API_URL`	Nutrition service base URL. Default `https://nutrition.cook.md`.
`COOKMD_BASE_URL`	cook.md base URL for device login. Default `https://cook.md`.
`NUTRITION_API_TOKEN`	Optional org API key/token override — bypasses `login` when set.

Next steps

render_report embeds the open-source cook-md/cooklang-reports-nutrition extension — the template functions available inside reports are documented in the report extension guides, starting with the function reference.
API reference — the underlying HTTP endpoints the tools call.