Cookidoo MCP Server

An MCP (Model Context Protocol) server for interacting with the Thermomix Cookidoo platform, built with FastMCP.

Disclaimer: This is an unofficial project. The developers are not affiliated with, endorsed by, or connected to Cookidoo, Vorwerk, Thermomix, or any of their subsidiaries or trademarks. It uses Cookidoo's private web API with your own account: that may conflict with Cookidoo's terms of use, and it can break whenever Cookidoo changes its site (a weekly live test watches for that). Use it at your own risk.

Features

• Recipe Search: Find recipes by keywords and/or ingredients, with a maximum total time

• Recipe Details: Fetch ingredients, steps and times of any Cookidoo recipe

• Custom Recipes: List, read, create, update and delete the recipes on your own account

• Shopping List: Add recipes and items, tick them off, rename, remove or clear

• Meal Plan: See the week, plan recipes on a day or remove them

• Collections: List, follow and create collections, add and remove their recipes

• Account: Subscription and linked Thermomix devices

• Guided Cooking: Steps can carry Thermomix settings (time, temperature, speed, reverse), preset on the machine

• Guided Prompt: create_thermomix_recipe walks the assistant through writing a proper Thermomix recipe (EN / FR / DE)

Related MCP server: cookidoo-mcp

Setup

Requires Python 3.12+ and uv.

uv sync
cp .env.example .env   # then fill in your Cookidoo credentials

Usage

Claude Code

claude mcp add cookidoo -- uv run --directory /path/to/mcp-cookidoo server.py

Claude Desktop

Bundle (easiest): download mcp-cookidoo-<version>.mcpb from the latest release and open it with Claude Desktop. It asks for your Cookidoo e-mail, password (kept in the system's secure storage), site and Thermomix; Claude Desktop installs Python and the dependencies itself.

From a checkout:

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "cookidoo": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/mcp-cookidoo", "server.py"]
    }
  }
}

Docker

Images for amd64 and arm64 are published to GitHub Container Registry: edge is built from every change on main, version tags (1, 1.2, 1.2.0) from releases. Keep the credentials in an env file (chmod 600) rather than in the client configuration:

{
  "mcpServers": {
    "cookidoo": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "--env-file", "/path/to/cookidoo.env",
               "ghcr.io/herp75/mcp-cookidoo:edge"]
    }
  }
}

cookidoo.env holds the variables of the table above (COOKIDOO_EMAIL=…, one per line). To build the image yourself: docker build -t mcp-cookidoo .; it runs as a non-root user.

Verifying a release

Images are signed keyless with cosign by the Docker workflow of this repository; release files carry GitHub build provenance:

cosign verify ghcr.io/herp75/mcp-cookidoo:2.0.0 \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  --certificate-identity-regexp '^https://github.com/herp75/mcp-cookidoo/\.github/workflows/docker\.yml@'
gh attestation verify mcp-cookidoo-2.0.0.mcpb --repo herp75/mcp-cookidoo

The server is also listed in the MCP Registry as io.github.herp75/mcp-cookidoo.

HTTP

uv run server.py --transport http                   # http://127.0.0.1:8000/mcp

# Reachable from other machines: a token is required, the server refuses to start without one
COOKIDOO_MCP_TOKEN=$(openssl rand -hex 32) COOKIDOO_MCP_HOST=0.0.0.0 uv run server.py --transport http

Clients then send Authorization: Bearer <token>. GET /health returns {"status":"ok"}. With Docker, the server must bind to all interfaces inside the container, so a token is required; publish the port on loopback only:

docker run --rm --env-file cookidoo.env -e COOKIDOO_MCP_HOST=0.0.0.0 \
  -e COOKIDOO_MCP_TOKEN="$(openssl rand -hex 32)" -p 127.0.0.1:8000:8000 \
  ghcr.io/herp75/mcp-cookidoo:edge --transport http

Use server.py rather than fastmcp run … --transport http, which skips these checks.

Development

uv run fastmcp dev inspector fastmcp.json           # MCP Inspector

Available Tools

Type: read = read-only; write = changes the account; destructive = deletes or overwrites data. Tools marked † refuse to run unless called with confirm=true, as a second safety layer on top of your client's approval prompt.

Recipe steps

A step is either plain text, or an object with Thermomix settings preset in guided cooking and/or ingredient links. The text holds one {settings} placeholder per setting, replaced by the setting written out in the account's language (COOKIDOO_LANGUAGE): French, English and German are supported, other languages are written in English. The settings preset on the Thermomix are the same in every language.

