Mealie MCP Server

Mealie MCP 服务

一个模型上下文协议（MCP）服务，可通过 Claude Desktop 等客户端，将 AI 助手连接到你的 Mealie 食谱数据库。

目录

• 功能
• 快速开始
• 配置
• 远程访问
• Docker
• 使用示例
• 可用工具
• 开发
• 重要说明
• 支持与贡献
• 许可证与鸣谢

功能

• 食谱： 创建、读取、更新、导入、复制和删除食谱。
• 搜索： 使用 AND/OR 逻辑按文本、分类、标签和工具筛选。
• 图片和资源： 上传食谱图片和文件，或通过 URL 设置图片。
• 营养与显示： 设置每份营养信息和食谱可见性选项，例如 showAssets 和 showNutrition。
• 食材： 根据 Mealie 的食物和单位词汇表解析自由文本食材。
• 购物清单： 管理清单和条目、执行批量操作，并按比例调整食谱食材数量后添加。
• 组织管理： 管理分类、标签、食物、单位和食谱工具；查找未使用的分类和标签。
• 膳食计划： 查看、创建、更新和删除膳食计划条目，创建多个条目，并将食谱标记为今天已制作。

快速开始

前提条件

• Python 3.12+
• 正在运行的 Mealie 实例，以及从账户设置中获取的 API 密钥
• 包管理器 uv

安装

选项 1：使用 MCP SDK CLI（推荐）

克隆仓库，然后使用 Python MCP SDK 提供的 mcp 命令将服务安装到 Claude Desktop（无需单独安装 fastmcp 包）：

git clone https://github.com/rldiao/mealie-mcp-server.git
cd mealie-mcp-server
uv sync --locked
uv run mcp install src/server.py --with-editable . \
  --env-var MEALIE_BASE_URL=https://your-mealie-instance.com \
  --env-var MEALIE_API_KEY=your-mealie-api-key

选项 2：使用 uvx

将以下内容添加到 MCP 客户端配置中，即可直接从 GitHub 运行，无需克隆（在 Claude Desktop 中，使用 claude_desktop_config.json）：

{
  "mcpServers": {
    "mealie-mcp-server": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/rldiao/mealie-mcp-server",
        "mealie-mcp-server"
      ],
      "env": {
        "MEALIE_BASE_URL": "https://your-mealie-instance.com",
        "MEALIE_API_KEY": "your-mealie-api-key"
      }
    }
  }
}

重启 Claude Desktop 以加载服务。

配置

在 MCP 客户端配置或 shell 中设置环境变量。对于本地检出版本，也可以将 .env.template 复制为 .env 并填写实例信息。切勿提交 API 密钥。

变量	默认值	说明
MEALIE_BASE_URL	必填	Mealie 基础 URL；如有需要，请包含协议和端口
MEALIE_API_KEY	必填	从 Mealie 账户设置中获取的 API 密钥
MEALIE_ENABLE_AI_IMPORT	false	选择启用 AI 食谱导入；接受 true/false（不区分大小写）
MCP_TRANSPORT	stdio	stdio、streamable-http 或旧版 sse
MCP_HOST	127.0.0.1	HTTP 绑定地址；在容器中使用 0.0.0.0
MCP_PORT	8765	HTTP 端口，范围为 1 到 65535
LOG_LEVEL	INFO	DEBUG、INFO、WARNING、ERROR 或 CRITICAL

远程访问

默认的 stdio 传输方式适用于本地客户端。若要为 HTTP 客户端提供服务，请按上述说明配置 Mealie 凭据，然后在检出目录中运行：

export MCP_TRANSPORT=streamable-http
export MCP_HOST=127.0.0.1
export MCP_PORT=8765
uv run mealie-mcp-server

服务将在 http://<host>:<port>/mcp 提供 MCP 端点。

安全性： HTTP 传输没有内置身份验证。任何能够访问此端点的人，都可以通过其工具使用已配置的 Mealie 凭据。请将其限制在可信网络接口上；如需远程访问，请使用强制身份验证和 HTTPS 的反向代理。

Docker

Dockerfile 会以持久容器的形式运行服务。

构建

docker build -t mealie-mcp-server .

独立运行

docker run -d \
  --name mealie-mcp \
  -e MEALIE_BASE_URL=http://your-mealie-host:9000 \
  -e MEALIE_API_KEY=your-mealie-api-key \
  -e MCP_TRANSPORT=streamable-http \
  -e MCP_HOST=0.0.0.0 \
  -e MCP_PORT=8765 \
  -p 127.0.0.1:8765:8765 \
  mealie-mcp-server

该端口仅发布到主机的回环接口。允许远程访问之前，请参阅远程访问。

