Cookidough MCP Server

An unofficial Model Context Protocol (MCP) server for the Thermomix® Cookidoo® platform. Plug it into Claude Desktop, Claude Code or any other MCP-aware client and let your LLM search recipes, manage shopping lists and meal plans, and upload custom recipes.

Unofficial project. This is an independent, community-built MCP server. It is not developed, sponsored, endorsed, or affiliated with Vorwerk, Thermomix®, or Cookidoo®. The name "Thermomix" and "Cookidoo" is used here purely to identify the third-party service this software talks to. See Disclaimer & trademarks for details.

• 42 MCP tools across 7 domains (auth, recipes, collections, shopping, calendar, discovery, interactions), plus 3 MCP resources and 2 prompts
• Dual transport: stdio (default) and streamable HTTP
• Thermomix quality gate that blocks low-quality custom recipe uploads
• Guided-cooking annotations (TTS time/speed spans, INGREDIENT spans) — delivered explicitly by the LLM or inferred server-side from plain text
• Web recipe import via recipe-scrapers (200+ supported sites)
• Filtered search of the Cookidoo recipe library (time, difficulty, ingredients, rating, Thermomix model, …)
• Ingredient-based recipe suggestions — library-wide or scoped to the user's own collections
• Recipe interactions: rate, bookmark, personal notes, cooked-history
• Calendar→shopping-list in one call, personalized recommendations, nutrition data, and optional cookie persistence across restarts

Table of contents

• Features
• Requirements
• Quickstart
• MCP client setup
• Configuration
• Tool reference
• Resources & prompts
• Quality gate
• Guided-cooking annotations
• HTTP transport
• Development
• Architecture
• Troubleshooting
• Credits
• Disclaimer & trademarks
• License

Features

A high-level overview of what the server can do, grouped by domain. The exact tool names live in the Tool reference further below.

Account & authentication

• Lazy login on first tool call — no separate connect step.
• Read the user profile and active subscription, including subscription level, type, and expiry; optionally include the Thermomix devices and accessories linked to the account (include_devices=true).
• Optional cookie persistence (COOKIDOUGH_COOKIES_FILE): valid session cookies survive a server restart and skip the OAuth2 login round-trip.

Recipe lookup, creation & import

• Fetch full Cookidoo recipe details (get_recipe_details) including categories, collections and per-serving nutrition values; optionally with the user's own rating, the community rating and the personal note (include_interactions=true) and every recipe photo in square/portrait/landscape variants (include_images=true).
• List, read, delete the authenticated user's custom recipes.
• Edit an existing custom recipe in place: pass recipe_id to upload_custom_recipe for a full-replace update (fetch → edit → resubmit).
• Upload a photo for a custom recipe (set_custom_recipe_image): local file or URL, JPEG/PNG — uploaded via Vorwerk's signed Cloudinary flow and preserved across later recipe updates.
• Clone any Cookidoo recipe into the user's custom recipes at a chosen serving size (clone_recipe_as_custom).
• Build, validate, and upload custom Thermomix recipes from structured input, with guided-cooking annotations (TTS, INGREDIENT, all seven MODE variants).
• Import a recipe directly from any of 200+ supported recipe sites via recipe-scrapers, returning the parsed draft + a quality report and uploading when the gate passes.
• Filtered search of the Cookidoo recipe library (search_recipes): total time, difficulty, categories, required/excluded ingredients, minimum rating, portions, Thermomix model, accessories, sort order.
• Ingredient-based suggestions (suggest_recipes_from_ingredients) — library-wide via the server-side ingredient filter, or scoped to the user's collections when collection_ids is given.
• Personalized recommendations (get_recipe_recommendations): the "For you" feed, or recipes similar to a given one.

Collections (managed + custom)

• Browse and subscribe to / unsubscribe from Cookidoo-curated managed collections.
• Full CRUD over custom collections: create, list, delete, add recipes, remove a single recipe.

Shopping list

