mealie-mcp

一个面向Mealie（自托管食谱管理器与膳食规划器）的模型上下文协议服务器。

它为模型提供经过筛选的 Mealie 实例视图：搜索和读取食谱及其配料与步骤，从网站导入新食谱，整理标签和分类，规划膳食，根据规划生成购物清单，以及记录实际烹饪内容。

📖 完整文档请访问 mealie-mcp.ni-c.de

Mealie 的 REST API 在 175 个路径上共有 259 个操作。此服务器暴露了 52 个工具，选择方式使得常见任务只需一次调用，而危险区域完全不可达。已验证兼容 Mealie v3.22.0；每个请求形态的最终依据是运行中实例的 GET /openapi.json，而非已发布的文档，后者在多个地方已过时。

要求

• Node.js 22 或更高版本

• 一个 Mealie 实例以及从 设置 → API 令牌 获取的 API 令牌

Related MCP server: Blender Open MCP

配置

两个布尔值均与字面字符串 true 进行比较，因此拼写错误会使它们保持 关闭 状态——请检查 stderr 上的启动行，其中会报告生效的模式。

一旦读取令牌，它将从进程环境中移除，因此子进程无法从 /proc/<pid>/environ 中获取它。

安装

Claude Desktop，或任何接受 JSON 配置的 MCP 客户端：

{
  "mcpServers": {
    "mealie": {
      "command": "npx",
      "args": ["-y", "@ni-c/mealie-mcp"],
      "env": {
        "MEALIE_URL": "https://mealie.example.com",
        "MEALIE_API_TOKEN": "…"
      }
    }
  }
}

claude mcp add mealie \
  -e MEALIE_URL=https://mealie.example.com \
  -e MEALIE_API_TOKEN=… \
  -- npx -y @ni-c/mealie-mcp

Codex（~/.codex/config.toml）：

[mcp_servers.mealie]
command = "npx"
args = ["-y", "@ni-c/mealie-mcp"]

[mcp_servers.mealie.env]
MEALIE_URL = "https://mealie.example.com"
MEALIE_API_TOKEN = "…"

或作为容器：

docker run --rm -i \
  -e MEALIE_URL=https://mealie.example.com \
  -e MEALIE_API_TOKEN=… \
  ghcr.io/ni-c/mealie-mcp

要交互式地试用工具：

npx @modelcontextprotocol/inspector npx -y @ni-c/mealie-mcp

工具

食谱 — search_recipes、get_recipe、suggest_recipes、create_recipe、update_recipe、duplicate_recipe、set_recipe_last_made、delete_recipe 🔒

导入 — preview_recipe_url（试运行，不保存任何内容）、import_recipe_from_url、import_recipe_from_html_or_json、import_recipe_from_image

整理 — list_organizers、create_organizer、update_organizer、delete_organizer 🔒 — 每个均接受 kind: tag | category | tool

配料 — list_foods、create_food、merge_foods 🔒、list_units、create_unit、merge_units 🔒、parse_ingredients

膳食计划 — list_mealplans、get_todays_meals、create_mealplan_entry、create_random_meal、update_mealplan_entry、delete_mealplan_entry 🔒

购物 — list_shopping_lists、get_shopping_list、create_shopping_list、delete_shopping_list 🔒、add_shopping_list_items、update_shopping_list_items、delete_shopping_list_items 🔒、add_recipe_to_shopping_list、remove_recipe_from_shopping_list

食谱集 — list_cookbooks、get_cookbook、create_cookbook、delete_cookbook 🔒

笔记与分享 — set_recipe_rating、add_recipe_comment、delete_recipe_comment 🔒、list_recipe_comments、list_recipe_timeline、create_timeline_event、list_share_tokens、create_share_token 🔒、delete_share_token

实例 — get_about

🔒 需要确认令牌：先调用一次以获取令牌，然后再次调用时带上令牌。

食谱可以在任何地方通过 slug 或 UUID 引用——Mealie 的标识符空间分为这两种，工具会解析它们接收到的任意一种。

故意未暴露的内容

/api/admin 下的所有内容（备份、恢复、维护、用户、组和家庭管理、电子邮件、AI 提供商设置）、/api/users/api-tokens（生成 API 凭据的工具属于权限提升面）、认证路由、用户 CRUD 和密码、Webhook、事件通知和食谱操作（三者都会触发从实例发出的 HTTP 请求）、膳食计划规则、迁移、种子数据、邀请、批量导出和 ZIP 下载，以及资产和图片上传。

PUT /api/recipes/{slug} 也未暴露：它会替换整个包含 33 个字段的食谱对象，因此通过它进行部分更新会静默丢弃配料、步骤和标签。update_recipe 使用 PATCH。

安全性

• 实例内容是不可信的输入。 食谱通常从任意网站抓取，评论来自其他用户，因此每个可能包含实例内容的工具结果都会以显式标记开头，告知模型将其视为数据。这在导入后也同样重要：文本保留在数据库中，并通过 get_recipe 返回。

• 导入工具让 Mealie 执行抓取，而非此服务器。 URL 仅限于公共 http/https 地址；回环地址、私有范围地址、链路本地地址以及 .lan/.internal/.local 主机均被拒绝。

• 确认提示不会引用上游文本——仅包含 ID、计数和标志。

• 响应有边界限制：过大的结果会丢弃整个条目，而不是在 JSON 字符串中间截断，并且响应体永远不会读取超过 8 MB。

• 拒绝重定向，以防令牌被重新发送到其他主机。

有关信任模型以及如何报告漏洞，请参见 SECURITY.md。

开发

npm install && npm test && npm run build

scripts/verify-live.mjs 会针对一个 可丢弃的 Mealie 实例执行所有 52 个工具；设置实例的说明在 CONTRIBUTING.md 中。

架构图和社交卡片由 npm run assets 从 docs/assets/architecture.source.svg 和 docs/assets/og.json 生成；如果渲染后的副本被手动编辑，CI 会失败。

发布

一切由标签驱动；无需手动发布步骤。

1. 将 CHANGELOG.md 中的 [Unreleased] 部分移至新版本并注明日期。发布工作流会使用 awk 提取该部分，因此 ## [x.y.z] 标题格式很重要。

2. 更新 package.json 中的 version。

3. 执行 npm run lint && npm run build && npm run test:coverage。

4. 提交，然后创建一个 签名并注释的 标签：

   git tag -s v0.1.1 -m "v0.1.1"
   git push origin main v0.1.1

随后 release.yml 会验证标签是否与 package.json 匹配，通过 受信任发布（OIDC——不存在可泄露的 npm 令牌）并附带来源证明地将包发布到 npm，将版本同步到 server.json 的两个包条目中，发布到 MCP 注册表，并根据 changelog 部分创建 GitHub 发布。ci.yml 会并行地将多架构容器镜像推送到 GHCR。

许可证

MIT