Mealie MCP Server

mealie-mcp

一个用于 Mealie 的模型上下文协议（MCP）服务。Mealie 是一款可自托管的食谱管理器和膳食规划工具。

让 Claude Code、Claude Desktop 或 Codex 等 MCP 客户端能够使用你的食谱收藏：搜索并阅读食谱及其食材和步骤，从网站导入新食谱，整理标签和类别，规划膳食，根据计划生成购物清单，并记录实际烹饪的内容。

五十三个工具是上限，而非最低数量：设置 MEALIE_ALLOW_TOOLS=essential 只会注册经过精选的八个工具。模型从八个工具中挑选合适工具，远比从五十四个中挑选可靠——请参阅选择加载哪些工具。

Mealie 的 REST API 在 175 个路径上提供 259 个操作。本服务提供 54 个工具，经过精心挑选，让常见任务只需一次调用即可完成，同时完全无法触及危险功能。已针对 Mealie v3.28.0 验证；每个请求格式的权威依据是运行中实例的 GET /openapi.json，而不是在多个地方已经过时的已发布文档。

与众不同之处

从 259 个 API 操作中精选 53 个工具。 Mealie 的 REST API 远超模型应该接触的范围；这里的工具涵盖常见任务，一次调用即可完成——搜索、阅读和导入食谱，整理标签和类别，规划膳食，生成购物清单，以及管理食谱集和评分。

update_recipe 使用 PATCH，而非 PUT。 Mealie 的替换路由会悄悄丢弃未发送的食谱字段；在这里，只有你指定的字段会发生更改。

危险功能完全无法触及。 没有管理路由、令牌签发、Webhook 或出站 HTTP 触发器，无论令牌允许执行什么操作都一样。

要求

• Node.js 22 或更高版本
• Mealie 实例，以及从 Settings → API Tokens 获取的 API 令牌

配置

变量	必填	说明
MEALIE_URL	是	基础 URL，例如 https://mealie.example.com
MEALIE_API_TOKEN	是	从 Settings → API Tokens 获取的令牌。它以创建令牌的用户身份运行。
MEALIE_READ_ONLY	否	仅当值为 true 时，才会注册 18 个只读工具
MEALIE_ACCEPT_LANGUAGE	否	例如 de-DE；本地化单位和标签名称
MEALIE_INSECURE_TLS	否	仅当值为 true 时，才接受自签名证书；仅对此连接生效
MEALIE_ALLOW_TOOLS	否	以逗号分隔的工具名称、list_* 前缀，或精选预设 essential
MEALIE_DENY_TOOLS	否	语法相同；从 MEALIE_ALLOW_TOOLS 留下的工具中移除
ELICITATION	否	false 会将审批对话框替换为两次调用令牌。不带前缀

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

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

选择要加载的工具

MEALIE_ALLOW_TOOLS 和 MEALIE_DENY_TOOLS 接受以逗号分隔的工具名称；末尾的 * 可匹配整个工具系列。essential 是包含以下 8 个工具的精选预设：search_recipes、get_recipe、import_recipe_from_url、create_recipe、get_todays_meals、create_mealplan_entry、list_shopping_lists、add_recipe_to_shopping_list。

MEALIE_ALLOW_TOOLS=essential
MEALIE_ALLOW_TOOLS=search_recipes,get_recipe,import_recipe_from_url
MEALIE_DENY_TOOLS=delete_*

如果某个条目未匹配任何工具，启动就会中止并指出该条目，因此拼写错误不会悄悄隐藏工具——没人会想到去环境变量中排查工具缺失的问题。经过筛选的工具不会被注册，因此它们既不会出现在 tools/list 中，也无法通过 tools/call 调用，效果与 MEALIE_READ_ONLY 下的写入工具完全相同。

如果你同时运行多个这类服务，另一个选择是 mcp-hub——它的 /hub 端点会用 6 个元工具替换所有服务的工具。

安装

Claude Code

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

Claude Desktop

同一条配置也适用于任何接受 JSON 配置的 MCP 客户端：

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

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 = "…"

MCP Inspector

交互式试用这些工具：

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

Docker

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

通过 mcp-hub

无法启动本地进程的客户端——ChatGPT connectors、网页端 Claude、Cursor、LibreChat——可通过 mcp-hub 访问 mealie-mcp：一个容器即可通过 Streamable HTTP 提供多个 stdio MCP 服务，并通过单一密码进行 OAuth 2.1 登录，还能为不支持 OAuth 的客户端提供长期有效的令牌。它的 /hub 端点会用 6 个元工具承载所有服务，因此一个连接器就能访问全部服务，无需在模型上下文中放入 N×工具架构；它还同时支持两种协议修订版本——本服务提出的问题会经由它传递给另一端的用户。

它的 /config/mcp.json 使用 Claude Code 的格式，因此配置条目就是你已有的那一条：

