Openfoodfacts MCP Server

OpenFoodFacts MCP服务器

模型上下文协议（MCP）服务器，将OpenFoodFacts API数据直接集成到人工智能模型中，实现有关食品、营养事实和成分的自然语言查询。

特性

• 产品搜索：按名称、品牌或类别搜索食品
• 条形码查找：使用条形码/EAN码获取详细的产品信息
• 营养分析：获取全面的营养事实和评分
• 产品比较：并排比较多个产品
• 过敏原信息：获取详细的过敏原和成分信息
• 营养过滤：按特定营养标准搜索产品
• 类别和品牌浏览：按类别或品牌浏览产品

安装

# Clone the repository
git clone https://github.com/yourusername/openfoodfacts-mcp-server.git
cd openfoodfacts-mcp-server

# Install dependencies
npm install

# Build the project
npm run build

# Start the server
npm start

发展

# Run in development mode with auto-reload
npm run dev

# Watch for changes
npm run watch

# Lint code
npm run lint

# Run tests
npm run test

可用工具

1.搜索产品

按名称、品牌或类别搜索食品。

参数：

• query （必填）：搜索查询字符串
• page （可选）：分页页码（默认值：1）
• page_size （可选）：每页结果（默认值：20，最大值：100）
• sort_by （可选）：按流行度、product_name、created_t或last_modified_t排序

示例用法：

Search for "chocolate chip cookies"

2.get_product_by_barcode

使用条形码/EAN获取详细的产品信息。

参数：

• barcode （必填）：产品条形码/EAN码

示例用法：

Get product information for barcode 3017620422003

3.按类别获取产品

浏览特定类别中的产品。

参数：

• category （必填）：类别名称（例如，“早餐麦片”、“酸奶”）
• page （可选）：分页页码
• page_size （可选）：每页结果

示例用法：

Show me yogurt products

4.获得产品_品牌

浏览特定品牌的产品。

参数：

• brand （必填）：品牌名称（例如“雀巢”、“可口可乐”）
• page （可选）：分页页码
• page_size （可选）：每页结果

示例用法：

Show me Nestlé products

5.获取营养信息

获取产品的详细营养信息。

参数：

• barcode （必填）：产品条形码/EAN

示例用法：

Get nutrition facts for barcode 3017620422003

6.比较产品

比较多种产品之间的营养成分。

参数：

• barcodes （必填）：2-5个产品条形码阵列

示例用法：

Compare nutrition between products with barcodes 3017620422003 and 8712566072576

7.获取过敏信息

获取产品的过敏原和成分信息。

参数：

• barcode （必填）：产品条形码/EAN

示例用法：

Get allergen information for barcode 3017620422003

8.搜索_营养素

根据营养标准搜索产品。

参数：

• max_fat （可选）：每100克的最大脂肪含量
• max_sugar （可选）：每100克的最大含糖量
• max_salt （可选）：每100克的最大含盐量
• min_fiber （可选）：每100克的最低纤维含量
• min_protein （可选）：每100克最低蛋白质含量
• nutriscore_grade （可选）：营养评分等级（A、B、C、D、E）
• page （可选）：分页页码
• page_size （可选）：每页结果

示例用法：

Find products with less than 5g sugar per 100g and Nutri-Score grade A

数据源

此服务器使用 OpenFoodFacts API提供：

• 来自全球200多万种食品的产品信息
• 营养事实和评分（营养评分、NOVA、生态评分）
• 成分清单和过敏原信息
• 产品图片和包装细节
• 来自全球社区的贡献者验证数据

自然语言示例

一旦与人工智能模型集成，用户可以提出以下问题：

• “条形码为3017620422003的产品的营养成分是什么？”
• “给我找低糖早餐麦片”
• “可口可乐和百事可乐的营养比较”
• “给我看看Alpro品牌的纯素产品”
• “本产品含有哪些过敏原？”（带条形码）
• “寻找高蛋白、低脂肪含量的产品”
• “Nutella的成分是什么？”

配置

服务器使用位于的OpenFoodFacts公共API https://world.openfoodfacts.org.不需要API密钥，但请遵守费率限制。

错误处理

该服务器包括全面的错误处理功能，用于：

• 条形码或产品代码无效
• 网络连接问题
• API速率限制
• 搜索参数无效
• 缺少产品数据

贡献

1. 分叉存储库
2. 创建要素分支(git checkout -b feature/amazing-feature)
3. 提交您的更改(git commit -m 'Add some amazing feature')
4. 推到分支(git push origin feature/amazing-feature)
5. 打开拉取请求

许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

MCP集成

添加到Claude桌面

要将此服务器与Claude Desktop一起使用，请将以下内容添加到MCP配置文件中：

macOS： ~/Library/Application Support/Claude/claude_desktop_config.json 窗户： %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "openfoodfacts": {
      "command": "node",
      "args": ["/path/to/openfoodfacts-mcp-server/dist/index.js"],
      "env": {}
    }
  }
}