Docker Compose

将此服务添加到运行 Mealie 的 Compose 文件中。此示例假设 Mealie 服务名为 mealie，且两个服务都使用在该 Compose 文件中定义、名为 mealie_net 的网络。在 shell 或 Compose .env 文件中设置 MEALIE_API_KEY。

services:
  mealie-mcp:
    build: .
    container_name: mealie-mcp
    restart: unless-stopped
    environment:
      MEALIE_BASE_URL: http://mealie:9000
      MEALIE_API_KEY: ${MEALIE_API_KEY}
      MCP_TRANSPORT: streamable-http
      MCP_HOST: "0.0.0.0"
      MCP_PORT: "8765"
    expose:
      - "8765"
    networks:
      - mealie_net

expose 不会将端口发布到主机。要远程访问，请在同一网络上连接反向代理，并遵循 HTTP 安全指南。

使用示例

"Search for chicken recipes"
"Create a new recipe for pasta carbonara"
"Mark the meatloaf recipe as made today"
"Create a shopping list for this week"
"Add all ingredients from the lasagna recipe to my shopping list"
"Plan chicken soup for lunch on Friday"

有关详细工作流和故障排除，请参阅使用示例。

可用工具

食谱工具（12 项操作）

• get_recipes - 列出／搜索食谱，并支持高级筛选
• get_recipe - 获取完整食谱详情，或使用 concise=true 获取摘要
• create_recipe - 创建食谱；只需提供名称，还可选填食材、步骤、元数据、营养信息和显示设置
• import_recipe_from_url - 从网页导入食谱
• update_recipe - 更新内容或元数据，包括营养信息和显示设置；未提供的字段会保留，空列表会清除内容
• duplicate_recipe - 克隆食谱
• mark_recipe_last_made - 更新上次制作时间戳
• set_recipe_image_from_url - 从 URL 设置图片
• upload_recipe_image_file - 上传图片文件
• upload_recipe_asset_file - 上传文档／资源
• update_recipe_categories_and_tags - 使用 ID 替换或清除分类、标签，或同时执行两项操作
• delete_recipe - 删除食谱

购物清单工具（15 项操作）

• get_shopping_lists - 列出所有购物清单
• create_shopping_list - 创建购物清单
• get_shopping_list - 按 ID 获取清单
• update_shopping_list - 重命名清单，同时保留其他字段
• delete_shopping_list - 删除清单
• add_recipe_to_shopping_list - 添加食谱食材
• remove_recipe_from_shopping_list - 移除食谱食材
• get_shopping_list_items - 列出所有条目
• get_shopping_list_item - 按 ID 获取条目
• create_shopping_list_item - 创建单个条目
• create_shopping_list_items_bulk - 批量创建条目
• update_shopping_list_item - 更新条目（保留字段）
• update_shopping_list_items_bulk - 批量更新条目
• delete_shopping_list_item - 删除单个条目
• delete_shopping_list_items_bulk - 批量删除条目

分类工具（6 项操作）

• get_categories - 列出／搜索分类
• get_empty_categories - 查找未使用的分类
• create_category - 创建分类
• get_category - 必须且只能通过 category_id 或 category_slug 之一获取
• update_category - 更新分类
• delete_category - 删除分类

标签工具（6 项操作）

• get_tags - 列出／搜索标签
• get_empty_tags - 查找未使用的标签
• create_tag - 创建标签
• get_tag - 必须且只能通过 tag_id 或 tag_slug 之一获取
• update_tag - 更新标签
• delete_tag - 删除标签

食品工具（5 项操作）

• get_foods - 列出／搜索食品（为结构化食材解析 ID）
• create_food - 创建食品
• get_food - 按 ID 获取
• update_food - 更新食品
• delete_food - 删除食品

单位工具（5 项操作）

• get_units - 列出／搜索单位
• create_unit - 创建单位
• get_unit - 按 ID 获取
• update_unit - 更新单位
• delete_unit - 删除单位

厨房工具（5 项操作）

• get_tools - 列出／搜索食谱工具（包含 householdsWithTool）
• create_tool - 创建工具
• get_tool - 必须且只能通过 tool_id 或 tool_slug 之一获取
• update_tool - 更新工具
• delete_tool - 删除工具

解析器工具（1 项操作）

• parse_ingredients - 在一个请求中解析一行或多行食材，并返回列表

餐食计划工具（6 项操作）

• get_all_mealplans - 列出餐食计划
• create_mealplan - 创建餐食计划条目
• create_mealplan_bulk - 创建多个条目
• update_mealplan - 更新条目，同时保留未提供的字段
• delete_mealplan - 删除条目
• get_todays_mealplan - 获取今天的餐食

