Skip to main content
Glama
recipe-mcp

recipe-mcp

by mnavas

recipe-mcp

A local MCP server for the kitchen. It gives any MCP client (Claude Desktop, Claude Code, etc.) tools to:

  • Convert units — weight (mg/g/kg/oz/lb/stone) and volume (ml/l/cup/tbsp/tsp/fl oz, US + metric + imperial).

  • Convert weight ↔ volume per ingredient — using a bulk-density table, so "how many grams is 1 tbsp of table salt?" or "how much volume is 1 g of salt?" are answerable when your scale isn't precise to the gram.

  • Scale recipes — by a factor or by changing the yield (e.g. 8 → 12 servings).

  • Percentages & ratios — ingredient-as-%-of-total, baker's percentages (flour = 100%), and solving ratios like 3:2:1.

  • Ask a local cooking assistant — backed by Ollama running on your machine (default model gemma3n:latest).

Everything runs locally. The assistant never leaves your computer.

Install

cd recipe-mcp
python3 -m venv .venv && . .venv/bin/activate
pip install -e .          # or: pip install -r requirements.txt

Make sure Ollama is running and has a model:

ollama serve &            # usually already running as a service
ollama pull gemma3n       # or any model you like

Related MCP server: mcp-mealie

How to use it

recipe-mcp is a backend for an AI assistant, not an app you run by hand. python -m recipe_mcp starts the server and then just waits silently — that's correct: it speaks the MCP protocol over stdin/stdout and does nothing until an MCP client (Claude Desktop, Claude Code, …) connects and calls its tools. You then talk to that client in plain language and it calls the tools for you.

There are three ways to use it, from quickest to most integrated.

1. Straight from the terminal (no client needed)

A small CLI exposes the same conversions directly — handy for a quick check:

recipe-mcp-cli convert 2 cup ml            # 2.0 cup = 473.2 ml
recipe-mcp-cli convert 1 lb g              # 1.0 lb = 453.6 g
recipe-mcp-cli vtow "table salt" 1 tbsp g  # 1 tbsp salt = 18.04 g
recipe-mcp-cli wtov "all-purpose flour" 125 g cup
recipe-mcp-cli ingredients                 # list the density table
recipe-mcp-cli ask "why weigh flour instead of cups?"   # needs Ollama

(Equivalent to python -m recipe_mcp.cli … if the script isn't on your PATH.)

2. Claude Code

Register the server once, then just ask in chat:

claude mcp add recipe -- /ABSOLUTE/PATH/recipe-mcp/.venv/bin/python -m recipe_mcp

Then: "Using the recipe tools, convert 2 cups of flour to grams" or "Give me the baker's percentages for 1000 g flour, 700 g water, 20 g salt." Check it's connected with claude mcp list.

3. Claude Desktop

Edit the config file (Settings → Developer → Edit Config, or the path below) and add the server. Use the absolute path to the venv's Python:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

  • Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "recipe": {
      "command": "/ABSOLUTE/PATH/recipe-mcp/.venv/bin/python",
      "args": ["-m", "recipe_mcp"],
      "env": { "RECIPE_MCP_MODEL": "gemma3n:latest" }
    }
  }
}

Restart Claude Desktop; the recipe tools appear in the 🔌 tools menu.

Inspect the tools in a browser (optional)

To click through every tool manually, run the official MCP Inspector against the server (needs Node/npx; no uv required):

npx @modelcontextprotocol/inspector .venv/bin/python -m recipe_mcp

The bundled mcp install / mcp dev helpers are not used here because they require uv; the commands above work with a plain venv.

Example prompts (once connected)

  • "How many grams is 1 tablespoon of table salt?"

  • "Scale this recipe from 8 to 12 servings: 300 g flour, 150 g sugar, 2 eggs."

  • "Turn this into baker's percentages." / "Apply these percentages to 500 g flour."

  • "What's a 3:2:1 shortbread ratio for 600 g total?"

Tools

Tool

What it does

convert_weight / convert_volume

Unit conversion within a dimension

list_units

All supported unit names

list_ingredients / ingredient_density

Browse the density table (g/ml)

weight_to_volume / volume_to_weight

Per-ingredient weight ↔ volume

scale_recipe

Rescale by factor or from_yield/to_yield

recipe_to_percentages

