cookidoo-mcp

An MCP server that bridges LLM sessions (Claude, Gemini, or any MCP client) to Cookidoo custom recipes on a Thermomix (TM7 by default). Describe a recipe in a chat, and the server uploads it as a Cookidoo custom recipe with proper structured Thermomix settings (time, temperature, speed, reverse) so it looks and behaves like an official recipe on the device.

The server ships its own German authoring guide as an MCP prompt and resource, so the writing rules for Thermomix steps do not have to live in your prompts.

Disclaimer: Cookidoo/Vorwerk offers no official public API. This project relies on the reverse-engineered API of miaucl/cookidoo-api and may break whenever the Cookidoo backend changes. Use at your own risk.

Prior art this project builds on:

• miaucl/cookidoo-api - the unofficial Cookidoo API library used for login and session handling
• alexandrepa/mcp-cookidoo - first Cookidoo MCP server, source of the create/patch upload flow
• Xdev22/cookidoo-mcp - discovered the structured TTS and INGREDIENT annotations that make custom recipes look like official ones

Features

• upload_recipe - upload a recipe with structured ingredients and steps. The LLM supplies semantics only (text, time, temperature, speed, reverse); the server renders the German settings notation and computes all Cookidoo annotations itself. Optional image_url/image_base64 parameters attach a photo in the same call.
• set_recipe_image - set or replace the photo of an existing custom recipe, from an https URL or base64 data.
• list_custom_recipes - list your custom recipes.
• get_custom_recipe - fetch one custom recipe by id.
• delete_custom_recipe - delete a custom recipe by id.
• get_recipe_details - fetch any Cookidoo recipe by id.
• get_shopping_list, add_items_to_shopping_list, add_recipe_to_shopping_list - read and fill the shopping list.
• get_meal_plan, add_recipe_to_meal_plan - read and fill the weekly planner.
• MCP prompt and resource with the full German Thermomix authoring guide, plus compact server instructions delivered to every client on connect.
• Optional GitHub OAuth with a user allowlist and persistent client registrations for safe public exposure.

Recipe images

Custom recipes can carry a photo. Pass image_url or image_base64 (exactly one source; base64 works with or without a data URI prefix) to upload_recipe, or call set_recipe_image for a recipe that already exists. JPEG and PNG are supported, from 80x80 pixels (smaller images are rejected by Cookidoo) up to 10 MB. URL images are downloaded by the server itself (https only), and Cookidoo re-hosts every image on its own CDN. Clients should downscale images to about 800px (JPEG, quality around 70) before embedding them as base64. An image failure does not abort the recipe upload; the result then contains an image_warning instead.

Requirements

• Python 3.12 or newer
• uv
• A Cookidoo account with an active subscription

Setup

uv sync
cp .env.example .env

Then edit .env and fill in your Cookidoo credentials:

Variable	Meaning	Default
COOKIDOO_EMAIL	Cookidoo account email	required
COOKIDOO_PASSWORD	Cookidoo account password	required
COOKIDOO_COUNTRY	Country code	de
COOKIDOO_LANGUAGE	Language code	de-DE
THERMOMIX_MODEL	Device written to the recipe tools field	TM7

Locale examples:

Country	COOKIDOO_COUNTRY	COOKIDOO_LANGUAGE
Germany	de	de-DE
Austria	at	de-AT

Running

uv run cookidoo-mcp

This starts the server with streamable HTTP transport on http://127.0.0.1:8000/mcp. Host and port are configurable via MCP_HOST and MCP_PORT.

For clients that spawn the server as a subprocess, use stdio transport instead:

MCP_TRANSPORT=stdio uv run cookidoo-mcp

Client configuration

Claude Code

claude mcp add --transport http cookidoo http://localhost:8000/mcp

Claude Desktop

Add the server to your claude_desktop_config.json:

{
  "mcpServers": {
    "cookidoo": {
      "type": "http",
      "url": "http://localhost:8000/mcp"
    }
  }
}

Public exposure and OAuth

Connectors on claude.ai (web, mobile app, and the Claude Desktop connector dialog) are established from Anthropic servers, so LAN-only deployments are not reachable there. To use the server from those clients it must be exposed to the internet - and then it MUST be protected, otherwise anyone could use your Cookidoo account.

The server supports GitHub OAuth via FastMCP:

