mcp-cookidoo

Cookidoo MCP 服务

一个用于与 Thermomix Cookidoo 平台交互的 MCP（模型上下文协议）服务，基于 FastMCP 构建。

免责声明： 这是一个非官方项目。开发者与 Cookidoo、Vorwerk、Thermomix 或其任何子公司或商标均无关联，也未获得其认可。它使用 Cookidoo 的私有 Web API，并通过你自己的账户访问：这可能与 Cookidoo 的使用条款冲突，而且 Cookidoo 更改网站时也可能导致它无法使用（每周都会进行一次实时测试以监测这种情况）。使用风险由你自行承担。

功能

• 食谱搜索：按关键词和／或食材查找食谱，并可设置最长总用时
• 食谱详情：获取任意 Cookidoo 食谱的食材、步骤和用时
• 自定义食谱：列出、读取、创建、更新和删除你账户中的食谱
• 购物清单：添加食谱和物品、勾选完成项、重命名、移除或清空
• 膳食计划：查看一周安排、为某天规划食谱或移除食谱
• 收藏集：列出、关注和创建收藏集，并添加或移除其中的食谱
• 账户：订阅信息和已关联的 Thermomix 设备
• 引导式烹饪：步骤可包含 Thermomix 设置（时间、温度、速度、反转），并预设到设备上
• 引导式提示词：create_thermomix_recipe 会引导助手编写规范的 Thermomix 食谱（EN / FR / DE）

设置

需要 Python 3.12+ 和 uv。

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

变量	默认值	说明
COOKIDOO_EMAIL	—	Cookidoo 账户邮箱（必填）
COOKIDOO_PASSWORD	—	Cookidoo 账户密码（必填）
COOKIDOO_COUNTRY	fr	Cookidoo 网站国家／地区代码（fr、de、gb、es 等）
COOKIDOO_LANGUAGE	fr-FR	网站语言（例如 de-DE）；引导式烹饪设置也会以此语言编写
COOKIDOO_DEVICE	—（自动检测）	食谱适用的 Thermomix 设备（TM5、TM6、TM7）。未设置时：使用关联到账户的设备（若其中包含 TM6，则按 TM6 规则处理），否则使用 TM6
COOKIDOO_IMAGE_DIRS	—（禁用上传）	upload_custom_recipe_image 可读取图片的文件夹，以 : 分隔（Windows 上使用 ;）
COOKIDOO_MCP_TRANSPORT	stdio	stdio 或 http（与 --transport 相同）
COOKIDOO_MCP_HOST	127.0.0.1	HTTP 绑定地址。任何非回环地址都需要设置 COOKIDOO_MCP_TOKEN
COOKIDOO_MCP_PORT	8000	HTTP 端口
COOKIDOO_MCP_TOKEN	—	HTTP 模式的 Bearer 令牌，至少 32 个字符（例如 openssl rand -hex 32）
COOKIDOO_TEST_EMAIL、COOKIDOO_TEST_PASSWORD	—	仅用于实时测试：专用测试账户（参见实时测试）
COOKIDOO_TEST_COUNTRY、COOKIDOO_TEST_LANGUAGE	ch、de-CH	仅用于实时测试：测试账户的网站设置

用法

Claude Code

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

Claude Desktop

安装包（最简单）： 从最新版本下载 mcp-cookidoo-<version>.mcpb，并用 Claude Desktop 打开。它会询问你的 Cookidoo 邮箱、密码（保存在系统的安全存储中）、网站和 Thermomix；Claude Desktop 会自行安装 Python 和依赖项。

从代码检出目录运行：

添加到 claude_desktop_config.json：

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

Docker

amd64 和 arm64 镜像已发布到 GitHub Container Registry：edge 根据 main 上的每次更改构建，版本标签（1、1.2、1.2.0）则根据各个版本构建。请将凭据保存在环境变量文件中（chmod 600），不要放在客户端配置中：

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