Each ingredient as % of total weight

bakers_percentages

Flour = 100%, others relative to flour

apply_bakers_percentages

Turn a formula into weights for a flour weight

solve_ratio

Scale a ratio (e.g. 3:2:1) to real amounts

cooking_assistant

Ask the local Ollama assistant

assistant_models / assistant_health

List models / check Ollama

get_config / set_config

View or change model, host, temperature, prompt

An ingredient line used by the scaling tools is {"name", "amount", "unit"}.

Configuration

Settings resolve in this order (first wins): env vars → config.json → defaults. Copy config.example.json to config.json to persist, or use env vars:

Field

Env var

Default

model

RECIPE_MCP_MODEL

gemma3n:latest

ollama_host

RECIPE_MCP_OLLAMA_HOST

http://localhost:11434

temperature

RECIPE_MCP_TEMPERATURE

0.4

system_prompt

RECIPE_MCP_SYSTEM_PROMPT

cooking-assistant persona

densities_override

RECIPE_MCP_DENSITIES

(none)

set_config(..., persist=True) writes config.json for you.

Ingredient densities

Densities in data/densities.json are bulk (scooped) densities in g/ml, tuned to common cooking charts — not laboratory material density. Granular ingredients vary with packing, so treat them as close approximations. Extend or override them with your own JSON file via densities_override (accepts {"ingredients": {...}} or a flat {name: density} map).

Documentation

Tests

pip install pytest
python -m pytest -q

Layout

recipe_mcp/
  server.py       MCP server — wires tools to the modules
  units.py        weight & volume conversion
  ingredients.py  density table + weight/volume conversion
  scaling.py      scaling, percentages, baker's %, ratios
  assistant.py    Ollama cooking assistant
  config.py       settings (env / config.json / defaults)
data/densities.json
docs/             landing page + EXAMPLES.md + CONFIGURATION.md
tests/

License

MIT — see LICENSE.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    • Baking unit conversion (cups/grams/temp/recipe scaling). convert_amount, convert_temperature

      https://api.bakingtab.com/mcp
    • Recipe search, ingredient matching, nutrition filters and a private cookbook for any AI agent.

      https://mcp.ask.recipes/mcp
    • Your Recipes, Beautifully Kept. weReci MCP server lets Claude and other MCP clients work with your personal weReci cookbook, the recipes you've imported from the web, social video and scanned family books. Interactive UI in the chat. weReci supports MCP Apps, so in clients that support it, tools return live views instead of plain text: recipe cards, shopping lists and your recipe graph. Clients without MCP Apps support get the same results as text. Find and read recipes: search your collection in plain language, open any recipe in full, or get an overview of what's in your cookbook. Cook with them: scale a recipe to any serving count, with cooking adjustments as well as amounts. Get substitution suggestions with ratios and caveats. Explore connections: browse your recipe graph (shared ingredients, techniques and cuisines), trace the connection between two recipes, and look up where a dish sits on the cuisine map. Themed collections: list the themed groups weReci curates from your cookbook, or ask it to reshuffle them. Shop: build a shopping list from one or more recipes, add or update items, and read the list back. Share: email a recipe to someone. Longer jobs like conceit reshuffles run in the background, with tools to check their progress. Everything is scoped to your own cookbook, or to a shared one you've joined.

      https://wereci.xyz/api/mcp
    • Scraps Kitchen gives any AI agent a persistent, household-aware kitchen memory. Unlike generic chatbot recall, Scraps maintains structured cooking data: what's in your fridge (with freshness tracking), who you cook for (with allergens, dietary restrictions, and preferences), your recipe collection (with cook notes and per-diner ratings), your shopping list, and your kitchen equipment. 27 tools across 6 domains let agents read kitchen context, suggest meals that respect dietary safety, update the pantry after cooking, and build a history of what works for your household. Every interaction makes the data richer. Cooking history, preference signals, kitchen awareness = better suggestions next time. All tools work via oAuth and a free scraps.kitchen account.

      https://api.scraps.kitchen/mcp

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      An MCP server for Mealie that provides curated tools for recipes, meal plans, and cookbooks with compact responses, enabling natural language management of your Mealie instance.
      1
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Provides recipe search and authoring, meal planning, shopping lists, and pantry tracking via task-shaped MCP tools.
      34 npm
      MIT