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
• Recipe 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 recipe catalogue (time, difficulty, ingredients, rating, device 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 token 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 devices and accessories linked to the account (include_devices=true).
• Optional token persistence (COOKIDOUGH_TOKEN_FILE): the OAuth2 tokens survive a server restart and skip the login for the cookidoo-api paths.

Recipe lookup, creation & import

• Fetch full details of up to 20 catalogue recipes in one call (get_recipe_details with recipe_ids, an unknown ID yields an error entry instead of failing the batch) including the grouped cooking steps (instructions, plain text with the appliance icons spelled out), 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 catalogue recipe into the user's custom recipes at a chosen serving size (clone_recipe_as_custom).
• Build, validate, and upload custom 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 recipe catalogue (search_recipes): total time, difficulty, categories, required/excluded ingredients, minimum rating, portions, device 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 platform-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 platform endpoints (not part of cookidoo-api), verified against the live API; individual failures degrade gracefully instead of failing the call.

Quality, safety & transport

• Recipe 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. It parses no options of its own — everything is configured through the COOKIDOUGH_* environment variables.

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 | - | Account email | | COOKIDOUGH_PASSWORD | yes | - | Account password (stored in memory as SecretStr) | | COOKIDOUGH_COUNTRY | no | de | ISO 3166-1 alpha-2 country code (case-insensitive) | | COOKIDOUGH_LANGUAGE | no | de | ISO 639-1 (de, paired with COOKIDOUGH_COUNTRY) or BCP-47 (de-DE); case-normalized to lang-REGION | | COOKIDOUGH_MCP_MODE | no | stdio | Transport: stdio or http | | COOKIDOUGH_MCP_HOST | no | 127.0.0.1 | Bind host (HTTP only) | | COOKIDOUGH_MCP_PORT | no | 8765 | Bind port (HTTP only) | | COOKIDOUGH_QUALITY_BAR | no | 70 | Minimum recipe quality score (0-100) for custom uploads | | COOKIDOUGH_TOKEN_FILE | no | - | Optional path for persisting the OAuth2 tokens across restarts (skips the login while the refresh token is valid) |

A restored token authenticates every call immediately — the library calls as well as search and the interaction endpoints.

Security note on COOKIDOUGH_TOKEN_FILE: the file holds the OAuth2 access and refresh tokens — anyone who can read it can act as your platform account, and a refresh token outlives a session cookie. The server creates it with 0600 permissions before writing; keep it outside any repository (the bundled `.gi