总计：61 个工具

启用 MEALIE_ENABLE_AI_IMPORT=true 后，import_recipe_with_ai 会增加一项可选的食谱操作：总计 62 个工具，其中包括 13 个食谱工具。禁用时，该工具不会出现在发现列表中，也无法调用。

迁移合并后的工具（破坏性变更）

冗余的 MCP 名称已被移除，不再作为别名保留。请刷新客户端的工具列表并更新已保存的调用：

已移除的工具	替代项
create_recipe_full	使用相同参数调用 create_recipe
get_recipe_detailed	get_recipe（默认返回完整详情）
get_recipe_concise	get_recipe，并设置 concise=true
patch_recipe	使用相同参数调用 update_recipe
set_recipe_categories	update_recipe_categories_and_tags，并设置 category_ids
set_recipe_tags	update_recipe_categories_and_tags，并设置 tag_ids
get_category_by_slug	get_category，并设置 category_slug
get_tag_by_slug	get_tag，并设置 tag_slug
get_tool_by_slug	get_tool，并设置 tool_slug
parse_ingredient	parse_ingredients(ingredients=[...])；读取第一个结果

现有的 create_recipe 和 update_recipe 调用仍受支持。食谱更新现在可以同时修改内容和元数据；未提供或值为 null 的字段保持不变。食材和说明列表只会替换已提供的字段。营养信息仍会整体替换，而设置则会合并。

不同操作仍保持独立：单项写入和批量写入具有不同的响应／失败约定；分页列表与单项查询、未使用的整理项查询以及今天的餐食计划各不相同。食谱 URL 导入、图片 URL 抓取和文件上传也执行不同的操作。

可选 AI 食谱导入

在 MCP 客户端的环境、Shell 或本地 .env 中设置 MEALIE_ENABLE_AI_IMPORT=true。重启服务并刷新客户端的工具列表。此设置适用于 stdio、SSE 和 Streamable HTTP。离线 SDK 发现仍然不需要配置或网络，只列出默认工具；可选工具会在运行时启动时注册（或传入显式启用的 ServerConfig 时注册）。

import_recipe_with_ai 要求 Mealie 3.23.0+，并且 API 用户所属群组已配置默认 AI 提供商。它接受以下任意组合：

• content：纯文本、原始 HTML 或 JSON；也可用于更正或备注。
• url：HTTP(S) 食谱或视频 URL，由 Mealie 获取并保存为来源。
• image_paths：MCP 服务文件系统可访问的有序图片路径，而非远程调用者电脑上的路径。多张照片会合并为一道食谱；第一张将作为封面图片。

至少需要一个非空白来源。如果来源之间存在冲突，将合并这些来源，并以粘贴的内容为准。可选的 translate_language 用于请求翻译。create_new_organizers 默认为 false：可以分配匹配的现有标签、类别和厨房工具，但只有明确请求时才会创建新的条目。

每次导入前，服务都会读取 /api/groups/self，检查 aiEnabled，并在导入照片时检查 imageProviderEnabled。如果能力信息缺失、格式错误或查询失败，会返回明确错误，而不是静默地显示为已禁用。视频检测和对音频提供商的要求由 Mealie 处理。这些检查确认的是配置状态，不代表提供商连接正常、凭据有效或仍有可用额度。

此工具会立即创建并保存食谱。 Mealie 配置的 AI 提供商会处理来源材料，且可能产生费用。请检查返回的食谱是否准确。导入的读取超时时间为 300 秒；其他 API 调用仍使用原有的超时时间。不会自动重试任何导入。如果超时或连接失败，请在重试或切换工具前检查 Mealie：食谱可能已经创建成功。如果后续获取失败，错误中会包含 created_slug 和 stage；请获取该食谱，而不要再次导入。

请根据任务选择工具：

任务	工具
普通食谱网页	import_recipe_from_url
非结构化文本、照片、视频、组合来源、翻译或明确指定使用 AI 导入	import_recipe_with_ai（需主动启用）
保存已整理好的食材和说明	create_recipe
为现有食谱添加照片，不提取内容	upload_recipe_image_file

主动启用选项只控制这个新工具。它不会禁用 Mealie 在抓取 URL 时使用的 AI 回退机制，也不会禁用其他现有 AI 功能。请参阅 Mealie 的 AI 导入文档和使用示例。

开发

设置

克隆仓库后，安装开发依赖项：

uv sync --locked --extra dev

如需手动测试，请配置 Mealie 实例：

cp .env.template .env
# Edit .env with your Mealie instance details

启动 MCP Inspector：

uv run mcp dev src/server.py