{
  "mcpServers": {
    "mealie": {
      "command": "npx",
      "args": ["-y", "@ni-c/mealie-mcp"],
      "env": { "MEALIE_ALLOW_TOOLS": "essential" },
      "denyTools": ["delete_*"]
    }
  }
}

其中的 allowTools 和 denyTools 是 hub 自身针对各服务的筛选器，与 env 中的 *_ALLOW_TOOLS 并不相同——两者的区别以及由此引发的误用，详见客户端指南。

工具

每个工具都会声明一个 outputSchema，并在文本块之外同时返回 structuredContent，因此客户端无需解析散文即可使用结果。 原先以一句话作答的九个工具——“已删除 ID 为 … 的食谱。”——现在也会返回字段。

大多数工具都会包含 untrusted: true 和 source: "mealie" 字段：食谱经常从任意网站抓取，评论则来自此实例的其他用户。其余十一个工具返回此服务收到的 ID；get_about 则返回版本字符串以及其认证账户的权限标志，这些都是模型应当据此采取行动的事实。

Mealie 的记录被描述为开放对象，包含此服务构建的顶层键。可自托管的 Mealie 可以是任意版本，而 SDK 会在每个结果发出前根据其架构进行验证——如果对象结构严格，某个版本新增的字段就会导致工具彻底失败。

食谱 — search_recipes、get_recipe、suggest_recipes、create_recipe、 update_recipe、parse_recipe_ingredients、duplicate_recipe、set_recipe_image、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

🔒 会通过 MCP 征询功能向用户请求确认——这是模型无法代为回答的对话框。如果客户端无法显示该对话框，则会改用两次调用的 confirm_token 方式。请参阅 向用户请求确认。

在所有地方，食谱都可以通过 slug 或 UUID 指定——Mealie 将标识符分为这两类，工具会解析收到的任一类型。

有意不提供的功能

/api/admin 下的所有内容（备份、恢复、维护、用户、群组和家庭管理、电子邮件、AI 提供商设置）、/api/users/api-tokens（可生成 API 凭据的工具会带来权限提升风险）、身份验证路由、用户 CRUD 和密码、Webhooks、事件通知和食谱操作（这三类操作都会从实例向外发起 HTTP 请求）、膳食计划规则、迁移、数据填充程序、邀请、批量导出和 ZIP 下载，以及资源上传。唯一开放的上传路由是通过 set_recipe_image 设置食谱封面图片。

PUT /api/recipes/{slug} 也不开放：它会替换包含 33 个字段的整个食谱对象，因此通过它进行部分更新会悄无声息地丢弃食材、步骤和标签。update_recipe 使用 PATCH。

安全性

• 实例内容是不可信输入。 食谱通常从任意网站抓取，评论也来自其他用户，因此，所有可能包含实例内容的工具结果都会加上明确标记，告知模型应将其视为数据。导入后这一点依然重要：文本会保留在数据库中，并通过 get_recipe 返回。
• 导入工具让 Mealie 获取内容，而非由此服务获取。 URL 仅允许使用 http/https，并会拒绝环回地址和链路本地地址，包括云元数据端点及解析到这些地址的主机名。地址会以数值方式比较，因此像 [::ffff:169.254.169.254] 这样的 IPv4 映射字面地址也会被拦截；主机名也会经过解析——但只能尽力而为，因为在此处无法解析的名称仍会被传递。自 0.1.2 起，私有局域网地址会被传递，但 Mealie 会自行拒绝这些地址，因此此类导入会在那里失败，而非在此处失败。有关此检查未覆盖的内容，请参阅 SECURITY.md，其中包括 import_recipe_from_html_or_json。
• 确认提示不会引用上游文本——仅包含 ID、计数和标志。
• 响应大小有限制：结果过大时会删除完整条目，而不会截断 JSON 字符串；响应正文的读取量绝不会超过 8 MB。
• 拒绝重定向，以免令牌被重新发送到其他主机。

有关信任模型及漏洞报告方式，请参阅 SECURITY.md。

文档

完整指南、工具参考和安全说明请见 mealie-mcp.ni-c.de（源文件位于 docs/）。

开发

npm install && npm test && npm run build

npm run test:integration 会在 Docker 中对一个临时 Mealie 实例运行目录中的所有工具；如何启动该实例，请参阅 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 是否匹配，通过带来源证明的 Trusted Publishing（OIDC——不存在可泄露的 npm 令牌）发布到 npm，将版本同步到 server.json 中的两个 package 条目，发布到 MCP registry，并根据变更日志部分创建 GitHub release。ci.yml 会并行将多架构容器镜像推送到 GHCR。

贡献

欢迎提交问题、参与讨论和发起拉取请求——请参阅 CONTRIBUTING.md。如需报告漏洞，请使用 私密报告渠道，而非公开问题；相关政策见 SECURITY.md。

许可证

MIT © Willi Thiel