• Read the full list grouped by source (recipe ingredients vs. free-text items), including the recipes whose ingredients are currently on it.
• Push and pull recipe ingredients for regular and custom recipes (add_recipes_to_shopping_list, add_custom_recipes_to_shopping_list, the matching remove_* variants).
• Calendar mode: add_recipes_to_shopping_list with from_date/to_date puts every recipe planned in that range (incl. custom recipes, deduplicated) on the list in one call.
• Add, remove, rename, and check / uncheck free-text shopping items (add_additional_items, rename_additional_items, set_additional_items_ownership).
• Check / uncheck recipe-derived ingredient items (set_ingredient_items_ownership).
• Wipe the whole list in one call.

Calendar / meal plan

• Read the meal plan for any week.
• Schedule and remove regular and custom recipes on a specific date (add_recipes_to_calendar, add_custom_recipes_to_calendar, remove_recipe_from_calendar, remove_custom_recipe_from_calendar).

Recipe interactions

• Rate recipes (1-5 stars), bookmark them, keep a personal note, and log them in the cooking history (catalogue and own recipes) — all through one write tool (set_recipe_interactions) with per-action success reporting; read the history back via get_cooking_history.
• Read everything back via get_recipe_details with include_interactions=true; list bookmarks via list_bookmarked_recipes.
• These wrap undocumented Cookidoo endpoints (not part of cookidoo-api), verified against the live API; individual failures degrade gracefully instead of failing the call.

Quality, safety & transport

• Thermomix quality gate that scores every draft and refuses low-quality custom recipe uploads unless explicitly forced.
• All credentials kept in memory as SecretStr, with email + token redaction in every log message and upstream error body.
• Per-request HTTP timeout; reentrant, lock-protected session lifecycle.
• Dual transport: stdio (default) and streamable HTTP.

Requirements

• Python 3.12 or newer
• A valid Cookidoo account (COOKIDOUGH_EMAIL / COOKIDOUGH_PASSWORD)
• Optional: uv for the recommended client setup, or pip if you prefer

Quickstart

git clone https://github.com/Poket-Jony/cookidough-mcp.git
cd cookidough-mcp
cp .env.example .env          # fill in COOKIDOUGH_EMAIL / COOKIDOUGH_PASSWORD
./run.sh

run.sh is idempotent: it detects Python 3.12+, creates .venv/, installs the project the first time around, loads .env, validates credentials, and starts the server. Subsequent runs skip the install step and start immediately. Any extra arguments are forwarded to cookidough-mcp.

./run.sh --help                       # CLI help
COOKIDOUGH_MCP_MODE=http ./run.sh       # start over HTTP instead of stdio

MCP client setup

Claude Desktop / Claude Code

Two ways to wire it up — pick one and add it to your MCP client config (claude_desktop_config.json or ~/.claude/mcp.json).

Option A — using run.sh (recommended, no extra tooling):

{
  "mcpServers": {
    "cookidough": {
      "command": "/absolute/path/to/cookidough-mcp/run.sh",
      "env": {
        "COOKIDOUGH_EMAIL": "you@example.com",
        "COOKIDOUGH_PASSWORD": "..."
      }
    }
  }
}

Option B — using uvx (no clone required; works locally with --from):

{
  "mcpServers": {
    "cookidough": {
      "command": "uvx",
      "args": [
        "--from",
        "/absolute/path/to/cookidough-mcp",
        "cookidough-mcp"
      ],
      "env": {
        "COOKIDOUGH_EMAIL": "you@example.com",
        "COOKIDOUGH_PASSWORD": "...",
        "COOKIDOUGH_COUNTRY": "de",
        "COOKIDOUGH_LANGUAGE": "de-DE",
        "COOKIDOUGH_QUALITY_BAR": "70"
      }
    }
  }
}

Smoke-test with the MCP Inspector

npx @modelcontextprotocol/inspector ./run.sh

The inspector lists every registered tool and lets you call them interactively.

Configuration

The server is configured purely via environment variables (see .env.example):

| Variable | Required | Default | Description | | ----------------------- | -------- | ----------- | -------------------------------------------------------- | | COOKIDOUGH_EMAIL | yes | - | Cookidoo account email | | COOKIDOUGH_PASSWORD | yes | - | Cookidoo account password (stored in memory as SecretStr) | | COOKIDOUGH_COUNTRY | no