运行离线检查；这些检查不需要 Mealie 实例或凭据：

uv run ruff check src tests
uv run pytest -q

项目结构

路径	用途
src/mealie/	HTTP 客户端和 API 混入类
src/tools/	FastMCP 工具定义和注册
src/models/	Pydantic 请求和响应模型
src/server.py	配置、生命周期和入口点
src/prompts.py	MCP 提示词
tests/	离线测试和测试夹具

仓库规范见 AGENTS.md，其中还包含针对源代码和测试的专项说明。

自动化测试套件使用虚假的 HTTP 响应，并包含本地 HTTP 传输检查。它不能替代针对你所部署的 Mealie 版本进行的兼容性测试。

重要说明

以下调用使用 Python 风格的表示法来展示 MCP 工具参数；它们不是独立的 Python 脚本。

按标签和类别筛选

筛选食谱时，必须使用 slug 或 UUID，而不是显示名称：

先使用 get_tags() 或 get_categories() 查找正确的 slug：

get_recipes(tags=["quick-meals", "healthy"])

例如，传入 quick-meals，而不是显示名称 Quick Meals。

营养信息会被替换，而非合并

Mealie 在写入时会替换整个 nutrition 对象。update_recipe 也遵循此行为，因此请传入所有要保留的值：

# Clears every nutrition value except fat.
update_recipe(slug="...", nutrition={"fatContent": "12"})

批量解析食材

手动解析食材时，每种食材需要调用一到两次 get_foods / get_units。parse_ingredients 可在一次请求中处理整份食谱，并返回可直接传给 create_recipe 的结果：

parse_ingredients(ingredients=["1/4 cup chopped onion", "2 large eggs"])
# -> [{"input": "1/4 cup chopped onion", "confidence": 0.99, "quantity": 0.25,
#      "unit": {"id": "...", "name": "cup"},
#      "food": {"id": "...", "name": "onion"}, "note": "chopped"}, ...]

null 单位或食材表示你的实例中没有匹配项；请使用 create_food / create_unit 创建，或将文本留在备注中。传入 verbose=True 可获取 Mealie 的完整响应，其中包括各字段的置信度。

上传的资源和营养信息可能已存储但不可见

食谱的 settings 对象控制 UI 的渲染内容。showAssets 和 showNutrition 控制是否显示资源卡片和营养信息卡片，因此，通过 upload_recipe_asset_file 上传的资源可能存在于 API 响应中，但仍不会显示在 Web UI 中。使用以下方式切换开关：

update_recipe(slug="...", settings={"showAssets": True})

Mealie 会根据家庭偏好设置（recipeShowAssets、recipeShowNutrition 等）初始化新食谱的设置，因此不同实例的默认值可能不同。请先检查，不要想当然。

只有传入的开关会被更改。该工具会读取食谱当前的设置并发送合并后的对象，因为 Mealie 无法可靠地保留 settings PATCH 中未提供的开关。

字段保留

更新购物清单项目时，无论是单项还是批量更新，都会先获取当前记录并保留省略的字段。你只需指定想要更改的字段：

# Only updates 'checked' field, preserves note, quantity, etc.
update_shopping_list_item(item_id="...", checked=True)

批量购物清单输入接受 snake_case 名称（例如 shopping_list_id）和 Mealie 的 camelCase 名称（例如 shoppingListId）。批量更新中互相冲突的别名和重复 ID 会在写入前被拒绝。

餐食计划验证与清除

餐食日期必须使用 YYYY-MM-DD，条目类型必须是 breakfast、lunch、dinner 或 side。创建时必须提供食谱或非空标题。批量餐食计划会在创建任何条目之前进行完整验证。

省略的更新字段将保持不变。若要移除现有的食谱链接，请使用 update_mealplan(entry_id="...", clear_recipe=True, title="Leftovers")。不要将 clear_recipe 与替换用的 recipe_id 一起使用。

从部分完成的写入中恢复

创建或填充食谱以及批量创建餐食计划需要多个 API 请求，并非原子操作。如果后续请求失败，工具错误会提供恢复信息，指出已完成的操作。请检查这些信息和 Mealie 当前状态，而不要盲目重试整个操作。失败或超时的请求可能已在远程端完成。

支持与贡献

• 查看更新日志，了解更改和迁移说明。
• 查阅使用指南和 Mealie 文档。
• 通过 GitHub issues 报告问题。
• 提交拉取请求时，请遵循开发工作流，并为行为更改添加 测试。

许可证与致谢

本项目采用 MIT License 许可。

• Mealie - 食谱管理系统
• Python MCP SDK - SDK 和 内置的 FastMCP 服务
• Model Context Protocol - 协议文档
• Claude Desktop