使用说明

Mealie MCP服务器

一个模型上下文协议（MCP）服务器，允许LLM将食谱直接保存到您的米莉例子此服务器接受schema.org/Recipe格式的食谱，并自动处理转换和保存到Mealie。

特性

接受标准schema.org/Recipe格式的食谱
自动转换为Mealie的食谱格式
透明处理的两步API工作流程（创建+更新）
支持成分、说明、营养信息等
自动字段规范化（referenceId、显示字段等）
使用描述性消息进行正确的错误处理

当前限制

分类与标签：由于Mealie API的限制，类别和标记不会自动保存。它们必须在Mealie web UI中手动创建，然后才能分配给食谱。看类别_标签_模仿.md 了解详情。

安装

克隆此存储库：

cd mealie-mcp

安装依赖项：

npm install

构建项目：

npm run build

配置

创建名为的配置文件 .mealie-mcp.json 在项目目录中：

cp .mealie-mcp.json.example .mealie-mcp.json

然后编辑 .mealie-mcp.json 使用您的Mealie实例详细信息：

{
  "mealieUrl": "https://your-mealie-instance.com",
  "apiToken": "your-api-token-here"
}

获取Mealie API代币

登录您的Mealie实例
导航至 /user/profile/api-tokens
创建新的API令牌
将令牌复制到配置文件

备注：服务器正在查找 .mealie-mcp.json 启动时在当前工作目录中。

使用Claude Desktop

将此服务器添加到您的Claude Desktop配置文件中：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json 视窗: %APPDATA%\Claude\claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "mealie": {
      "command": "node",
      "args": ["/absolute/path/to/mealie-mcp/build/index.js"],
      "cwd": "/absolute/path/to/mealie-mcp"
    }
  }
}

替换 /absolute/path/to/mealie-mcp 与这个项目的实际路径。

重要：The cwd （当前工作目录）必须设置为项目目录，以便服务器可以找到 .mealie-mcp.json 配置文件。

用法示例

配置后，您可以要求Claude将食谱保存到Mealie：

示例1：简单食谱

Save this recipe to Mealie:

Chocolate Chip Cookies

Ingredients:
- 2 cups flour
- 1 cup butter
- 1 cup sugar
- 2 eggs
- 2 cups chocolate chips

Instructions:
1. Preheat oven to 350°F
2. Mix butter and sugar
3. Add eggs and flour
4. Fold in chocolate chips
5. Bake for 12 minutes

示例2：详细配方

Save this pasta recipe to Mealie:

Name: Classic Spaghetti Carbonara
Cuisine: Italian
Category: Main Course
Prep Time: 10 minutes
Cook Time: 20 minutes
Servings: 4

Ingredients:
- 400g spaghetti
- 200g guanciale or pancetta
- 4 egg yolks
- 100g Pecorino Romano cheese
- Black pepper
- Salt

Instructions:
1. Cook pasta in salted boiling water until al dente
2. Cut guanciale into small pieces and cook until crispy
3. Mix egg yolks with grated cheese
4. Combine hot pasta with guanciale
5. Remove from heat and mix in egg mixture
6. Season with black pepper and serve

Tags: italian, pasta, quick-meals

配方格式

MCP工具接受具有以下字段的schema.org/Recipe格式的配方：

必需

name：配方名称

可选的

description：配方说明
recipeYield：份数（例如“4份”）
totalTime：总时间（ISO 8601持续时间，例如“PT30M”）
prepTime：准备时间（ISO 8601持续时间）
cookTime：烹饪时间（ISO 8601持续时间）
recipeCategory：类别或类别数组⚠️ 当前未保存 （见限制）
recipeCuisine：菜肴类型
keywords：标签/关键字（字符串或数组）⚠️ 当前未保存 （见限制）
recipeIngredient：成分字符串数组
recipeInstructions：指令对象的字符串或数组
nutrition：带有营养信息的物体
image：图像URL或URL数组
url：原始源URL
aggregateRating：评级信息

发展

在开发模式下运行：

npm run dev

构建项目：

npm run build

项目结构

mealie-mcp/
├── src/
│   ├── index.ts                    # MCP server entry point
│   ├── config.ts                   # Configuration management
│   ├── types.ts                    # TypeScript interfaces
│   ├── converter.ts                # Schema.org to Mealie converter
│   ├── converter.test.ts           # Converter tests
│   ├── mealie-client.ts            # Mealie API client
│   └── mealie-client.test.ts       # Integration tests
├── build/                          # Compiled JavaScript
├── MEALIE_API_STRUCTURE.md         # API format documentation
├── CATEGORIES_TAGS_LIMITATION.md   # Categories/tags limitation details
├── package.json
├── tsconfig.json
└── README.md

故障排除

错误：找不到配置文件

确保 .mealie-mcp.json 存在于项目目录中
检查JSON是否有效
验证两者 mealieUrl 和 apiToken 存在
如果使用Claude Desktop，请确保 cwd 在配置中设置正确

错误：创建配方失败（401）

您的API令牌无效或已过期
在Mealie中生成新令牌 /user/profile/api-tokens

错误：创建配方失败（404）

检查你的 mealieUrl 是正确的
确保URL没有尾随斜线
验证您的Mealie实例是否可访问

配方已创建，但更新失败

配方是在Mealie中创建的，但详细信息未能保存
检查错误中提到的slug，必要时在Mealie中手动更新

未显示类别或标签

必须首先在Mealie中手动创建类别和标签
导航到“设置”→ Mealie实例中的类别/标签
创建要使用的类别/标签
看类别_标签_模仿.md 详情请见

运作原理

服务器自动处理整个工作流：

Schema.org输入：LLM以标准schema.org格式提供配方
转换：转换为Mealie的内部格式
创建: POST /api/recipes 仅使用配方名称→ 返回一个slug
规范化：自动添加所有必需的Mealie字段：
- 产生 referenceId 每种成分的UUID
- 集合 display, unit, food, isFood, disableAmount 领域
- 添加 title 和 ingredientReferences 根据指示
- 删除类别/标签（Mealie API限制）
更新: PATCH /api/recipes/{slug} 具有完整的配方数据

如果更新失败，食谱将仅以名称存在于Mealie中，并且可以手动编辑。

有关数据结构的详细信息，请参阅 MEALIE_API _结构.md.

文档

MEALIE_API _结构.md -详细解释Mealie的配方格式、数据工作流程和已知问题
类别_标签_模仿.md -为什么没有保存类别和标签，以及如何解决这个问题

测试

运行集成测试（需要 .mealie-mcp.json 配置）：

npm test

仅运行转换器测试：

npm test -- converter.test

许可证

ISC

贡献

欢迎问题和拉取请求！