{
  "text": "Add the onion and the olive oil, then sauté {settings}.",
  "settings": [{"time": 180, "temperature": "120", "speed": "1", "reverse": true}],
  "ingredients": [{"text": "the onion", "ingredient": "1 onion, halved"}]
}

A setting's mode selects its fields. The limits are those of the Cookidoo recipe editor (snapshot of cookidoo.de, 2026-10-20), and they depend on the Thermomix the recipe is for:

speed is "soft" (stirring speed, Sanftrührstufe) or "0.5" to "10" by halves (written Stufe 0,5 in German). Cookidoo has no other mode for custom recipes (sous-vide, slow cooking, fermentation… only exist in catalogue recipes).

Target device. generate_recipe_structure, upload_custom_recipe and update_custom_recipe take an optional device (TM5, TM6, TM7) and refuse settings that device does not support, naming the allowed values. Without it: for an update, the recipe's own devices; then COOKIDOO_DEVICE; then the devices linked to the account (TM6 rules if a TM6 is among them, as TM6-valid steps also run on a TM7); then TM6. Times off the editor's grid (10 s steps up to 5 min, 30 s up to 20 min, then whole minutes) only give a warning. Which modes exist and which are TM7-only is read from the Cookidoo recipe editor of your account (cached for an hour), with the built-in snapshot as fallback; the tool output says which was used. Recipes already on Cookidoo are always readable, whatever their values, and are only checked when saved again.

Modes are written with their name, so the text should not repeat it ("then start {settings}" rather than "knead {settings}").

ingredients links words of the step text (their first occurrence) to a line of the ingredient list. Invalid settings and links are rejected. get_custom_recipe returns steps in the same format, so a recipe keeps its settings and links when edited.

Security

• The server stores your real Cookidoo password (Cookidoo has no OAuth): use a unique password.

• Prefer stdio. Use HTTP only with a token, on a trusted network.

• TLS certificate verification is always on; secrets are redacted from logs and error messages.

• Recipe content is untrusted input to the model. Keep your client's approval prompt on for write tools.

• upload_custom_recipe_image is the only tool that reads a local file and sends it to the internet. It is off until you set COOKIDOO_IMAGE_DIRS: point it at a folder that holds only recipe photos, not your home directory. Files outside it (also through symlinks) and anything but JPEG/PNG/WebP up to 10 MB are refused; images are re-encoded and their metadata (EXIF, GPS location) removed before upload. With Docker, mount that folder read-only (-v ~/RecipePhotos:/photos:ro -e COOKIDOO_IMAGE_DIRS=/photos).

See SECURITY.md for the threat model and how to report a vulnerability.

Development

See CONTRIBUTING.md for the workflow and docs/architecture.md for how the code is organised.

uv sync
uv run pytest --cov                    # tests, coverage must stay at 85 % or more
uv run ruff check . && uv run ruff format .
uv run pyright
scripts/check_insecure_patterns.sh     # TLS / bind-address guard, also run in CI

CI also runs pip-audit, gitleaks, CodeQL, dependency review and a Trivy scan of the Docker image.

Live tests

tests/live runs against the real Cookidoo API. Use a dedicated test account, never your own: the write tests create and delete recipes, a collection, shopping-list items and meal-plan entries (all named "MCP live test …").

cp .env.live.example .env.live && chmod 600 .env.live   # then fill in the test account
uv run pytest tests/live --live -p no:logging --assert=plain        # read-only
uv run pytest tests/live --live-write -p no:logging --assert=plain  # also writes, cleans up

They read only COOKIDOO_TEST_* and refuse to run with the account in COOKIDOO_EMAIL. The "Live tests" workflow runs them weekly with the secrets COOKIDOO_TEST_EMAIL and COOKIDOO_TEST_PASSWORD of the live environment (deployment branch main only; optional variables COOKIDOO_TEST_COUNTRY, COOKIDOO_TEST_LANGUAGE, default ch / de-CH). It also compares the Cookidoo recipe editor with devices.py and opens an issue if they differ.

Credits

• alexandrepa/mcp-cookidoo by Alexandre Patelli: the original server this fork extends.

• tobilektri/mcp-cookidoo (MIT): German Thermomix notation, mode limits per device, the editor-page parser and fixtures.

• vitaliemiron/cookidoo-mcp (Apache-2.0): recipe image upload and the meal-plan move; see NOTICE.

• danielkliem/mcp-cookidoo and sisques-labs/cookidoo-mcp: feature inspiration only, no code copied.

• cookidoo-api by miaucl: the Python client for the Cookidoo platform everything here is built on.

• Everyone who opened pull requests on the original repository: their ideas (search, recipe editing, Docker/STDIO support) shaped it.

License

MIT, see LICENSE and NOTICE.