Better Mealie MCP

---

基于 FastMCP 的 FastMCP from_openapi 构建：工具直接由 Mealie 的 OpenAPI 规范生成，因此服务始终与 Mealie 保持同步，无需手动维护。完整工具列表请参阅 TOOLS.md。

💬 可以用它做什么？

你说	会发生什么
“从这个 URL 添加一道鸡肉 Tikka Masala 食谱”	抓取并导入食谱
“用我储藏室里的食材能做什么？”	按你的食材搜索食谱
“为下周安排晚餐”	创建膳食计划条目
“为这些餐食创建购物清单”	生成汇总后的购物清单
“把我所有的汤都标记为‘冬季’”	批量更新食谱标签

🧙 安装向导

→ 打开安装向导

无需手写 JSON。向导会引导你完成每项选择，并根据你的组合生成可直接粘贴的配置：

• 安装方式 — Docker 镜像或从源代码安装。
• 客户端 — Claude Code、Claude Desktop、Cursor、VS Code、Gemini CLI 或 ChatGPT（向导了解各自的配置格式）。
• 连接方式 — stdio 或 HTTP，API 令牌或用户名/密码。
• 限制工具（可选）— 将 259 个工具精简为所需分组，让上下文更精简，或适配限制工具数量的客户端。从一个工具包（烹饪、膳食计划、分享与浏览、管理与用户）开始，也可单独选择分组；点击分组旁的 ⓘ 可查看其中的所有工具。所选内容会写入生成的配置中的 MEALIE_INCLUDE_TAGS。

🚀 设置

Docker（GHCR 镜像）：

docker pull ghcr.io/djwmarcx/better-mealie-mcp
docker run -i --rm \
  -e MEALIE_BASE_URL=http://host.docker.internal:9925 \
  -e MEALIE_API_TOKEN=... \
  ghcr.io/djwmarcx/better-mealie-mcp            # stdio; add `--http 8000` for HTTP

每次发布时都会发布镜像，标签为 <mealie-version> 和 latest。 在容器内，localhost 指向容器本身——请将 MEALIE_BASE_URL 指向 host.docker.internal（macOS/Windows）或主机的 LAN IP（Linux）。

从源代码安装：

git clone https://github.com/djwmarcx/better-mealie-mcp
cd better-mealie-mcp
uv sync                     # install deps
cp .env.example .env        # then edit .env with your Mealie URL + token

身份验证（在 .env 或环境变量中设置）：

变量	含义
MEALIE_BASE_URL	Mealie 基础 URL（默认 http://localhost:9925）
MEALIE_API_TOKEN	长期有效的 API 令牌（首选）——Mealie → 个人资料 → 管理 API 令牌
MEALIE_USERNAME / MEALIE_PASSWORD	替代方式：启动时登录以获取令牌
MEALIE_TIMEOUT	每次请求的超时时间，单位为秒（默认 60）
MEALIE_VERIFY_SSL	验证 TLS 证书；设为 false 可接受自签名证书（默认 true）
MCP_SERVER_NAME	向客户端公布的 MCP 名称（默认 Mealie）
MEALIE_INCLUDE_TAGS	仅公开这些 API 分组，以逗号分隔（例如 recipes,organizers,foods）。工具越少，上下文越精简，也适用于限制工具数量的客户端
MEALIE_EXCLUDE_TAGS	公开除这些分组以外的所有内容（例如 admin,households）
MEALIE_SLIM_SCHEMAS	精简冗余的架构信息——默认 true（参见下方模式）
MEALIE_SLIM_AGGRESSIVE	同时合并可空的 anyOf 联合类型——默认 false
MEALIE_VALIDATE_OUTPUT	输出每个工具的输出架构并验证结果——默认 false

分组是 API 路径的第一个部分（recipes、households、admin、 organizers、users、explore、foods、units 等）。未设置时 = 所有工具。 如果两者都设置，则 INCLUDE 优先。请参阅 TOOLS.md 了解当前 分组及其内容，或使用 设置向导进行选择——向导的 分组选择器（含 Cooking 或 Meal planning 等一键套装）会为你填写 MEALIE_INCLUDE_TAGS。

上下文大小（架构详情）