与其他MCP客户端一起使用

通过运行以下命令，服务器可以与任何兼容MCP的客户端一起使用：

npx openfoodfacts-mcp-server

API响应格式

产品摘要格式

{
  "barcode": "3017620422003",
  "name": "Nutella",
  "brands": "Ferrero",
  "categories": "Sweet spreads",
  "nutriscore_grade": "E",
  "nova_group": 4,
  "basic_nutrition": {
    "energy_kcal_100g": 539,
    "fat_100g": 30.9,
    "sugars_100g": 56.3,
    "salt_100g": 0.107,
    "proteins_100g": 6.3
  }
}

详细产品格式

{
  "barcode": "3017620422003",
  "name": "Nutella",
  "brands": "Ferrero",
  "categories": "Sweet spreads, Cocoa and hazelnuts spreads",
  "nutriscore_grade": "E",
  "nova_group": 4,
  "ecoscore_grade": "D",
  "nutrition_per_100g": {
    "energy-kcal_100g": 539,
    "fat_100g": 30.9,
    "saturated-fat_100g": 10.6,
    "sugars_100g": 56.3,
    "salt_100g": 0.107,
    "fiber_100g": 0,
    "proteins_100g": 6.3,
    "carbohydrates_100g": 57.5
  },
  "ingredients": "Sugar, palm oil, hazelnuts, skimmed milk powder...",
  "allergens": "Milk, nuts",
  "image_url": "https://static.openfoodfacts.org/images/products/301/762/042/2003/front_en.jpg"
}

营养评分解释

营养评分

• A.：最佳营养品质（深绿色）
• B：营养质量好（浅绿色）
• C：营养质量一般（黄色）
• D：营养质量差（橙色）
• E：营养质量最差（红色）

NOVA集团

• 1：未加工或最低加工食品
• 2：加工烹饪原料
• 3：加工食品
• 4：超加工食品和饮料产品

生态评分

• A.：对环境的影响非常小
• B：对环境影响小
• C：中度环境影响
• D：环境影响大
• E：对环境的影响非常大

用例

营养学家和营养师

• 快速访问全面的营养数据
• 比较产品的饮食建议
• 识别过敏原和成分
• 寻找符合特定营养标准的产品

对于开发者

• 将食品数据整合到健康和健身应用程序中
• 构建营养跟踪应用程序
• 创建配方分析工具
• 开发饮食限制过滤器

对于消费者

• 通过人工智能辅助做出明智的食物选择
• 轻松比较同类产品
• 用自然语言理解营养成分
• 获取过敏原警告和成分信息

对于研究人员

• 获取大规模食品数据
• 分析不同类别的营养趋势
• 研究成分模式和配方
• 研究食品对环境的影响

利率限制和最佳实践

虽然OpenFoodFacts不强制执行严格的费率限制，但请尊重：

• 尽可能缓存频繁访问的数据
• 不要发出过多的并发请求
• 考虑对批量操作实施请求延迟
• 对大型结果集使用分页

故障排除

常见问题

“找不到产品”错误：

• 验证条形码是否正确（13位EAN或UPC）
• 有些产品可能不在OpenFoodFacts数据库中
• 区域产品可能供应有限

空白营养数据：

• 并非所有产品都有完整的营养信息
• 数据质量因产品和贡献者而异
• 考虑为关键应用程序使用多个数据源

搜索未返回任何结果：

• 尝试更广泛的搜索词
• 检查拼写和语言
• 某些类别/品牌在数据库中可能有不同的名称

调试模式

使用调试日志运行服务器：

DEBUG=* npm start

路线图

• \[\]添加缓存层以提高性能
• \[\]对多个产品实施批量操作
• \[\]添加对产品建议/推荐的支持
• \[\]包括可用的价格比较数据
• \[\]添加对用户偏好和饮食限制的支持
• \[\]实现模糊搜索以更好地匹配产品
• \[\]添加对配方营养分析的支持

贡献指南

代码的风格

• 使用TypeScript实现类型安全
• 遵循ESLint配置
• 为公共方法添加JSDoc注释
• 为新功能编写单元测试

测试

# Run all tests
npm test

# Run with coverage
npm run test:coverage

# Run specific test file
npm test -- product.test.ts

提交问题

请包括：

• Node.js版本
• 错误消息和堆栈跟踪
• 重现步骤
• 预期行为与实际行为

安全

此服务器：

• 仅向OpenFoodFacts发出只读请求
• 不存储或缓存敏感数据
• 不需要身份验证或API密钥
• 遵循OpenFoodFacts服务条款

演出

典型响应时间：

• 通过条形码查找产品：200-500ms
• 产品搜索：300-800ms
• 类别浏览：400-1000ms

性能因素：

• OpenFoodFacts服务器的网络延迟
• 产品数据完整性
• 搜索复杂性

致谢

• OpenFoodFacts -开放式食品数据库
• 模型上下文协议 -协议规范
• OpenFoodFacts全球贡献者社区