Cookidoo MCP

Documentation / Overview

Connect AI intent to the Cookidoo workflow.

Start the MCP server, understand its 16 tools, and build safe automations for recipes, guided cooking, images, shopping lists, and meal planning.

Quick start

Run the published package.

Python 3.12 or newer is required. Keep credentials in a private local file, outside the repository.

mkdir -p ~/.config/cookidoo-mcp
chmod 700 ~/.config/cookidoo-mcp
touch ~/.config/cookidoo-mcp/.env
chmod 600 ~/.config/cookidoo-mcp/.env

Edit that file with your Cookidoo login:

COOKIDOO_EMAIL=your-login
COOKIDOO_PASSWORD=your-password

With uv installed, start the stdio MCP server without cloning the repository:

uvx cookidoo-mcp \
  --env-file ~/.config/cookidoo-mcp/.env

Use the same command and arguments in any MCP client:

{
  "mcpServers": {
    "cookidoo": {
      "command": "uvx",
      "args": [
        "cookidoo-mcp",
        "--env-file",
        "/absolute/path/to/cookidoo-mcp.env"
      ]
    }
  }
}
Keep the password out of client JSON

Point the client at a private .env file with an absolute path. Existing environment variables take precedence over values in that file.

How do I run the source checkout for development? 
git clone https://github.com/vitaliemiron/cookidoo-mcp.git
cd cookidoo-mcp
python3 -m venv venv
source venv/bin/activate
python -m pip install -r requirements-dev.txt
cp .env.example .env
venv/bin/fastmcp run server.py

Restart after changing server.py or cookidoo_service.py; the long-lived process keeps authenticated state in memory.

Explore the system

Human-readable and model-readable by design.

16 tools

Tool reference

Arguments, behavior, source requirements, and expected output for every MCP action.

 Guided setup

Configuration generator

Choose macOS, Linux, or Windows and get copy-ready steps for Codex, Claude Desktop, or VS Code.

 Schemas

Guided cooking

TTS, ingredient weighing, smart-function modes, and JavaScript UTF-16 positions.

 Workflows

Shopping and planning

Recipe-grouped ingredients and the rolling seven-day meal-planning contract.

 Reliability

Testing and monitoring

Offline unit checks, five authenticated contracts, cleanup rules, and regression issues.

Find a tool

Search the MCP surface.

connect_to_cookidooAuthenticate and store the shared session. get_recipe_detailsRead official recipe metadata and ingredients. get_custom_recipe_detailsRead full private recipe content. get_shopping_list_ingredientsRead shopping items grouped by recipe. get_meal_plan_weekRead a complete seven-day planning window. add_recipes_to_meal_planAdd official or customer recipes to a day. remove_recipe_from_meal_planRemove one recipe from a planned day. move_recipe_in_meal_planMove a recipe between days with rollback. copy_recipe_to_customCopy an official recipe to access full steps. generate_recipe_structureBuild a validated upload-ready recipe object. validate_guided_recipe_structureValidate guided-cooking JSON. calculate_annotation_positionCalculate JavaScript UTF-16 text ranges. update_custom_recipe_stepsReplace private steps and annotations. update_custom_recipe_ingredientsReplace ingredients and structured amounts. upload_custom_recipe_imageNormalize and attach an owned image. upload_custom_recipeCreate a private recipe in Cookidoo.

For AI agents

Skip the page chrome.

Use the purpose-built machine-readable resources when indexing or reasoning about the project:

ResourcePurpose
/llms.txtConcise navigation and context for language models.
/llms-full.txtConsolidated project and API guidance.
/tools.jsonMachine-readable tool names, parameters, categories, and summaries.
/raw/*.mdUnstyled Markdown versions of the technical guides.

Important boundary

This is an unofficial integration.

The server combines the third-party cookidoo-api package with direct requests to undocumented Cookidoo endpoints. It is not affiliated with Vorwerk, Thermomix, or Cookidoo.

Preserve user data

Prefer read-only investigation. Never overwrite or delete a private recipe unless the user explicitly identifies it and requests that action.