此服务公开的每个工具都会在每次请求中将其 JSON 架构发送给模型——在实际调用工具之前，这些“闲置上下文”纯属额外开销。 全部 259 个工具的完整架构约占 240k 个令牌，因此服务会对其进行精简。 提供三种预设模式（所有端点仍可调用——只有模型看到的架构详情会改变）：

模式	环境变量	闲置上下文	说明
精简 (默认)	(无——默认值)	约 61k tok	删除冗余的 title（FastAPI 会根据字段名称自动生成）和重复的 default，并省略输出/响应架构。不影响可调用能力。
最精简	MEALIE_SLIM_AGGRESSIVE=true	约 51k tok	包含精简模式的所有处理，并且将可空的 anyOf:[{X},{null}] 联合类型合并为 X（删除显式的“允许 null”提示）。
完整	MEALIE_SLIM_SCHEMAS=false MEALIE_VALIDATE_OUTPUT=true	约 240k tok	提供完整、未经精简的输入和输出架构，并在客户端验证结果。仅在客户端依赖结构化输出架构时使用。

每种模式都会保留模型正确调用工具所需的一切信息（format、真实的 description、必填字段）。结合上方的标签筛选功能还可进一步缩减—— 设置向导会显示你所选组合的实时令牌 估算。

▶️ 运行

uv run better-mealie-mcp             # stdio transport (for MCP clients)
uv run better-mealie-mcp --http 8000 # streamable-http on 127.0.0.1:8000
uv run server.py                     # same server, back-compat entry
fastmcp run fastmcp.json             # via FastMCP project config (stdio)
fastmcp run fastmcp-http.json        # via FastMCP project config (http)

在 --http 模式下，绑定地址由 MCP_HOST 指定（默认 127.0.0.1； Docker 镜像将其设为 0.0.0.0，以便端口映射 -p 生效）。

🧪 使用本地 Mealie（Docker）进行测试

docker run -d --name mealie -p 9925:9000 \
  -e ALLOW_SIGNUP=true -e BASE_URL=http://localhost:9925 -e TZ=UTC \
  ghcr.io/mealie-recipes/mealie:latest

默认管理员登录信息：[email protected] / MyPassword。

📝 备注

• 公开所有端点意味着会有大量工具，也会产生大量闲置上下文。 大多数 客户端都能正常处理。如果你的客户端限制工具数量，或你想精简上下文， 可通过 MEALIE_INCLUDE_TAGS / MEALIE_EXCLUDE_TAGS 精简工具集 （参见设置），也可以使用向导的分组选择器。

版本管理

此 MCP 的版本与其规范所针对的 Mealie 版本一致——MCP 3.20.1 ⇒ Mealie v3.20.1。服务会向客户端公布此版本，VERSIONS.md 列出了每个版本对应的 Mealie 版本和日期。

仅涉及 MCP 的更改（不影响 Mealie 版本的功能或修复）会作为同一 Mealie 版本的修订版发布：REVISION 计数器递增，发布版本和镜像标签会添加 -r<n> 后缀，例如 v3.20.1-r2（-r1 是基础版本，不带后缀）。Mealie 版本更新时，计数器会重置。:latest 始终指向最新构建。

openapi.json 是 Mealie 规范的随附副本。update-spec 工作流每天运行，并自动跟踪最新稳定版 Mealie（mealie:latest）：启动该镜像，从 /api/app/about 读取实际版本（MEALIE_VERSION），拉取 /openapi.json，重新生成 TOOLS.md 及其计数，并且——仅当规范确实发生更改时——更新版本并创建拉取请求（主分支受保护，因此所有更改都通过拉取请求合并）。该拉取请求合并后，release-on-spec 会创建一个发布版本（附带规范，并在说明中列出新增和移除的工具）。为确保规范未变化时运行确实不产生任何更改，会移除易变的服务器时钟默认值。

若要固定在某个版本，而不跟踪最新版本，请在工作流中将 MEALIE_TAG_DEFAULT 设为特定标签（例如 v3.20.1），或手动运行工作流并传入 mealie_tag 参数（latest、nightly 或任意标签）。

• 少数端点（list_auth_oauth*）在 Mealie 端未配置 OIDC 时会返回 500——这是 Mealie 的行为，并非服务的问题。

📄 许可证

MIT 许可证