cookidoo.env 保存上表中的变量（每行一个，例如 COOKIDOO_EMAIL=…）。 对于 upload_custom_recipe_image，请以只读方式挂载照片文件夹，并在 COOKIDOO_IMAGE_DIRS 中指定：将 "-v", "/path/to/photos:/photos:ro", "-e", "COOKIDOO_IMAGE_DIRS=/photos" 添加到镜像名称之前。 要自行构建镜像：docker build -t mcp-cookidoo .；镜像以非 root 用户身份运行。

验证发行版本

映像由本仓库的 Docker 工作流使用 cosign 进行无密钥签名；发行文件附带 GitHub 构建溯源信息：

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

该服务也已在 MCP Registry 中列出，名称为 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

然后，客户端发送 Authorization: Bearer <token>。GET /health 返回 {"status":"ok"}。 使用 Docker 时，服务必须在容器内绑定到所有网络接口，因此需要令牌；请仅在回环地址上发布端口：

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

如果没有令牌，服务只会响应发往 localhost、127.0.0.1 或 [::1]（Host 标头）的请求；从浏览器发起的请求也只会响应来自本机所托管页面的请求（Origin）： 这样可以阻止网页通过 DNS 重绑定访问该服务。使用反向代理或其他主机名时，请设置令牌。

请使用 server.py，不要使用会跳过这些检查的 fastmcp run … --transport http。

开发

uv run fastmcp dev inspector fastmcp.json           # MCP Inspector

可用工具

类型：read = 只读；write = 更改账户；destructive = 删除或覆盖数据。标记为 † 的工具除非以 confirm=true 作为参数调用，否则拒绝运行；这是在客户端的审批提示之外的第二层安全措施。

工具	类型	描述
食谱
search_recipes	read	按搜索词、食材和最长总用时搜索食谱
get_recipe_details	read	按 ID 获取食谱的食材、步骤和用时
自定义食谱
list_custom_recipes	read	列出账户中的自定义食谱
get_custom_recipe	read	获取可编辑 JSON 格式的自定义食谱
generate_recipe_structure	read	验证适用于 Thermomix（TM5/TM6/TM7）的新食谱，并返回其 JSON
upload_custom_recipe	write	根据该 JSON 为 Thermomix 创建自定义食谱
update_custom_recipe	destructive	根据该 JSON 替换现有自定义食谱
copy_recipe_to_custom	write	将目录食谱复制为新的自定义食谱，以便调整
upload_custom_recipe_image	destructive	使用本地图像设置自定义食谱的照片（参见 COOKIDOO_IMAGE_DIRS）
delete_custom_recipe †	destructive	永久删除自定义食谱
购物清单
get_shopping_list	read	获取食谱、食材和手动添加的项目，以及勾选状态和 ID
add_recipes_to_shopping_list	write	添加目录食谱和／或自定义食谱的食材
remove_recipes_from_shopping_list	destructive	移除食谱及其食材
add_shopping_list_items	write	手动添加项目（“牛奶”“2 个柠檬”）
edit_shopping_list_items	destructive	重命名手动添加的项目
mark_shopping_list_items	write	勾选项目，或取消勾选
remove_shopping_list_items	destructive	删除手动添加的项目
clear_shopping_list †	destructive	清空整个购物清单
膳食计划
get_meal_plan_week	read	获取从指定日期开始的 7 天内已计划的食谱
add_to_meal_plan	write	将目录食谱和／或自定义食谱安排到某一天
move_in_meal_plan	destructive	将已计划的食谱移至其他日期（失败时会回滚）
remove_from_meal_plan	destructive	从某一天移除食谱（食谱会保留）
收藏集
list_collections	read	列出你创建和关注的收藏集及其食谱（分页）
follow_collection / unfollow_collection	write / destructive	关注或取消关注 Cookidoo 收藏集
create_collection	write	创建自定义收藏集
delete_collection †	destructive	删除自定义收藏集（其中的食谱会保留）
add_to_collection / remove_from_collection	write / destructive	在自定义收藏集中添加或移除食谱
Thermomix
get_thermomix_modes	read	获取设备支持的设置和模式，以及限制和示例
账户
connect_to_cookidoo	read	检查配置／强制重新登录（可选，工具会自动登录）
get_account_info	read	获取用户、Cookidoo 站点、订阅和设备信息
list_devices	read	列出关联到账户的 Thermomix 设备

