Cook (Cooklang recipes)

io.github.cook-mdv0.2.3Updated Oct 6, 2026

Cooklang recipes for AI agents: validate, meal plans, shopping lists, pantry, nutrition

VerifiedSTDIODesktop onlyData & AnalyticsLocation & LifestyleProductivity & Workflow

Overview

AI-generated overview

Lets an AI assistant read, search, validate and write Cooklang recipes and meal plans, build shopping lists, track a pantry and render reports from a local file

What it does
Gives an agent access to a folder of plain Cooklang .cook and .menu files. Free local tools list, read, search, validate and write recipes and menus, build shopping lists grouped by aisle and net of the pantry, track pantry stock and expiry, and render Jinja report templates (R38-R51). With a cook.md login it adds nutrition facts, unit conversion, ingredient and branded-product lookup, reference intakes, and recipe import from web pages, photos or social links (R52-R63). It also exposes Cooklang spec, syntax, menu-format and per-skill guide resources plus prompts (R69-R74).
When to use it
Worth adding if you keep recipes as Cooklang files and want an assistant to plan meals, generate shopping lists, check a collection for errors, or answer what you can cook from your pantry. It also suits users who want nutrition estimates or recipe import from photos and links, which require a cook.md account. Skip it if you do not use Cooklang or need Windows support. (R4, R5, R10, R11)
Requirements
Runs locally over stdio, typically via npx @cookmd/mcp; Node.js is needed for that package. macOS (arm64, x64) and Linux (x64, arm64, glibc 2.35+) are supported; there are no Windows builds (R10, R11, R89). No account is needed for local recipe, pantry, shopping-list and report tools. Nutrition and photo or social-link import need a cook.md login (Cook Basic or Pro). Optional variables: COOK_RECIPES_DIR, COOKMD_BASE_URL, NUTRITION_API_URL, NUTRITION_API_TOKEN, COOK_MCP_AUTH_PATH (R93-R100).
Before you install
Writes are confined to the recipe root and paths outside it are refused, every write is validated first, and there is no delete tool (R75-R81). A cook.md login stores a token, by default under the auth path, and the NUTRITION_API_TOKEN variable takes priority over it (R98-R100). Photo and social-link imports consume a cook.md import allowance (R65). Pantry subtraction only works when units match (R83-R85), and symlinks pointing outside the recipe folder may still be followed in some cases (R86-R

Installation

In SourceWeft

  1. Open Cook (Cooklang recipes) in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

cook-mcp

An MCP server that gives your AI agent (Claude Code, Claude Desktop, Cursor, ChatGPT, or any other MCP client) access to your Cooklang recipe collection. Recipes stay as plain .cook and .menu files in a folder you own. The agent can read, search, validate and write them, build shopping lists, track a pantry and render reports, all locally and without an account. With a cook.md login it can also compute nutrition and import recipes from photos and social links.

Install

Claude Code:

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

Any client that takes an mcpServers config:

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

If COOK_RECIPES_DIR is not set, the server uses the workspace folder your client shares, or the folder the client was started in. See How the recipe folder is chosen.

Supported platforms: macOS (arm64, x64) and Linux (x64, arm64, glibc 2.35 or newer). There are no Windows builds yet.

Setup notes for specific clients: https://cook.md/help/mcp

Claude Code plugin

Claude Code users can install the cooklang plugin instead of adding the server by hand. It lives in cooklang/cooklang-skills and bundles this server plus the skills below:

/plugin marketplace add cooklang/cooklang-skills/plugin install cooklang@cooklang-skills

The plugin starts the server with your Claude Code project folder as the recipe root, and Claude Code picks the right skill from what you ask ("plan dinners for next week", "is this recipe valid?"). If you already added the server with claude mcp add cook, remove that entry so you don't run two copies.

The skills (also served by this server as cooklang://skills/<name> resources):

SkillUse it for
cooklang-editingWrite a new recipe or edit and fix a .cook file
cooklang-validationCheck recipes, a folder or the whole collection for errors and broken references
metadataAdd or fix YAML frontmatter (title, tags, servings, times), including bulk changes
recipe-importImport a recipe from a URL, photos or pasted text
recipe-searchFind recipes by ingredient, tag, cuisine, course or a remembered phrase
scale-recipeShow a recipe for more or fewer servings
export-recipeTurn a recipe into Markdown, JSON, plain text or HTML
organize-collectionFolder layout, metadata audit, aisle and pantry config, whole-library checks
meal-planningBuild or edit a .menu meal plan
shopping-listShopping lists from recipes or plans, grouped by aisle, minus the pantry
pantryTrack stock, expiry and low items; what can I cook with what I have
report-authoringCustom Jinja reports and printouts with render_report
nutrition-reportsNutrition evaluation and screening (Cook Basic or Pro)
nutrition-goalsChange a recipe or plan to hit nutrition targets (Cook Basic or Pro)

skills/ in this repo is the canonical copy; the plugin repo syncs from it. Each skill is skills/<name>/SKILL.md.

Tools

Free (local, no login)

ToolWhat it does
list_recipesList recipes, meal plans or report templates (kind: recipe, menu, template, all)
read_recipeRead a recipe or menu: source plus parsed ingredients, cookware, steps and metadata; optional scaling
search_recipesSearch names and contents, optionally filtered by tag
validateCheck a file, a folder, the whole collection, or unsaved content for errors and broken references
write_recipeSave a .cook recipe (validated first)
write_menuSave a .menu meal plan (validated first)
write_configSave config/aisle.conf, config/pantry.conf, or a .jinja report template under reports/ or config/reports/
shopping_listBuild a shopping list from recipes and/or menus: merges duplicates, groups by aisle, subtracts the pantry
pantry_listShow the pantry, by section
pantry_expiringItems expiring soon
pantry_depletedItems at or below their low-stock threshold
pantry_recipesWhich recipes you can cook with what is in the pantry
pantry_updateAdd, update or remove pantry items
render_reportRender a jinja report template against a recipe or menu (plain templates need no login)

Cook Basic / Pro (cook.md login)

ToolWhat it does
loginStart a cook.md device login; shows a code and a URL
auth_statusShow login status, plan and import allowance
get_nutritionNutrition facts for one ingredient amount
aggregate_nutritionSum nutrition across many ingredient lines
lookup_ingredientFuzzy-search the ingredient catalog
convert_unitsConvert between units (volume to mass needs a density)
check_categoryCheck whether an ingredient belongs to a category
branded_lookupLook up a packaged product by barcode or text
reference_intakesDaily reference-intake tables (RDA/DV)
import_recipeConvert a web page, photos or pasted text to Cooklang

import_recipe from a web page or pasted text works without a login. Photos and social-media links need a cook.md account and use your import allowance. It returns Cooklang text and does not save it; the agent validates it and calls write_recipe. Nutrition functions inside render_report also need Cook Basic or Pro.

Prompts and resources

Prompts: meal-planning, shopping-list, pantry, import-recipe, edit-recipe, nutrition-report, nutrition-goals, scale-recipe.

Resources:

  • cooklang://spec: the Cooklang specification
  • cooklang://syntax: a syntax reference
  • cooklang://menu-format: the .menu meal plan format
  • cooklang://skills/<name>: working guides for the agent, one per skill in the table above: cooklang-editing, cooklang-validation, export-recipe, meal-planning, metadata, nutrition-goals, nutrition-reports, organize-collection, pantry, recipe-import, recipe-search, report-authoring, scale-recipe, shopping-list

Safety

  • Writes stay inside the recipe root. Paths outside it are refused.
  • Every write is validated first; invalid Cooklang is not saved.
  • The deprecated >> metadata syntax is refused. Use YAML frontmatter.
  • There is no delete tool. The agent cannot remove your files.

Known limitations

  • Pantry subtraction in shopping lists only works when units match. For example, 1 kg in the pantry does not cancel 200 g in a recipe. This is a limitation of cookcli-core.
  • Symlinks inside the recipe folder are mostly not followed for reads and listing. A symlink requested by bare name without an extension, or reached through a recipe's @./ reference, may still be followed. This only matters if you put symlinks pointing outside the folder into your recipes.
  • No Windows builds yet.
  • No delete tool.

Environment variables

VarDefaultMeaning
COOK_RECIPES_DIRthe client's roots, then its working directoryRecipe root. Every path is relative to it. Always wins when set.
COOKMD_BASE_URLhttps://cook.mdLogin, entitlements, import
NUTRITION_API_URLhttps://nutrition.cook.mdNutrition service
NUTRITION_API_TOKENnoneOrg key or pre-made token. Takes priority over the stored login.
COOK_MCP_AUTH_PATH~/.config/cook-mcp/auth.jsonToken store. The old NUTRITION_MCP_AUTH_PATH still works as an alias.

How the recipe folder is chosen

  1. COOK_RECIPES_DIR, if set. Nothing else is consulted.
  2. The client's MCP roots. If the client supports roots (it shares its open workspace folders with the server), the first file:// root that is an existing folder becomes the recipe root. The server asks on the first recipe tool call and again whenever the client reports that its roots changed. If the client doesn't answer within 5 seconds, the server uses the working directory and asks again later (at most once every 30 seconds).
  3. The folder the client started the server in.

A root is a folder you opened on purpose, so it is used unless it is /, your home folder or inside an agent plugin install folder (for example ~/.codex/plugins/cache/..., ~/.gemini/extensions/... or the folder CLAUDE_PLUGIN_ROOT points to). The working directory is checked more strictly: it is also refused when it, or a folder up to four levels above it, has .claude-plugin/plugin.json, an Agent Plugins plugin.json or gemini-extension.json, because a plugin that starts the server in its own install folder would otherwise expose the wrong files and write recipes into a folder that is wiped on update. When nothing usable is found, recipe tools say that no recipe folder is set, why, and that COOK_RECIPES_DIR fixes it; auth_status shows recipe_root_source: "unset". Otherwise recipe_root_source is env, roots or cwd.

What each client does:

  • Claude Code sends its project folder as a root (verified), so nothing to configure.

  • Codex sends no roots (verified with 0.160.1) and may start the server in a plugin folder, so set COOK_RECIPES_DIR:

    sh
    codex mcp add cook --env COOK_RECIPES_DIR=/path/to/recipes -- npx -y @cookmd/mcp

  • VS Code and Cursor document support for roots (not verified here). If recipe tools say no folder is set, set COOK_RECIPES_DIR in the server's config.

Things to ask

  • "Plan dinners for next week from my recipes and make the shopping list."
  • "What can I cook with what's in my pantry?"
  • "Check my whole collection for broken references."
  • "Import https://example.com/some-recipe as a recipe."
  • "How much protein is in this week's plan?" (needs Cook Basic or Pro)

Building from source

sh
cargo build --releasecargo test

The binary is target/release/cook-mcp. It speaks MCP over stdio. cook-mcp login and cook-mcp logout manage the cook.md login from a terminal.

Migrating from nutrition-mcp

@cookmd/nutrition-mcp keeps working: it is now a thin shim that runs @cookmd/mcp. To switch, change the package name in your MCP config to @cookmd/mcp. Your login carries over.

Two things changed. Recipe tools need COOK_RECIPES_DIR (old configs did not set it), or start the client in your recipe folder; without either, recipe tools tell the agent that no recipe folder is set. And render_report paths are now relative to the recipe folder.

License

MIT

Source: README.md at commit 19d4f47

Tools

0
Tool metadata has not been indexed yet.

Version history

1
  1. v0.2.3LatestOct 6, 2026