Openfoodfacts Mcp Server

---

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. Runs as a stdio process, a local Streamable HTTP server, or the public hosted endpoint above.

Tools

Tool	Description
off_get_product	Fetch one product by barcode: ingredients, allergens and traces, additives, scores, nutrition, and tags
off_search_products	Search by text, tag filters, allergen exclusions, and nutrient thresholds (per 100 g, or per 100 ml for liquids); returns summary rows with barcodes
off_compare_products	Compare up to 10 products per call by barcode on nutrition (per 100 g, or per 100 ml for liquids), Nutri-Score, NOVA, and Green-Score
off_browse_taxonomy	Resolve a human term to the canonical tag ID that off_search_products filters on

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; every word except common stop words must match the name, generic name, categories, labels, or brand, and a hyphen or other punctuation between words separates them, so milk-chocolate requires both) plus tag filters categories_tag, brands_tag, labels_tag (up to 10, all must apply), 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; page_size (default 20) up to 50 per call, with a larger value up to 10,000 served at 50 and flagged in page_size_capped while page counts pages of 50; optional sort_by
• Summary rows carry barcode, product_name, brands, nutriscore_grade, nova_group, ecoscore_grade, and categories_tags, alongside total, total_is_lower_bound, page_size, last_page, and omitted; truncated marks a page with more matches beyond it, never the final page; responses using an exclusion carry exclusion_coverage, since products with no allergen data entered pass it
• With nutrient_filters, each row also carries indexed_nutriments: the text index's values for the constrained nutrients (per 100 g, or per 100 ml for liquids), keyed like off_get_product (sugars_100g, energy_kcal_100g). They are the values the filters were checked against and can differ from the current record off_get_product returns
• query or nutrient_filters routes the search to a text index that lags the live database (flagged in text_index_snapshot), serves 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, and a page past either bound fails as page_out_of_range

---

off_compare_products _tool

• 2–100 barcodes, returned one row each in input order; a repeated barcode is compared once (two identical barcodes yield one row), 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) up to 100 per call, with a larger value up to 200 returning the first 100; a cut names how many matched and whether a larger limit or a narrower term reaches the rest; 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 unreachable, gives no usable answer, or the budget is spent; 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), counted per upstream attempt; transient failures (5xx other than 501, timeouts, 429 with Retry-After) retry up to 4 attempts, while a 4xx or 501 is sent once
• Nutriments normalized from hyphenated keys (energy-kcal_100g → energy_kcal_100g), with named macros plus additional_100g / additional_serving maps that label each nutrient with the unit Open Food Facts normalizes it to (g, kJ, kcal, % vol, %, mmol/l, or none for pH and glycemic index)
• Tag filters take canonical IDs (en:organic, en:no-gluten); on text searches a case variant, synonym, or brand name is canonicalized before it is sent (US → en:united-states, Nutella → nutella)
• Every field is contributor-entered, so a missing one means not yet recorded rather than absent from the product; 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, and an exhausted page is reported as such rather than as zero matches
• Typed failures: each carries a declared reason (upstream_error, upstream_timeout, upstream_rejected, rate_limited, plus per-tool input reasons) and a recovery hint on both client surfaces; a success response missing its result fields is a retryable upstream_error (a failed entry on off_compare_products; the noticed offline fallback on off_browse_taxonomy), never a confident empty result or a not-found

Getting started

Public Hosted Instance

A public instance is available at https://openfoodfacts.caseyjhand.com/mcp — no installation required. Point any MCP client at it via Streamable HTTP:

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

Self-Hosted / Local

No API key is required. Add the following to your MCP client configuration file.

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

Or with npx (no Bun required):

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

Or with 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"
      ]
    }
  }
}

For Streamable HTTP, set the transport and start the server:

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

Prerequisites

• Bun v1.4.0 or higher (or Node.js v24+).
• No API key or account. Open Food Facts asks clients to identify themselves, and the server's User-Agent does so without configuration.

Installation

1. Clone the repository:

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

2. Navigate into the directory:

cd openfoodfacts-mcp-server

3. Install dependencies:

bun install

4. Configure environment:

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

Configuration

Variable	Description	Default
OFF_BASE_URL	Open Food Facts API base URL.	https://world.openfoodfacts.org
OFF_RATE_LIMIT_PRODUCT	Product read budget (requests/min). The default is Open Food Facts' published per-IP limit; lower it on a shared outbound IP.	15
OFF_RATE_LIMIT_SEARCH	Search budget (requests/min). The default is Open Food Facts' published per-IP limit.	10
OFF_RATE_LIMIT_TAXONOMY	Taxonomy lookup budget (requests/min), shared by off_browse_taxonomy, tag canonicalization on text searches, and exclusion checks.	10
MCP_TRANSPORT_TYPE	Transport: stdio or http.	stdio
MCP_HTTP_PORT	HTTP server port.	3010
MCP_AUTH_MODE	Auth mode: none, jwt, or oauth.	none
MCP_LOG_LEVEL	Log level (debug, info, warning, error).	info
LOG_TOOL_FAILURE_PAYLOADS	Log each failed tool call's arguments and result, redacted by key name and capped at LOG_TOOL_FAILURE_PAYLOAD_MAX_BYTES (default 16384). A secret inside a free-form value is not redacted.	false
OTEL_ENABLED	Enable OpenTelemetry instrumentation.	false

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

Running the server

Local development

• Build and run:

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

• Run checks and tests:

  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

The Dockerfile defaults to HTTP transport, stateless session mode, and logs to /var/log/openfoodfacts-mcp-server. OpenTelemetry peer dependencies are installed by default — build with --build-arg OTEL_ENABLED=false to omit them.

Project structure

Directory	Purpose
src/index.ts	createApp() entry point — registers tools and inits services.
src/config	Server-specific environment variable parsing and validation with Zod.
src/mcp-server/tools	Tool definitions (*.tool.ts).
src/services/openfoodfacts	Open Food Facts API client — HTTP, rate limiting, retry, field normalization.
src/services/taxonomy	Tag vocabulary — live resolution, offline sample, and tag-value canonicalization.
src/utils	Markdown escaping for contributor-entered values in text output.
tests/	Unit and integration tests mirroring src/.

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.