mealie-mcp-server

一个用于 Mealie 食谱管理的 Model Context Protocol (MCP) 服务器。为 AI 助手提供 46 个工具和 1 个提示词，用于搜索、创建和管理食谱、膳食计划、购物清单、分类和标签。

功能特性

• 食谱管理 — 搜索、创建、修补、复制和删除食谱。以有界并发批量获取多个食谱。

• 基于食材的食谱发现 — find_recipes_for_ingredients 将人类可读的食材名称（绝不是 Mealie 食物 UUID）解析到 Mealie 的食物分类体系，并通过 Mealie 的 Recipe Finder 查找匹配的食谱；当没有精确的食物匹配时，回退到常规食谱搜索——适用于"我可以用 X 做什么"这类发现场景，包括 Mealie 不以其确切名称识别的食材（调用方 LLM 会用替代词扩大搜索范围；MCP 本身从不猜测替代词）。

• 食谱分类与标签分配 — 为现有食谱分配分类和标签，支持合并/替换语义、名称/别名/ID 解析，以及可选地自动创建缺失值，且不会干扰食材、步骤、营养信息或任何其他食谱字段。可通过 patch_recipe、update_recipe_taxonomy 和 update_recipe_taxonomy_batch 使用。

• 膳食计划 — 查看、创建和批量创建膳食计划。复合工具通过并发批量请求获取带有内嵌食谱详情（包括营养信息）的膳食计划，消除了 N+1 查询问题。

• 购物清单 — 清单和条目的完整增删改查、批量操作，以及食谱到清单的集成。

• 分类与标签 — 用于组织食谱的完整增删改查，包括空分类/标签检测。

• 批量与复合工具 — get_recipes_batch 和 get_recipes_detailed_batch 用于有界并发食谱查找，get_mealplan_with_recipes 用于获取带有内嵌食谱数据和客户端日期过滤的膳食计划，update_recipe_taxonomy_batch 用于跨多个食谱的有界并发分类/标签更新。

• 除 SDK 外零运行时依赖 — 使用原生 fetch，不依赖 axios 或 httpx。

Related MCP server: mcp-mealie

环境要求

• Node.js >= 22

• 一个运行中的 Mealie 实例，并带有 API 密钥

安装

快速开始（npx）

MEALIE_BASE_URL=https://your-mealie-instance.com \
MEALIE_API_KEY=your-api-key \
npx mealie-mcp-server

opencode 配置

添加到你的 opencode.json：

{
  "mcp": {
    "mealie-mcp-server": {
      "type": "local",
      "command": ["npx", "mealie-mcp-server"],
      "enabled": true,
      "environment": {
        "MEALIE_BASE_URL": "https://your-mealie-instance.com",
        "MEALIE_API_KEY": "your-api-key"
      }
    }
  }
}

Docker

在容器中运行 MCP 服务器：

docker run -d \
  --name mealie-mcp-server \
  -e MEALIE_BASE_URL=https://your-mealie-instance.com \
  -e MEALIE_API_KEY=your-api-key \
  ghcr.io/timo-reymann/mealie-mcp-server:main

或使用 Docker Compose：

version: '3.8'
services:
  mealie-mcp-server:
    image: ghcr.io/timo-reymann/mealie-mcp-server:main
    environment:
      MEALIE_BASE_URL: https://your-mealie-instance.com
      MEALIE_API_KEY: your-api-key
    restart: unless-stopped

本地开发

git clone https://github.com/timo-reymann/mealie-mcp-server.git
cd mealie-mcp-server
corepack enable
yarn install
cp .env.template .env
# Edit .env with your MEALIE_BASE_URL and MEALIE_API_KEY
yarn dev

确保在环境中或 opencode 配置中设置了 MEALIE_BASE_URL 和 MEALIE_API_KEY。

文档

参见 API 覆盖，了解全部 46 个工具及其对应的 Mealie API 端点的详细说明。

按食材查找食谱

find_recipes_for_ingredients 让 AI 助手能够从人类可读的食材名称（例如 "branzino"、"chicken thighs"）发现食谱，而无需知道 Mealie 内部的食物 UUID。MCP 处理所有 Mealie 特有的机制——将名称解析为 Mealie Food 对象、调用 Mealie 的 Recipe Finder（GET /api/recipes/suggestions）或常规食谱搜索——而食材替换/扩展（例如决定"海鲈鱼"或"整鱼"是"branzino"的合理替代）则留给调用方 LLM 处理。

食材解析，按顺序，针对每种食材：

1. 在食物名称上进行精确的不区分大小写匹配。

2. 在食物的复数名称或其别名之一上进行精确的不区分大小写匹配（与 Category/Tag 不同，Mealie 的 Food 对象没有 slug 字段）。

3. 如果以上均未匹配，则使用 Mealie 食物搜索中的唯一结果。

如果某个名称匹配多个食物且没有唯一候选（例如 "fish"），则会以 ambiguous 状态连同候选名称一起报告——该工具从不猜测。

搜索策略，取决于解析结果：

{ "ingredients": ["salmon"], "categories": ["Dinner"] }

