Openfoodfacts MCP Server README

Overview

Packaged-food data from Open Food Facts, a crowd-sourced database of 3M+ products. Look up items by barcode, search by text, tags, allergens, and nutrient thresholds, compare products side by side, and resolve everyday terms to the canonical tags the filters take.

Tools

Skills

Capability reference

off_get_product _tool

• barcode is digits only, 4–40 digits after any leading zeros; optional fields trims the response and pulls in what a field depends on (nutriments brings the serving size), with requested_fields echoing what was fetched
• Returns ingredients (raw text plus a parsed tree up to three levels deep with percent_estimate), allergens_tags, traces_tags, additives_tags, ingredients_analysis_tags (vegan, vegetarian, palm-oil verdicts), nutriscore_grade, nova_group, ecoscore_grade (Green-Score), nutriments (per serving, and per 100 g, or per 100 ml for liquids), category/label/packaging/origin/country tags, image_url, and completeness (0–1)
• traces_tags: ["en:none"] means the label states no traces, while an empty array means none entered yet; a barcode no contributor has recorded fails as not_found

off_search_products _tool

• query (up to 24 words, all of which must match the name, generic name, categories, labels, or brand; punctuation separates words, so milk-chocolate requires both) plus the tag filters categories_tag, brands_tag, labels_tag (up to 10), allergens_tag, traces_tag, ingredients_analysis_tag, additives_tag, nutrition_grade, nova_group, countries_tag, the exclude_allergens / exclude_traces lists (up to 14 each), and up to 18 nutrient_filters (per 100 g, or per 100 ml for liquids), all combined as AND; optional sort_by
• page_size defaults to 20 and is served at up to 50 per call; a larger value (up to 10,000) is served at 50 and flagged in page_size_capped, and page counts pages of 50. Rows carry barcode, product_name, brands, nutriscore_grade, nova_group, ecoscore_grade, and categories_tags, plus total, total_is_lower_bound, last_page, omitted, and truncated (more matches beyond this page). Exclusions add exclusion_coverage, since products with no allergen data entered pass them; nutrient_filters add indexed_nutriments (the index values the filters checked, which can differ from off_get_product)
• query or nutrient_filters searches a text index that lags the live database (flagged in text_index_snapshot), reaches only the first 10,000 results, and rejects additives_tag as additives_filter_needs_tag_search; tag-only searches read the live database through page 10. A page past either limit fails as page_out_of_range

off_compare_products _tool

• 2–100 barcodes, one row each in input order; repeated barcodes are compared once, and those past the 10th distinct one are listed in unprocessed without being fetched
• Rows carry found, nutriscore_grade, nova_group, ecoscore_grade, energy, fat, saturated fat, sugars, salt, protein, and fiber (per 100 g, or per 100 ml for liquids), and completeness; missing values stay absent, never imputed
• not_found lists barcodes with no contributor record and failed lists fetches that failed, each with a reason; a failed barcode gets no row and never blocks the rest

off_browse_taxonomy _tool

• facet is one of categories, labels, allergens, additives, countries, nova_groups, nutrition_grades; search matches a substring of the tag ID, name, or a synonym ("shellfish" → en:crustaceans); limit (default 20) returns up to 100 per call (a value up to 200 still returns 100); a cut result says how many matched; no paging
• Returns tags[] of id and name, where id goes to off_search_products unchanged; nova_groups and nutrition_grades come back complete with total_in_facet
• The five open facets resolve against the live Open Food Facts taxonomy and fall back to a small offline sample, with a notice, when it is unavailable; omitting search returns only that sample

Features

Built on @cyanheads/mcp-ts-core: stdio and Streamable HTTP transports, pluggable auth (none / jwt / oauth), swappable storage (in-memory, filesystem, Supabase, Cloudflare KV/R2/D1), structured logging with optional OpenTelemetry tracing.

Open Food Facts-specific:

• No API key; the identifying User-Agent Open Food Facts' terms require is built in
• Per-endpoint request budgets (product 15/min, search 10/min, taxonomy 10/min); transient failures retry up to 4 attempts
• Nutriments normalized from hyphenated keys (energy-kcal_100g → energy_kcal_100g), with additional_100g / additional_serving maps that label each nutrient with its unit
• Tag filters take canonical IDs (en:organic, en:no-gluten); on text searches a case variant, synonym, or brand name is canonicalized first (US → en:united-states)
• Every field is contributor-entered, so a missing one means not yet recorded; Nutri-Score, NOVA, and Green-Score are Open Food Facts' own computed grades, returned as-is, and carry regional formula caveats

Agent-friendly output:

• Per-serving nutrition carries its denominator: serving_size, serving_quantity, serving_quantity_unit, and a note when none is recorded
• Graceful partial failure: off_compare_products returns resolved rows alongside not_found and failed
• Explicit count bounds: total_is_lower_bound, last_page, and omitted on searches
• Typed failures: each carries a declared reason (upstream_error, upstream_timeout, upstream_rejected, rate_limited, plus per-tool input reasons) and a recovery hint; an incomplete upstream response is a retryable upstream_error, never an empty result or a not-found

Getting started

Connect to the hosted instance, no install:

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

Or run it locally:

claude mcp add openfoodfacts-mcp-server -- npx -y @cyanheads/openfoodfacts-mcp-server

For other clients, add this to the MCP config file:

{
  "mcpServers": {
    "openfoodfacts-mcp-server": {
      "command": "npx",
      "args": ["-y", "@cyanheads/openfoodfacts-mcp-server"]
    }
  }
}

No API key or account is needed: the server identifies itself to Open Food Facts with its own User-Agent. For Docker or a source build, see Running the server.

Configuration

See .env.example for the full list of optional overrides.

Running the server

Local development

Requires Bun v1.4.0 or higher (or Node.js v24+).

• Clone and install:

  shCopy

  git clone https://github.com/cyanheads/openfoodfacts-mcp-server.git
  cd openfoodfacts-mcp-server && bun install
  cp .env.example .env   # optional: override rate limits or the base URL
  

• Build and run:

  shCopy

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

• Run checks and tests:

  shCopy

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

Docker

docker run --rm -p 3010:3010 ghcr.io/cyanheads/openfoodfacts-mcp-server:latest

The image defaults to HTTP transport, stateless session mode, and logs to /var/log/openfoodfacts-mcp-server. To run it over stdio from an MCP client, use "command": "docker" with "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/openfoodfacts-mcp-server:latest"]. To build locally, docker build -t openfoodfacts-mcp-server .; OpenTelemetry peer dependencies are installed by default — build with --build-arg OTEL_ENABLED=false to omit them.

Project structure

Development guide

See CLAUDE.md for development guidelines and architectural rules. The short version:

• Handlers throw, framework catches — no try/catch in tool logic
• Use ctx.log for request-scoped logging, ctx.state for tenant-scoped storage
• Register new tools via the barrel in src/mcp-server/tools/definitions/index.ts
• Wrap external API calls: validate raw → normalize to domain type → return output schema; never fabricate missing fields

Contributing

Issues are welcome — see CONTRIBUTING.md for the forms and what makes a report actionable. Report vulnerabilities through private disclosure, never a public issue. Run checks and tests before submitting:

bun run devcheck
bun run test

License

Apache-2.0 — see LICENSE for details. Open Food Facts data is released under the Open Database License (ODbL) 1.0; downstream use must cite Open Food Facts.