菜谱步骤

步骤可以是纯文本，也可以是包含 Thermomix 引导式烹饪预设设置和／或食材链接的对象。文本中每项设置对应一个 {settings} 占位符，系统会将其替换为账户语言（COOKIDOO_LANGUAGE）中的设置描述：支持法语、英语和德语，其他语言则使用英语。Thermomix 上的设置预设在所有语言中都相同。

{
  "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"}]
}

设置的 mode 用于选择其字段。限制与 Cookidoo 菜谱编辑器一致（取自 cookidoo.de 的快照，2026-10-20），并取决于菜谱所适用的 Thermomix 型号：

mode	设备	字段和限制	显示形式（fr）	显示形式（de）
manual（默认）	TM5、TM6、TM7	time（1 s – 99 min）、temperature（可选："37"…"95"，按 5 递增；"98"；"100"…"120"，按 5 递增；或仅限 TM6 使用的 "varoma"）、speed（设置温度时最高为 "6"）、reverse	3 min/120°C/vitesse 1	3 Min./120°C/Stufe 1
dough	TM6、TM7	time（最长 20 min）	Pétrin/2 min	Teig kneten/2 Min.
browning	TM7	time（最长 30 min）、temperature（"140"…"160"，按 5 递增）、power（gentle、intense）	Rissolage/5 min/160°C/intense	Anbraten/5 Min./160°C/Intensiv
steaming	TM7	time（最长 99 min）、speed（最高为 "5"）、reverse、accessory（varoma、simmering_basket、varoma_and_simmering_basket）	Cuisson vapeur/20 min/Varoma/vitesse 1	Dampfgaren/20 Min./im Varoma/Stufe 1
turbo	TM6、TM7	time（0.5、1 或 2 s）、pulses（1 至 9 次，仅限 TM7）	Turbo/0.5 sec/3 fois	Turbo/0.5 Sek./3x
rice_cooker	TM6、TM7	无	Rice cooker	Reis kochen
warm_up	TM6、TM7	temperature（"37"…"90"）、speed（"soft"、"1"、"2"；不含时间：Cookidoo 会将其删去）	Réchauffage/65°C/vitesse 2	Erwärmen/65°C/Stufe 2
blend	TM6、TM7	time（10 s – 5 min）、speed（"6"…"8"）	Mixage/1 min/vitesse 8	Pürieren/1 Min./Stufe 8

speed 可以是 "soft"（搅拌速度，Sanftrührstufe）或 "0.5" 至 "10"，以 0.5 为增量（德语显示为 Stufe 0,5）。Cookidoo 不提供其他自定义菜谱模式（水浴慢煮、慢炖、发酵……仅存在于目录菜谱中）。

目标设备。 generate_recipe_structure、upload_custom_recipe 和 update_custom_recipe 可选接受 device（TM5、TM6、TM7），并会拒绝该设备不支持的设置，同时列出允许的值。未指定时：更新菜谱会先使用菜谱自身的设备；然后使用 COOKIDOO_DEVICE；接着使用与账户关联的设备（若其中包含 TM6，则采用 TM6 规则，因为 TM6 支持的步骤也可在 TM7 上运行）；最后使用 TM6。时间不符合编辑器时间刻度（最多 5 min 时以 10 s 递增，最多 20 min 时以 30 s 递增，此后以整分钟递增）时，只会发出警告。可用模式及仅限 TM7 的模式会从账户的 Cookidoo 菜谱编辑器读取（缓存一小时）；若无法读取，则使用内置快照。工具输出会说明使用了哪种来源。Cookidoo 上已有的菜谱始终可读取，无论其设置值如何；只有再次保存时才会进行检查。