将 salmon 解析为 Food，然后使用 Mealie 的 Recipe Finder——食谱按使用了多少种已解析食材以及缺少多少种其他食材来排序。matchSource: "suggestions"。

{ "ingredients": ["branzino"] }

branzino 没有 Food 匹配 → 回退到 Mealie 的常规食谱搜索（匹配食谱名称、描述和食材文本）。如果也没有找到有用的结果，unresolvedIngredients 会报告它，以便 LLM 用更宽泛的术语（如 "sea bass" 或 "whole fish"）重试。matchSource: "text-search"（如果没有任何结果则为 "none"）。

{ "ingredients": ["chicken thighs", "broccoli"], "requireAllIngredients": true }

当有两个或更多已解析食材且 requireAllIngredients: true 时，使用 Mealie 的常规食谱搜索并带严格的食物 AND 过滤器，而不是 Finder。matchSource: "food-filter"。

categories/tags 的解析方式与 get_recipes 相同——按名称、别名或 ID，不区分大小写——在任何搜索运行之前完成，并以规范 ID 的形式发送给 Mealie，用于 food-filter 和 text-search 路径；对于 Recipe Finder 路径（其本身没有分类过滤器），则应用于返回的候选结果。

每个返回的食谱都包含 name、slug、description、categories、tags、totalTime、匹配了哪些请求的食材，以及（对于 Recipe Finder 结果）缺少哪些其他食材——足以决定哪些值得用 get_recipe_detailed 或 get_recipes_batch 进一步查看，而无需对每个候选进行额外的往返请求。

分配分类与标签

分类是宽泛的分组（例如 Dinner、Dessert），用于组织食谱书；而标签是更具体的自由格式属性（例如 Quick、Dairy-Free）。两者都可以通过 update_recipe_taxonomy（一个专注于此单一任务的工具）或 patch_recipe（除了现有字段外，还接受 categories/tags/taxonomyMode/createMissing，因此可以在一次调用中同时发送名称/描述编辑和分类变更）分配给现有食谱。

categories/tags 中的每个值都可以是名称、别名或 ID——与现有分类/标签的匹配在名称和别名上不区分大小写。结果会自动去重。

添加一个分类和一些标签，保留食谱已有的其他所有内容（mode: "merge"，默认值）：

{
  "slug": "chicken-shawarma",
  "categories": ["Dinner"],
  "tags": ["Dairy-Free", "Quick"],
  "mode": "merge",
  "createMissing": false
}

直接替换标签列表，丢弃之前的所有标签：

{
  "slug": "chicken-shawarma",
  "tags": ["Weeknight", "Middle Eastern"],
  "mode": "replace",
  "createMissing": true
}

上面的 createMissing: true 表示如果 Weeknight 和 Middle Eastern 尚不存在，则会自动创建。

通过传入显式空数组并配合 mode: "replace" 来清除食谱的所有分类——省略 categories 则会保持其不变：

{
  "slug": "chicken-shawarma",
  "categories": [],
  "mode": "replace"
}

使用 update_recipe_taxonomy_batch 一次更新多个食谱。 每个条目独立处理（有界并发），响应中包含每个食谱的成功或错误结果，因此一个错误的别名不会导致整个批次失败：

{
  "updates": [
    { "slug": "chicken-shawarma", "categories": ["Dinner"], "mode": "merge" },
    { "slug": "banana-bread", "tags": ["Dessert", "Baking"], "mode": "merge" },
    { "slug": "does-not-exist", "categories": ["Dinner"], "mode": "merge" }
  ]
}

两个工具都返回食谱的 id/slug，以及每个集合在更新后的 final 列表和哪些条目被 added、removed 或 created——有助于确认具体发生了什么变化。

贡献

欢迎你的参与！请阅读贡献指南开始。

开发

环境要求

• Node.js >= 22

• Yarn（通过 Corepack：corepack enable）

• 一个用于集成测试的 Mealie 实例（或模拟 fetch 层）

测试

yarn test

类型检查

yarn typecheck

构建

yarn build

代码检查

yarn lint

可用工具（共 46 个）

食谱（14 个）

get_recipes, find_recipes_for_ingredients, get_recipe_detailed, get_recipe_concise, get_recipes_batch, get_recipes_detailed_batch, create_recipe, patch_recipe, update_recipe_taxonomy, update_recipe_taxonomy_batch, duplicate_recipe, mark_recipe_last_made, set_recipe_image_from_url, delete_recipe

膳食计划（5 个）

get_all_mealplans, get_mealplan_with_recipes, create_mealplan, create_mealplan_bulk, get_todays_mealplan

分类（7 个）

get_categories, get_empty_categories, create_category, get_category, get_category_by_slug, update_category, delete_category

标签 (7)

get_tags, get_empty_tags, create_tag, get_tag, get_tag_by_slug, update_tag, delete_tag

购物清单 (13)

get_shopping_lists, create_shopping_list, get_shopping_list, update_shopping_list, delete_shopping_list, add_recipe_to_shopping_list, remove_recipe_from_shopping_list, get_shopping_list_items, create_shopping_list_item, create_shopping_list_items_bulk, update_shopping_list_item, delete_shopping_list_item, delete_shopping_list_items_bulk

许可证

MIT