内容
<div align="center">
# 更佳的Mealie MCP
<p>
<img src="https://img.shields.io/badge/259-blue" alt="259 tools">
<a href="https://github.com/jlowin/fastmcp"><img src="https://img.shields.io/badge/Built%20with-FastMCP-purple" alt="Built with FastMCP"></a>
<img src="https://img.shields.io/badge/python-3.14%2B-blue" alt="Python 3.14+">
<img src="https://img.shields.io/badge/Mealie-v3.20.1-brightgreen" alt="Mealie v3.20.1">
</p>
<p>
<a href="https://github.com/djwmarcx/better-mealie-mcp/actions/workflows/pages.yml"><img src="https://img.shields.io/github/actions/workflow/status/djwmarcx/better-mealie-mcp/pages.yml?branch=main&label=设置向导" alt="设置向导部署"></a>
<a href="https://github.com/djwmarcx/better-mealie-mcp/actions/workflows/update-spec.yml"><img src="https://img.shields.io/github/actions/workflow/status/djwmarcx/better-mealie-mcp/update-spec.yml?label=规格同步" alt="规格同步"></a>
<a href="https://github.com/djwmarcx/better-mealie-mcp/releases"><img src="https://img.shields.io/github/v/release/djwmarcx/better-mealie-mcp?sort=semver&label=发布版本" alt="最新发布版本"></a>
<a href="https://github.com/djwmarcx/better-mealie-mcp/blob/main/.github/renovate.json5"><img src="https://img.shields.io/badge/Renovate-enabled-brightgreen?logo=renovatebot&logoColor=white" alt="Renovate enabled"></a>
</p>
<em>一个MCP服务器，暴露了<strong>所有</strong> <a href="https://mealie.io">Mealie</a> API端点 —<br>
所有250多个操作，无一例外。您可以从任何AI助手以自然语言管理食谱、餐饮计划、购物清单、<br>
家庭等。</em>
</div>
---
使用 [FastMCP](https://github.com/jlowin/fastmcp) `from_openapi` 构建：工具直接从Mealie的OpenAPI规格生成，因此服务器始终与Mealie同步，并且没有任何手动维护。有关完整的工具列表，请参见 [TOOLS.md](./TOOLS.md)。
## 💬 您可以用它做什么？
| 您说的话 | 会发生什么 |
|---------|--------------|
| *"添加一个从这个URL获取的鸡肉提卡马萨拉食谱"* | 爬取并导入食谱 |
| *"我可以用我的食品柜里的食材做什么？"* | 按食材搜索食谱 |
| *"计划下周的晚餐"* | 创建餐饮计划条目 |
| *"为这些餐生成一个购物清单"* | 生成一个综合购物清单 |
| *"将我所有的汤标记为'冬季'"* | 批量更新食谱标签 |
## 🧙 设置向导
<h3 align="center">
[**→ 打开设置向导**](https://djwmarcx.github.io/better-mealie-mcp/)
</h3>
<p align="center">
<a href="https://djwmarcx.github.io/better-mealie-mcp/">
<img src="public/options-tree.png" alt="设置选项 — 安装、客户端、传输、身份验证" width="900">
</a>
</p>
## 🚀 设置
**Docker（GHCR镜像）：**
```bash
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 # 标准输入输出；添加 `--http 8000` 以启用HTTP
```
镜像在每个发布版本中发布，标记为 `<mealie-version>` 和 `latest`。在容器内，`localhost` 是容器 — 将 `MEALIE_BASE_URL` 指向 `host.docker.internal`（macOS/Windows）或主机的LAN IP（Linux）。
**从源码：**
```bash
git clone https://github.com/djwmarcx/better-mealie-mcp
cd better-mealie-mcp
uv sync # 安装依赖
cp .env.example .env # 然后使用您的Mealie URL + token 编辑 .env
```
身份验证（在 `.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`） |
## ▶️ 运行
```bash
uv run better-mealie-mcp # 标准输入输出传输（适用于MCP客户端）
uv run better-mealie-mcp --http 8000 # 流式HTTP在 127.0.0.1:8000
uv run server.py # 相同的服务器，兼容性入口
fastmcp run fastmcp.json # 通过FastMCP项目配置（标准输入输出）
fastmcp run fastmcp-http.json # 通过FastMCP项目配置（HTTP）
```
在 `--http` 模式下，绑定地址来自 `MCP_HOST`（默认为 `127.0.0.1`；Docker镜像设置为 `0.0.0.0`，因此 `-p` 端口映射有效）。
## 🧪 在本地Mealie（Docker）上测试
```bash
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
```
默认管理员登录： `changeme@example.com` / `MyPassword`。
## 📝 备注
- **暴露所有端点是一大堆工具 — 很多空闲上下文。** 大多数客户端都能处理它，但如果您的客户端限制工具数量或您想要更精简的上下文，请使用FastMCP的工具搜索或按标签过滤 — 请求并可以配置。
### 版本控制
**此MCP的版本镜像了它所针对的Mealie版本** — MCP `3.20.1` ⇒ Mealie `v3.20.1`。服务器向客户端广播它， [VERSIONS.md](./VERSIONS.md) 将每个发布版本映射到其Mealie版本和日期。
`openapi.json` 是Mealie规格的转售副本。 [`update-spec`](.github/workflows/update-spec.yml) 工作流每天运行并 **自动跟踪最新的稳定Mealie发布版本** （`mealie:latest`）：它启动该镜像，读取 `/api/app/about` 中的实际版本（ [`MEALIE_VERSION`](./MEALIE_VERSION)），拉取 `/openapi.json`，重新生成 [TOOLS.md](./TOOLS.md) + 计数，并且 **仅当规格实际更改时** — 版本升级并 **打开拉取请求** （主分支受保护，因此每个更改都通过PR落地）。当该PR合并时， [`release-on-spec`](.github/workflows/release-on-spec.yml) 创建一个 [发布版本](https://github.com/djwmarcx/better-mealie-mcp/releases) （附带规格，列出新增/删除的工具）。服务器时钟的易变默认值被剥离，因此不变的运行是真正的无操作。
要冻结在一个发布版本而不是跟踪最新版本，请在工作流中将 `MEALIE_TAG_DEFAULT` 设置为特定标签（例如 `v3.20.1`），或使用 `mealie_tag` 输入手动运行（ `latest`， `nightly` 或任何标签）。
- 少数端点（ `list_auth_oauth*` ）返回 500，除非在Mealie一侧配置了OIDC — 这是Mealie的行为，而不是服务器。