1. Register an OAuth app at https://github.com/settings/developers. Homepage: your MCP_BASE_URL; callback URL: <MCP_BASE_URL>/auth/callback.
2. Set GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET, MCP_BASE_URL, ALLOWED_GITHUB_USERS (and ideally MCP_JWT_SIGNING_KEY plus MCP_STATE_DIR for persistent client registrations - without it a restart disconnects all authorized clients) in the .env file and restart the container.
3. Make the server publicly reachable (see below).
4. Add the connector with your public https://.../mcp URL; Claude redirects you through the GitHub login once per client.

Only the GitHub accounts listed in ALLOWED_GITHUB_USERS are accepted; every other login is rejected after authentication. Without the GitHub variables the server runs unauthenticated as before - keep it LAN-only in that case.

Recommended public exposure: Cloudflare Tunnel

The battle-tested setup (and the one this project runs in production) is a Cloudflare Tunnel in front of a localhost-only server container:

1. Put a domain on Cloudflare (free plan; only the nameservers change, the registration stays where it is), create a tunnel under Zero Trust -> Networks -> Tunnels, and map a public hostname such as cookidoo.example.com to http://localhost:8443.

2. Run the connector next to the server (same host):

   docker run -d --name cloudflared --network host \
     --restart unless-stopped \
     -e TUNNEL_TOKEN=<your tunnel token> \
     cloudflare/cloudflared:latest tunnel run
   

3. Bind the server container to localhost only (the deploy script does this), drop the MCP_SSL_* variables (Cloudflare terminates TLS with auto-renewing certificates) and set MCP_BASE_URL and the GitHub app URLs to the tunnel hostname.

This needs no router port forwarding and works behind DS-Lite or CGNAT, because the tunnel connects outbound and Cloudflare provides a dual-stack edge - important since the claude.ai connector infrastructure connects over IPv4 only, so an IPv6-only port release is never reached.

Known pitfall: Tailscale Funnel does NOT work as the public endpoint for claude.ai connectors. The funnel edge intermittently aborts TLS handshakes, and the multi-request OAuth flow of the connector broker gives up on the first failure, surfacing as "Couldn't reach the MCP server" with zero requests in your logs - even though curl and Claude Code work fine through the same funnel.

Testing

uv run pytest

Unit and integration tests run offline against mocked HTTP. The end-to-end tests in tests/test_e2e.py talk to the live Cookidoo API and are skipped unless real credentials are present in .env.

Docker

Prebuilt image (recommended)

Every push to main builds a multi-arch image (amd64/arm64) via GitHub Actions and publishes it as ghcr.io/jsaedtler/cookidoo-mcp-docker:latest. On the server you only need the credentials file and one script:

sudo mkdir -p /docker/cookidoo-mcp
sudo cp .env.example /docker/cookidoo-mcp/.env   # fill in your credentials
./deploy/update-cookidoo-mcp.sh

deploy/update-cookidoo-mcp.sh stops and removes the old container, pulls the latest image and starts it again with --restart=unless-stopped. Re-run it any time to update. Adjust the ENV_FILE, SSL_DIR, STATE_DIR and PORT variables at the top of the script to your setup.

HTTPS without a tunnel

When you do not use the Cloudflare Tunnel (for example LAN-only use with Claude Desktop, which requires an https URL), the server can terminate TLS itself: set MCP_SSL_CERTFILE and MCP_SSL_KEYFILE and mount a certificate directory into the container (the deploy script does this via SSL_DIR). Any certificate you already have works, for example a Let's Encrypt certificate from another service on the same host. The hostname in the MCP URL must match the certificate. After a certificate renewal restart the container (docker restart cookidoo-mcp) so it picks up the new files.

Build locally

cp .env.example .env   # fill in your Cookidoo credentials
docker compose up -d --build

The server then listens on http://<host>:8000/mcp (Streamable HTTP) for clients in your network. To change the port, adjust both sides of the ports mapping in docker-compose.yml.

Notes:

• Credentials are injected at runtime via env_file; the .env file is never baked into the image (see .dockerignore).
• The container binds :: (dual-stack). If the Docker daemon runs with ip6tables: true, published ports are DNATed to the container's IPv6 address, so a v4-only bind would time out for all IPv6 clients even though the port looks open on IPv4.
• The image runs as a non-root user and builds on both amd64 and arm64.
• Typical deployment on a server: clone the repository, create .env, run docker compose up -d --build. The restart: unless-stopped policy brings the container back after reboots.