openfoodfacts-mcp-server

---

概览

来自 Open Food Facts 的包装食品数据。Open Food Facts 是一个由众包贡献构建、收录了 300 多万种产品的数据库。通过条码查找商品，按文本、标签、过敏原和营养阈值搜索，逐一比较产品，并将日常用语解析为筛选器采用的规范标签。

工具

工具	描述
off_get_product	通过条码获取单个产品：配料、过敏原及微量成分、添加剂、评分、营养信息和标签
off_search_products	按文本、标签筛选条件、过敏原排除项和营养阈值搜索（每 100 g；液体按每 100 ml）；返回包含条码的摘要行
off_compare_products	每次调用最多通过条码比较 10 种产品的营养信息（每 100 g；液体按每 100 ml）、Nutri-Score、NOVA 和 Green-Score
off_browse_taxonomy	将日常用语解析为 off_search_products 用作筛选条件的规范标签 ID

功能参考

off_get_product _工具

• barcode 只能包含数字；去掉任意前导零后，长度为 4–40 位；可选的 fields 会精简响应，并一并获取字段所依赖的数据（nutriments 会带上份量），requested_fields 会回显实际获取的字段
• 返回配料（原始文本及最多三层深度的解析树，包含 percent_estimate）、allergens_tags、traces_tags、additives_tags、ingredients_analysis_tags（对纯素、素食和棕榈油的判定）、nutriscore_grade、nova_group、ecoscore_grade（Green-Score）、nutriments（每份以及每 100 g；液体为每 100 ml）、类别／标签／包装／产地／国家标签、image_url 和 completeness（0–1）
• traces_tags: ["en:none"] 表示标签注明不含痕量成分，而空数组表示尚未录入相关信息；如果没有贡献者记录某个条形码，则会以 not_found 失败

---

off_search_products _工具

• query（最多 24 个词，每个词都必须匹配名称、通用名称、类别、标签或品牌；标点会分隔词语，因此 milk-chocolate 要求两者都匹配），以及标签筛选条件 categories_tag、brands_tag、labels_tag（最多 10 个）、allergens_tag、traces_tag、ingredients_analysis_tag、additives_tag、nutrition_grade、nova_group、countries_tag、exclude_allergens／exclude_traces 列表（各最多 14 个），以及最多 18 个 nutrient_filters（每 100 g；液体为每 100 ml）；所有条件按 AND 组合；可选 sort_by
• page_size 默认为 20，每次调用最多返回 50 个；较大的值（最多 10,000）仍只返回 50 个，并在 page_size_capped 中标记；page 按每页 50 个计数。每行包含 barcode、product_name、brands、nutriscore_grade、nova_group、ecoscore_grade 和 categories_tags，另有 total、total_is_lower_bound、last_page、omitted 和 truncated（表示此页之后还有匹配项）。排除条件会添加 exclusion_coverage，因为未录入过敏原数据的产品也会通过这些条件；nutrient_filters 会添加 indexed_nutriments（筛选条件检查的索引值，可能与 off_get_product 返回的值不同）
• query 或 nutrient_filters 搜索使用文本索引，其更新滞后于实时数据库（在 text_index_snapshot 中标记），且最多只能获取前 10,000 条结果；使用 additives_tag 会因 additives_filter_needs_tag_search 被拒绝。仅使用标签的搜索会读取实时数据库，最多支持到第 10 页。超出任一上限的页面会以 page_out_of_range 失败

---

off_compare_products _工具

• 接受 2–100 个 barcodes，每个条形码对应一行，并按输入顺序排列；重复条形码只比较一次；超过第 10 个不同条形码的条目会列在 unprocessed 中，不会被获取
• 每行包含 found、nutriscore_grade、nova_group、ecoscore_grade、能量、脂肪、饱和脂肪、糖、盐、蛋白质和纤维（每 100 g；液体为每 100 ml），以及 completeness；缺失值保持缺失，不会推算补齐
• not_found 列出没有贡献者记录的条形码，failed 列出获取失败的条形码，两者都包含 reason；获取失败的条形码不会生成对应行，也不会阻止处理其他条形码

---

off_browse_taxonomy _工具