模式会以名称显示，因此文本中不应重复该名称（应写成“然后启动 {settings}”，而不是“揉面 {settings}”）。

ingredients 会将步骤文本中的词语（首次出现的位置）链接到食材列表中的某一行。无效的设置和链接会被拒绝。get_custom_recipe 会以相同格式返回步骤，因此编辑菜谱时会保留其设置和链接。

安全

• 服务会存储你真实的 Cookidoo 密码（Cookidoo 不支持 OAuth）：请使用独立密码。
• 优先使用 stdio。只有在可信网络中并设置令牌时才使用 HTTP。
• 始终启用 TLS 证书验证；日志和错误消息会对机密信息进行脱敏。
• 菜谱内容对模型而言是不可信输入。请保持客户端的写入工具审批提示开启。
• upload_custom_recipe_image 是唯一会读取本地文件并将其发送到互联网的工具。设置 COOKIDOO_IMAGE_DIRS 后才会启用：请将其指向只存放菜谱照片的文件夹，而不是你的主目录。文件夹外的文件（包括通过符号链接访问的文件）以及 JPEG/PNG/WebP 以外或超过 10 MB 的文件都会被拒绝；图片会在上传前重新编码，并移除其元数据（EXIF、GPS 位置）。使用 Docker 时，请以只读方式挂载该文件夹（-v ~/RecipePhotos:/photos:ro -e COOKIDOO_IMAGE_DIRS=/photos）。

有关威胁模型以及如何报告漏洞，请参阅 SECURITY.md。

开发

有关工作流，请参阅 CONTRIBUTING.md；有关代码的组织方式，请参阅 docs/architecture.md。

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 还会运行 pip-audit、gitleaks、CodeQL、依赖项审查以及对 Docker 镜像进行 Trivy 扫描。

实时测试

tests/live 会针对真实的 Cookidoo API 运行。请使用专用测试账户，切勿使用你自己的账户：写入测试会创建并删除菜谱、收藏集、购物清单条目和膳食计划条目（名称均为 “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

这些测试仅读取 COOKIDOO_TEST_*，并且如果账户与 COOKIDOO_EMAIL 中的账户相同，就会拒绝运行。“Live tests” 工作流每周会使用 live 环境的机密 COOKIDOO_TEST_EMAIL 和 COOKIDOO_TEST_PASSWORD 运行测试（仅限部署分支 main；可选变量 COOKIDOO_TEST_COUNTRY、COOKIDOO_TEST_LANGUAGE，默认值为 ch / de-CH）。它还会将 Cookidoo 菜谱编辑器与 devices.py 进行比较，如果两者不同，就会创建一个 issue。

致谢

• alexandrepa/mcp-cookidoo，作者 Alexandre Patelli：本分支在此原始服务的基础上扩展而成。
• tobilektri/mcp-cookidoo（MIT）：德语 Thermomix 标记法、各设备的模式限制、编辑器页面解析器和测试夹具。
• vitaliemiron/cookidoo-mcp（Apache-2.0）： 菜谱图片上传和膳食计划移动功能；请参阅 NOTICE。
• danielkliem/mcp-cookidoo 和 sisques-labs/cookidoo-mcp：仅用于功能灵感，未复制任何代码。
• cookidoo-api，作者 miaucl：此处所有内容所基于的 Cookidoo 平台 Python 客户端。
• 向原始代码库提交过拉取请求的所有人：他们的想法（搜索、菜谱编辑、Docker/STDIO 支持）塑造了这个项目。

许可证

MIT，详见 LICENSE 和 NOTICE。