mealie-mcp-server

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

功能特性

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

• 基于食材的食谱发现 — find_recipes_for_ingredients 将人类可读的食材名称（绝不是 Mealie 食物 UUID）解析为 Mealie 的食物分类，并通过 Mealie 的 Recipe Finder 查找匹配的食谱；当没有精确的食物匹配时，回退到常规食谱搜索 — 适用于“我能用 X 做什么”式的发现，包括 Mealie 不认识的食材名称（调用 LLM 会用替代词扩大搜索范围；MCP 本身从不猜测替代词）。参见工作流中的 按食材查找食谱。

• 食谱分类与标签分配 — 以合并/替换语义为现有食谱分配分类和标签，支持名称/slug/ID 解析，并可选择自动创建缺失值，而不会干扰食材、说明、营养或任何其他食谱字段。可通过 patch_recipe、update_recipe_taxonomy 和 update_recipe_taxonomy_batch 使用。参见工作流中的 分配分类与标签。

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

• 购物清单 — 清单和项目的完整 CRUD、批量操作以及食谱到清单的集成。

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

• 食物 — 食物分类（可复用的结构化食材实体）的完整 CRUD，包括别名管理和食物标签分配。参见工作流中的 解析或创建食物。

• 结构化食材写入 — update_recipe_ingredients 使用已解析的食物/单位引用替换食谱的完整结构化食材集合，而不干扰任何其他食谱字段。参见工作流中的 更新结构化食谱食材。

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

• 食谱分类馈送 — get_recipes_for_classification 是一个紧凑、分页、只读的馈送，专为 AI 驱动的分类/标签分配而构建。它通过使用廉价的列表端点进行过滤，仅对匹配项使用与上述相同的有界并发获取来获取完整详情，并使用在并发分类编辑中保持稳定的游标进行分页，从而避免批量/详情工具在大型食谱集上可能遇到的超时。参见工作流中的 食谱分类工作流。

• 除 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 覆盖 — 每个工具映射到其底层 Mealie API 端点。

• 工作流 — 针对更复杂工具的使用指南和示例负载：食材发现、分类分配、食物、结构化食材写入以及食谱分类馈送。

• 架构 — 面向贡献者的内部设计说明：有界并发原理、分页/游标设计以及已知的 Mealie API 怪癖。

贡献者

我非常期待您的参与！请阅读 贡献指南 开始。

想出现在贡献者列表中吗？

从阅读 贡献指南 开始

开发

要求

• Node.js >= 22

• Yarn（通过 Corepack：corepack enable）

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

测试

yarn test

类型检查

yarn typecheck

构建

yarn build

代码检查

yarn lint

可用工具（共 53 个）

食谱（16 个）

get_recipes, find_recipes_for_ingredients, get_recipe_detailed, get_recipe_concise, get_recipes_batch, get_recipes_detailed_batch, get_recipes_for_classification, create_recipe, patch_recipe, update_recipe_ingredients, 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

食物（5 个）

get_foods, get_food, create_food, update_food, delete_food

许可证

MIT