• facet 可选 categories、labels、allergens、additives、countries、nova_groups、nutrition_grades 之一；search 会匹配标签 ID、名称或同义词中的子字符串（“shellfish” → en:crustaceans）；limit（默认为 20）每次最多返回 100 个（即使指定的值最高为 200，也仍只返回 100 个）；结果被截断时会说明匹配数量；不支持分页
• 返回由 id 和 name 组成的 tags[]，其中 id 可直接用于 off_search_products，无需修改；nova_groups 和 nutrition_grades 会完整返回，并附带 total_in_facet
• 五个开放类别会查询实时 Open Food Facts 分类体系；若其不可用，则会回退到较小的离线样本，并附带 notice；省略 search 时只返回该样本

功能

基于 @cyanheads/mcp-ts-core 构建：支持 stdio 和 Streamable HTTP 传输、可插拔身份验证（none / jwt / oauth）、可切换存储（in-memory、filesystem、Supabase、Cloudflare KV/R2/D1），以及结构化日志记录和可选的 OpenTelemetry 跟踪。

Open Food Facts 专属功能：

• 无需 API 密钥；内置符合 Open Food Facts 条款要求的标识性 User-Agent
• 按端点设置请求预算（产品每分钟 15 次、搜索每分钟 10 次、分类体系每分钟 10 次）；瞬时故障最多重试 4 次
• 将营养成分从带连字符的键规范化（energy-kcal_100g → energy_kcal_100g），并提供 additional_100g / additional_serving 映射，为每种营养成分标注单位
• 标签筛选器使用规范 ID（en:organic、en:no-gluten）；文本搜索中的大小写变体、同义词或品牌名称会先转换为规范形式（US → en:united-states）
• 每个字段均由贡献者录入，因此缺失字段表示尚未记录；Nutri-Score、NOVA 和 Green-Score 是 Open Food Facts 自行计算的评级，会按原样返回，并附带地区公式说明

适合 Agent 的输出：

• 每份营养数据都会注明其分母：serving_size、serving_quantity、serving_quantity_unit；若未记录分母，则会附上说明
• 优雅处理部分失败：off_compare_products 会同时返回已解析的行以及 not_found 和 failed 项
• 明确标注计数边界：搜索结果中包含 total_is_lower_bound、last_page 和 omitted
• 失败类型明确：每种失败都包含声明的 reason（upstream_error、upstream_timeout、upstream_rejected、rate_limited，以及各工具对应的输入原因）和恢复提示；上游响应不完整时，会作为可重试的 upstream_error 处理，绝不会返回空结果或标记为未找到

开始使用

公共托管实例

可使用公共实例 https://openfoodfacts.caseyjhand.com/mcp，无需安装。该实例使用 Streamable HTTP；各客户端的配置格式各不相同。

使用 Claude Code：

claude mcp add --transport http openfoodfacts-mcp-server https://openfoodfacts.caseyjhand.com/mcp

使用 Cline（cline_mcp_settings.json）：

{
  "mcpServers": {
    "openfoodfacts-mcp-server": {
      "type": "streamableHttp",
      "url": "https://openfoodfacts.caseyjhand.com/mcp"
    }
  }
}

使用 Cursor（mcp.json）：

{
  "mcpServers": {
    "openfoodfacts-mcp-server": {
      "url": "https://openfoodfacts.caseyjhand.com/mcp"
    }
  }
}

Claude Desktop 可在 Customize → Connectors 中添加远程服务。

自托管 / 本地运行

无需 API 密钥。将以下内容添加到 MCP 客户端配置文件中。

{
  "mcpServers": {
    "openfoodfacts-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/openfoodfacts-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

也可使用 npx（无需 Bun）：

{
  "mcpServers": {
    "openfoodfacts-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/openfoodfacts-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

也可使用 Docker：

{
  "mcpServers": {
    "openfoodfacts-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MCP_TRANSPORT_TYPE=stdio",
        "ghcr.io/cyanheads/openfoodfacts-mcp-server:latest"
      ]
    }
  }
}

使用 Streamable HTTP 时，设置传输方式并启动服务：

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcp

前置条件

• Bun v1.4.0 或更高版本（或 Node.js v24+）。
• 无需 API 密钥或账户。Open Food Facts 要求客户端标识自身；服务的 User-Agent 无需配置即可满足此要求。

安装

1. 克隆仓库：

git clone https://github.com/cyanheads/openfoodfacts-mcp-server.git

2. 进入目录：

cd openfoodfacts-mcp-server

3. 安装依赖：

bun install

4. 配置环境：

cp .env.example .env
# edit .env if you need to override rate limits or the base URL

配置

变量	描述	默认值
OFF_BASE_URL	Open Food Facts API 基础 URL。	https://world.openfoodfacts.org
OFF_RATE_LIMIT_PRODUCT	产品读取预算（请求/分钟）。默认值为 Open Food Facts 公布的每 IP 限额；如果多个客户端共用一个出站 IP，请调低此值。	15
OFF_RATE_LIMIT_SEARCH	搜索预算（请求/分钟）。默认值为 Open Food Facts 公布的每 IP 限额。	10
OFF_RATE_LIMIT_TAXONOMY	分类体系查询预算（请求/分钟），由 off_browse_taxonomy、文本搜索中的标签规范化以及排除项检查共用。	10
MCP_TRANSPORT_TYPE	传输方式：stdio 或 http。	stdio
MCP_HTTP_PORT	HTTP 服务端口。	3010
MCP_AUTH_MODE	身份验证模式：none、jwt 或 oauth。	none
MCP_LOG_LEVEL	日志级别（debug、info、warning、error）。	info
LOG_TOOL_FAILURE_PAYLOADS	记录每次失败的工具调用的参数和结果；按键名对内容脱敏，并将大小限制为 LOG_TOOL_FAILURE_PAYLOAD_MAX_BYTES（默认值为 16384）。自由格式值中的密钥不会被脱敏。	false
OTEL_ENABLED	启用 OpenTelemetry 插桩。	false

完整的可选覆盖项列表请参见 .env.example。

运行服务

本地开发

• 构建并运行：

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:stdio
  # or
  bun run start:http
  

• 运行检查和测试：

  bun run devcheck   # Lint, format, typecheck, security
  bun run test       # Vitest test suite
  bun run lint:mcp   # Validate MCP definitions against spec
  

Docker

docker build -t openfoodfacts-mcp-server .
docker run --rm -p 3010:3010 openfoodfacts-mcp-server

Dockerfile 默认使用 HTTP 传输、无状态会话模式，并将日志写入 /var/log/openfoodfacts-mcp-server。默认会安装 OpenTelemetry 对等依赖；若要省略这些依赖，请使用 --build-arg OTEL_ENABLED=false 进行构建。

项目结构

目录	用途
src/index.ts	createApp() 入口点——注册工具并初始化服务。
src/config	使用 Zod 解析并验证特定于服务端的环境变量。
src/mcp-server/tools	工具定义（*.tool.ts）。
src/services/openfoodfacts	Open Food Facts API 客户端——HTTP、速率限制、重试、字段规范化。
src/services/taxonomy	标签词汇——实时解析、离线示例和标签值规范化。
src/utils	对文本输出中由贡献者提供的值进行 Markdown 转义。
tests/	与 src/ 结构对应的单元测试和集成测试。

开发指南

开发指南和架构规则请参见 CLAUDE.md。简要说明：

• 处理程序抛出异常，框架负责捕获——工具逻辑中不要使用 try/catch
• 使用 ctx.log 进行请求范围内的日志记录，使用 ctx.state 进行租户范围内的存储
• 通过 src/mcp-server/tools/definitions/index.ts 中的汇总文件注册新工具
• 封装外部 API 调用：验证原始数据 → 规范化为领域类型 → 返回输出架构；绝不捏造缺失字段

贡献

欢迎提交问题——表单及如何提交有效报告，请参见 CONTRIBUTING.md。请通过私密披露报告漏洞，切勿公开提交问题。提交前请运行检查和测试：

bun run devcheck
bun run test

许可证

Apache-2.0——详情请参见 LICENSE。Open Food Facts 数据采用 Open Database License（ODbL）1.0 发布；下游使用时必须注明来源为 Open Food Facts。