io.github.cyanheads/openfoodfacts-mcp-server

Official4 toolsLive

by cyanheads · TypeScript

Barcode lookup, nutrition search, and product comparison for 3M+ crowd-sourced food products.

This Model Context Protocol (MCP) server performs barcode lookup, nutrition search, and product comparison for 3M+ crowd-sourced food products. It also exposes the canonical tag vocabulary via MCP. The server supports STDIO or Streamable HTTP and provides 4 tools. It is implemented as a TypeScript project.

🛠️ Key Features

Barcode lookup
Nutrition search
Product comparison side-by-side
Browse the canonical tag vocabulary via MCP
4 tools
STDIO or Streamable HTTP

🚀 Use Cases

Retrieve a product by barcode
Search products by ingredient or nutrition filter
Compare multiple food products side-by-side
Access canonical tag vocabulary through MCP

⚡ Developer Benefits

MCP tool access for barcode and nutrition workflows
Canonical tag vocabulary browsing via MCP
Integration over STDIO or Streamable HTTP

⚠️ Limitations

Limited to the functions described: lookup, nutrition search, comparison, and canonical tag vocabulary browsing

barcode lookupnutrition searchfood databaseproduct comparisoningredientsallergensopenfoodfacts

Topics

ai-agentsai-toolsbarcodecyanheadsfoodmcpmcp-servermodel-context-protocolnutritionopenfoodfactstypescript

Captured live from the server via tools/list.

off_get_product

Fetch a packaged food product by barcode (4–40 digits: EAN-13, EAN-8, UPC, and the shorter and longer codes Open Food Facts also holds) from Open Food Facts. Returns the product name, brand, quantity, ingredients (raw text and parsed list), declared allergens, trace allergens the label warns about, additives, the product-level vegan/vegetarian/palm-oil analysis, computed scores (Nutri-Score a–e, NOVA 1–4, Green-Score), nutrition per 100g and per serving, categories, labels, packaging, origins, countries of sale, image URL, and data completeness. Open Food Facts is a crowd-sourced database — a missing field means "not yet entered by contributors," not that the attribute is absent from the actual product. Computed scores carry regional formula caveats and are indicators, not absolute rankings. Data is under ODbL 1.0 — cite Open Food Facts in downstream use.

Parameters2

barcode	string	required	Product barcode, digits only: 4–40 digits after any leading zeros. The primary key for Open Food Facts — the barcode of an off_search_products row works as is. Example: "3017620422003" (Nutella FR).
fields	array	optional	Subset of fields to return. Omitting returns all standard fields. Use to reduce payload when only scores or ingredients are needed. A field that cannot be read on its own arrives with what it depends on: nutriments brings serving_size, serving_quantity, and serving_quantity_unit so per-serving figures carry their denominator, and serving_quantity_unit brings the quantity it describes. requested_fields echoes the full set that was fetched.

Raw schema

{
  "type": "object",
  "properties": {
    "barcode": {
      "type": "string",
      "pattern": "^0*[1-9]\\d{3,39}$",
      "description": "Product barcode, digits only: 4–40 digits after any leading zeros. The primary key for Open Food Facts — the barcode of an off_search_products row works as is. Example: \"3017620422003\" (Nutella FR)."
    },
    "fields": {
      "description": "Subset of fields to return. Omitting returns all standard fields. Use to reduce payload when only scores or ingredients are needed. A field that cannot be read on its own arrives with what it depends on: nutriments brings serving_size, serving_quantity, and serving_quantity_unit so per-serving figures carry their denominator, and serving_quantity_unit brings the quantity it describes. requested_fields echoes the full set that was fetched.",
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "product_name",
          "brands",
          "quantity",
          "ingredients_text",
          "ingredients",
          "allergens_tags",
          "traces_tags",
          "additives_tags",
          "ingredients_analysis_tags",
          "nutriscore_grade",
          "nova_group",
          "ecoscore_grade",
          "nutriments",
          "serving_size",
          "serving_quantity",
          "serving_quantity_unit",
          "categories_tags",
          "labels_tags",
          "packaging_tags",
          "origins_tags",
          "countries_tags",
          "image_url",
          "completeness",
          "data_quality_tags"
        ],
        "description": "A specific product field to include in the response."
      }
    }
  },
  "required": [
    "barcode"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

off_search_products

Search Open Food Facts by full-text query, structured tag filters, or both at once. Returns a summary list with barcodes, product names, brands, Nutri-Score, NOVA group, and categories — enough for triage and selection, not full label data. Use off_get_product on the returned barcodes for complete details. A text query and tag filters combine: every word of the query must match the product name, generic name, categories, labels, or brand, and every filter provided must hold (e.g. query "dark chocolate" with labels_tag "en:organic" and countries_tag "en:france" returns organic chocolate sold in France); numeric nutrient_filters express per-100 g thresholds such as sugars below 8 g and combine the same way; additives_tag is the one exception, filtering only on searches carrying neither query nor nutrient_filters. Tag filter values are canonical tag IDs (e.g. "en:organic", "en:no-gluten") — use off_browse_taxonomy to resolve human terms to tag IDs. A case variant, synonym, or singular of a tag is resolved to its canonical ID where Open Food Facts recognizes it; anything else is matched exactly. exclude_allergens and exclude_traces drop products that declare an allergen or a "may contain" trace, but a product with no allergen or trace data entered passes them, so confirm a candidate with off_get_product before relying on it. At least one search parameter is required. The two paths read different indexes: a search carrying query is answered by the text index, a snapshot that lags the live database, while a tag-only search reads the live database and is current — so a recently contributed product can be missing from a text search and present in the same search without query. Data is crowd-sourced; result count reflects contributed products, not all products in the market. Data under ODbL 1.0 — cite Open Food Facts in downstream use.

Parameters17

query	string	optional	Words to find. Every word must match the product name, generic name, categories, labels, or brand — ingredients and quantity are not searched — so put only words the product itself would carry. Stop words of English, French, Spanish, German, and Italian ("with", "the", "de", "mit", …) are not required, and neither is a content word that is a stop word in one of them (such as Spanish "soy"), though it still ranks the results. Names are matched in the 31 languages the text index analyzes, so a product named only in French is found by its French name. At most 24 words, counting each part of a hyphenated word. Example: "dark chocolate 70%". Supplying it routes the search to the text index, a snapshot that lags the live Open Food Facts database; drop it to run the same tag filters against the current data.
categories_tag	string	optional	Canonical category tag ID. Example: "en:breakfast-cereals", "en:cheeses". Use off_browse_taxonomy with facet="categories" to discover valid values.
brands_tag	string	optional	Brand slug (lowercased, hyphenated). Example: "nutella", "kelloggs". A brand name is slugged the way Open Food Facts slugs it ("Ben & Jerry's" → "ben-jerry-s") and then matched exactly — a partial or misspelled slug matches nothing rather than falling back to a near match, so put open-ended brand wording in query instead.
labels_tag	any	optional	Canonical label/certification tag ID, or an array of up to 10 that must all apply. Example: "en:organic", or ["en:organic", "en:fair-trade"] for products carrying both. Use off_browse_taxonomy with facet="labels".
allergens_tag	string	optional	Canonical allergen tag ID. Example: "en:milk", "en:gluten". Use off_browse_taxonomy with facet="allergens". Selects products that declare this allergen; it cannot select allergen-free products, because a product with no allergen tags may simply have none entered yet. To leave an allergen out, use exclude_allergens.
traces_tag	string	optional	Canonical allergen tag ID the label warns the product may contain as a trace ("may contain nuts"). Example: "en:nuts". Trace tags are allergen tags, so off_browse_taxonomy with facet="allergens" resolves them. Selects products carrying the warning; to leave them out, use exclude_traces.
exclude_allergens	array	optional	Allergen tag IDs a product must not declare, all applied. Example: ["en:nuts", "en:peanuts"]. Each value must be an allergen tag Open Food Facts recognizes — resolve it with off_browse_taxonomy facet="allergens" — and one it does not recognize is rejected rather than sent, because it would exclude nothing. A product with no allergen data entered passes an exclusion, so check a candidate with off_get_product before relying on it.
exclude_traces	array	optional	Allergen tag IDs a product's label must not warn it may contain as traces, all applied. Example: ["en:nuts"]. Values are validated like exclude_allergens. A product with no trace data entered passes, so check a candidate with off_get_product before relying on it.
ingredients_analysis_tag	string	optional	Vegan, vegetarian, or palm-oil verdict Open Food Facts computes from the parsed ingredients. Example: "en:vegan", "en:palm-oil-free". "en:maybe-vegan" and "en:may-contain-palm-oil" mean the ingredients could not settle it, and the "-unknown" values mean no verdict could be computed.
additives_tag	string	optional	Canonical additive (E-number) tag ID. Example: "en:e322", "en:e330". Use off_browse_taxonomy with facet="additives". Available only on searches carrying neither query nor nutrient_filters — both route to a backend with no additives field, so combining them is rejected instead of silently returning nothing.
nutrition_grade	string	optional	Filter by Nutri-Score grade. "a" is highest nutritional quality, "e" is lowest. Products without a score are excluded.
nova_group	string	optional	Filter by NOVA food processing class. "1"=unprocessed/minimally processed, "4"=ultra-processed. Products without a NOVA score are excluded.
countries_tag	string	optional	Canonical country tag ID. Example: "en:france", "en:united-states". Filters to products sold in that country.
nutrient_filters	array	optional	Numeric constraints on nutrient values per 100 g, combined as AND with each other and with every other filter. Pair two entries on the same nutrient to express a range (e.g. sugars gte 2 and sugars lte 8). Served only by the text backend, so supplying one routes the search there even without query — it then reads the lagging text index and is subject to the 10,000-result page window, and additives_tag cannot be combined with it. Per-serving and prepared-product values are not searchable.
sort_by	string	optional	Sort order, applied on every search. Each value orders newest or highest first: "unique_scans_n" surfaces the most-scanned products, "last_modified_t" and "created_t" the most recently updated and newest records, "popularity_key" the most popular. Omitting it leaves text searches relevance-ranked and tag-only searches in the default order.
page	integer	optional	Page number (1-based). Use with page_size to paginate results. A search by tag filters alone is served through page 10 only, so at page_size 50 it reaches the first 500 matches. A search carrying query or nutrient_filters serves only the first 10000 results, so page * page_size must stay at or below 10000. A request past either bound is rejected rather than sent; narrow the filters or change sort_by to bring other products forward.
page_size	integer	optional	Results per page (1–50, default 20). Keep low for initial exploration; increase for comparison workflows.

Raw schema

{
  "type": "object",
  "properties": {
    "query": {
      "description": "Words to find. Every word must match the product name, generic name, categories, labels, or brand — ingredients and quantity are not searched — so put only words the product itself would carry. Stop words of English, French, Spanish, German, and Italian (\"with\", \"the\", \"de\", \"mit\", …) are not required, and neither is a content word that is a stop word in one of them (such as Spanish \"soy\"), though it still ranks the results. Names are matched in the 31 languages the text index analyzes, so a product named only in French is found by its French name. At most 24 words, counting each part of a hyphenated word. Example: \"dark chocolate 70%\". Supplying it routes the search to the text index, a snapshot that lags the live Open Food Facts database; drop it to run the same tag filters against the current data.",
      "type": "string"
    },
    "categories_tag": {
      "description": "Canonical category tag ID. Example: \"en:breakfast-cereals\", \"en:cheeses\". Use off_browse_taxonomy with facet=\"categories\" to discover valid values.",
      "type": "string"
    },
    "brands_tag": {
      "description": "Brand slug (lowercased, hyphenated). Example: \"nutella\", \"kelloggs\". A brand name is slugged the way Open Food Facts slugs it (\"Ben & Jerry's\" → \"ben-jerry-s\") and then matched exactly — a partial or misspelled slug matches nothing rather than falling back to a near match, so put open-ended brand wording in query instead.",
      "type": "string"
    },
    "labels_tag": {
      "description": "Canonical label/certification tag ID, or an array of up to 10 that must all apply. Example: \"en:organic\", or [\"en:organic\", \"en:fair-trade\"] for products carrying both. Use off_browse_taxonomy with facet=\"labels\".",
      "anyOf": [
        {
          "type": "string",
          "description": "One canonical label tag ID."
        },
        {
          "maxItems": 10,
          "type": "array",
          "items": {
            "type": "string",
            "description": "One canonical label tag ID."
          },
          "description": "Up to 10 canonical label tag IDs, all of which must apply."
        }
      ]
    },
    "allergens_tag": {
      "description": "Canonical allergen tag ID. Example: \"en:milk\", \"en:gluten\". Use off_browse_taxonomy with facet=\"allergens\". Selects products that declare this allergen; it cannot select allergen-free products, because a product with no allergen tags may simply have none entered yet. To leave an allergen out, use exclude_allergens.",
      "type": "string"
    },
    "traces_tag": {
      "description": "Canonical allergen tag ID the label warns the product may contain as a trace (\"may contain nuts\"). Example: \"en:nuts\". Trace tags are allergen tags, so off_browse_taxonomy with facet=\"allergens\" resolves them. Selects products carrying the warning; to leave them out, use exclude_traces.",
      "type": "string"
    },
    "exclude_allergens": {
      "description": "Allergen tag IDs a product must not declare, all applied. Example: [\"en:nuts\", \"en:peanuts\"]. Each value must be an allergen tag Open Food Facts recognizes — resolve it with off_browse_taxonomy facet=\"allergens\" — and one it does not recognize is rejected rather than sent, because it would exclude nothing. A product with no allergen data entered passes an exclusion, so check a candidate with off_get_product before relying on it.",
      "maxItems": 14,
      "type": "array",
      "items": {
        "type": "string",
        "description": "One canonical allergen tag ID to exclude, e.g. \"en:nuts\"."
      }
    },
    "exclude_traces": {
      "description": "Allergen tag IDs a product's label must not warn it may contain as traces, all applied. Example: [\"en:nuts\"]. Values are validated like exclude_allergens. A product with no trace data entered passes, so check a candidate with off_get_product before relying on it.",
      "maxItems": 14,
      "type": "array",
      "items": {
        "type": "string",
        "description": "One canonical allergen tag ID to exclude as a trace, e.g. \"en:nuts\"."
      }
    },
    "ingredients_analysis_tag": {
      "description": "Vegan, vegetarian, or palm-oil verdict Open Food Facts computes from the parsed ingredients. Example: \"en:vegan\", \"en:palm-oil-free\". \"en:maybe-vegan\" and \"en:may-contain-palm-oil\" mean the ingredients could not settle it, and the \"-unknown\" values mean no verdict could be computed.",
      "type": "string",
      "enum": [
        "en:palm-oil",
        "en:palm-oil-free",
        "en:may-contain-palm-oil",
        "en:palm-oil-content-unknown",
        "en:vegan",
        "en:maybe-vegan",
        "en:non-vegan",
        "en:vegan-status-unknown",
        "en:vegetarian",
        "en:maybe-vegetarian",
        "en:non-vegetarian",
        "en:vegetarian-status-unknown"
      ]
    },
    "additives_tag": {
      "description": "Canonical additive (E-number) tag ID. Example: \"en:e322\", \"en:e330\". Use off_browse_taxonomy with facet=\"additives\". Available only on searches carrying neither query nor nutrient_filters — both route to a backend with no additives field, so combining them is rejected instead of silently returning nothing.",
      "type": "string"
    },
    "nutrition_grade": {
      "description": "Filter by Nutri-Score grade. \"a\" is highest nutritional quality, \"e\" is lowest. Products without a score are excluded.",
      "type": "string",
      "enum": [
        "a",
        "b",
        "c",
        "d",
        "e"
      ]
    },
    "nova_group": {
      "description": "Filter by NOVA food processing class. \"1\"=unprocessed/minimally processed, \"4\"=ultra-processed. Products without a NOVA score are excluded.",
      "type": "string",
      "enum": [
        "1",
        "2",
        "3",
        "4"
      ]
    },
    "countries_tag": {
      "description": "Canonical country tag ID. Example: \"en:france\", \"en:united-states\". Filters to products sold in that country.",
      "type": "string"
    },
    "nutrient_filters": {
      "description": "Numeric constraints on nutrient values per 100 g, combined as AND with each other and with every other filter. Pair two entries on the same nutrient to express a range (e.g. sugars gte 2 and sugars lte 8). Served only by the text backend, so supplying one routes the search there even without query — it then reads the lagging text index and is subject to the 10,000-result page window, and additives_tag cannot be combined with it. Per-serving and prepared-product values are not searchable.",
      "maxItems": 18,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "nutrient": {
            "type": "string",
            "enum": [
              "energy-kcal",
              "fat",
              "saturated-fat",
              "carbohydrates",
              "sugars",
              "fiber",
              "proteins",
              "salt",
              "sodium"
            ],
            "description": "Nutrient to constrain, measured per 100 g. Energy is kilocalories; every other value is grams per 100 g."
          },
          "operator": {
            "type": "string",
            "enum": [
              "lt",
              "lte",
              "gt",
              "gte"
            ],
            "description": "Comparison against value: \"lt\" below, \"lte\" at or below, \"gt\" above, \"gte\" at or above."
          },
          "value": {
            "type": "number",
            "minimum": 0,
            "description": "Threshold to compare against, in the nutrient's per-100 g unit."
          }
        },
        "required": [
          "nutrient",
          "operator",
          "value"
        ],
        "description": "One numeric constraint on a per-100 g nutrient value."
      }
    },
    "sort_by": {
      "description": "Sort order, applied on every search. Each value orders newest or highest first: \"unique_scans_n\" surfaces the most-scanned products, \"last_modified_t\" and \"created_t\" the most recently updated and newest records, \"popularity_key\" the most popular. Omitting it leaves text searches relevance-ranked and tag-only searches in the default order.",
      "type": "string",
      "enum": [
        "last_modified_t",
        "unique_scans_n",
        "created_t",
        "popularity_key"
      ]
    },
    "page": {
      "default": 1,
      "description": "Page number (1-based). Use with page_size to paginate results. A search by tag filters alone is served through page 10 only, so at page_size 50 it reaches the first 500 matches. A search carrying query or nutrient_filters serves only the first 10000 results, so page * page_size must stay at or below 10000. A request past either bound is rejected rather than sent; narrow the filters or change sort_by to bring other products forward.",
      "type": "integer",
      "minimum": 1,
      "maximum": 9007199254740991
    },
    "page_size": {
      "default": 20,
      "description": "Results per page (1–50, default 20). Keep low for initial exploration; increase for comparison workflows.",
      "type": "integer",
      "minimum": 1,
      "maximum": 50
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

off_compare_products

Side-by-side nutrition and scoring comparison for 2–10 products by barcode. Returns a normalized table of energy (kcal/100g), fat, saturated fat, sugars, salt, protein, fiber, Nutri-Score, NOVA group, and Green-Score. Designed for "which of these cereals is healthiest?" or "compare these pasta brands" workflows. Missing nutrition data for any product is preserved as absent — comparisons are not imputed. A batch is not all-or-nothing: barcodes that resolve are returned even when others fail, with confirmed-missing barcodes listed in not_found and failed fetches listed separately in failed. Scores carry regional formula caveats. Data under ODbL 1.0 — cite Open Food Facts in downstream use.

Parameters1

barcodes

array

required

2–10 barcodes to compare, returned as one row each in input order. Example: ["3017620422003", "7622210100146"].

Raw schema

{
  "type": "object",
  "properties": {
    "barcodes": {
      "minItems": 2,
      "maxItems": 10,
      "type": "array",
      "items": {
        "type": "string",
        "pattern": "^0*[1-9]\\d{3,39}$",
        "description": "Product barcode, digits only: 4–40 digits after any leading zeros."
      },
      "description": "2–10 barcodes to compare, returned as one row each in input order. Example: [\"3017620422003\", \"7622210100146\"]."
    }
  },
  "required": [
    "barcodes"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

off_browse_taxonomy

Resolve a human term to the canonical Open Food Facts tag ID that off_search_products filters on. Covers categories, labels/certifications, allergens, additives, countries, NOVA groups, and Nutri-Score grades. Pass a search term to resolve against the Open Food Facts vocabulary, which holds tens of thousands of tags; omitting it returns only a small reference list for each facet except NOVA groups and Nutri-Score grades, which are complete. Most tag IDs use the "en:" prefix (e.g. "en:organic", "en:no-gluten", "en:crustaceans"); NOVA groups return bare digits "1"-"4" and Nutri-Score grades bare letters "a"-"e". Pass the id through to off_search_products exactly as returned. Category tags are frequently plural ("kombucha" resolves to "en:kombuchas"), so use the returned id rather than constructing one.

Parameters3

facet	string	required	"categories" covers food categories (en:cheeses, en:breakfast-cereals). "labels" covers certifications (en:organic, en:fair-trade). "allergens" covers declared allergens (en:milk, en:gluten). "additives" covers E-numbers (en:e322). "countries" covers country-of-sale tags (en:france). "nova_groups" and "nutrition_grades" are closed vocabularies returned complete; the other five are resolved against the Open Food Facts taxonomy.
search	string	optional	Term to resolve. Matched case-insensitively as a substring of the tag ID, the display name, or a common synonym of either ("shellfish" resolves to en:crustaceans, "gluten free" to en:no-gluten). A single word works best ("hummus", not "hummus dip"). Omit only to see a small reference list — Open Food Facts cannot list the full vocabulary without a term, so an unfiltered call is not a view of the full facet.
limit	integer	optional	Maximum entries to return (1–100, default 20). There is no offset or page input: Open Food Facts offers no cursor for this lookup, so narrow the search term rather than paging. The tag spelling the term itself (e.g. "lentil" → en:lentils) is listed first among the live matches, so it is not the one a small limit cuts.

Raw schema

{
  "type": "object",
  "properties": {
    "facet": {
      "type": "string",
      "enum": [
        "categories",
        "labels",
        "allergens",
        "additives",
        "countries",
        "nova_groups",
        "nutrition_grades"
      ],
      "description": "\"categories\" covers food categories (en:cheeses, en:breakfast-cereals). \"labels\" covers certifications (en:organic, en:fair-trade). \"allergens\" covers declared allergens (en:milk, en:gluten). \"additives\" covers E-numbers (en:e322). \"countries\" covers country-of-sale tags (en:france). \"nova_groups\" and \"nutrition_grades\" are closed vocabularies returned complete; the other five are resolved against the Open Food Facts taxonomy."
    },
    "search": {
      "description": "Term to resolve. Matched case-insensitively as a substring of the tag ID, the display name, or a common synonym of either (\"shellfish\" resolves to en:crustaceans, \"gluten free\" to en:no-gluten). A single word works best (\"hummus\", not \"hummus dip\"). Omit only to see a small reference list — Open Food Facts cannot list the full vocabulary without a term, so an unfiltered call is not a view of the full facet.",
      "type": "string"
    },
    "limit": {
      "default": 20,
      "description": "Maximum entries to return (1–100, default 20). There is no offset or page input: Open Food Facts offers no cursor for this lookup, so narrow the search term rather than paging. The tag spelling the term itself (e.g. \"lentil\" → en:lentils) is listed first among the live matches, so it is not the one a small limit cuts.",
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    }
  },
  "required": [
    "facet"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

README.md20 KBView on GitHub

@cyanheads/openfoodfacts-mcp-server

Look up food products by barcode, search by keyword, tag, allergen, or nutrition filter, compare products side-by-side, and browse the canonical tag vocabulary via MCP. STDIO or Streamable HTTP.

4 Tools

MCP SDK TypeScript

Public Hosted Server: https://openfoodfacts.caseyjhand.com/mcp

Overview

Food product data from Open Food Facts, a crowd-sourced database of 3M+ packaged food products. Look up items by barcode, search by text and nutrition/allergen/label tags, compare products side-by-side, and resolve everyday terms to the canonical tag vocabulary from any MCP client. Runs as a stdio process, a local Streamable HTTP server, or the public hosted endpoint above.

Tools

Tool	Description
`off_get_product`	Fetch a packaged food product by barcode. Returns name, brand, quantity, ingredients, declared and trace allergens, additives, the vegan/vegetarian/palm-oil analysis, Nutri-Score, NOVA group, Green-Score, nutrition per 100g/serving, categories, labels, countries of sale, and data completeness.
`off_search_products`	Search by text query, structured tag filters (category, brand, labels, allergen, trace, vegan/vegetarian/palm-oil verdict, additive, Nutri-Score grade, NOVA group, country), allergen and trace exclusions, and numeric per-100 g nutrient thresholds. Returns summary rows with barcodes for follow-up lookups.
`off_compare_products`	Side-by-side nutrition and scoring comparison for 2–10 products by barcode. Returns a normalized table of energy, macros, salt, Nutri-Score, NOVA, and Green-Score.
`off_browse_taxonomy`	Resolve a human term to the canonical tag ID (categories, labels, allergens, additives, countries, NOVA groups, Nutri-Score grades) that `off_search_products` filters on, against the live Open Food Facts taxonomy.

Capability reference

`off_get_product` _tool

Accepts every barcode Open Food Facts serves: digits only, 4–40 digits after any leading zeros — EAN-13, EAN-8, UPC-A, UPC-E, and the shorter and longer codes the database also holds
Returns ingredients (raw text and parsed list with percent estimates, vegan/vegetarian flags, and each entry's sub-ingredients nested under it — wheat flour under "cereal", palm oil under "vegetable oils" — up to three levels deep), all 14 major allergens as tag IDs, E-number additives, Nutri-Score (a–e, unknown, not-applicable), NOVA 1–4, Green-Score (a-plus, a–f, unknown, not-applicable), every nutrient Open Food Facts holds per 100g and per serving, the serving size those per-serving figures are measured against, categories/labels/packaging/origins/countries of sale as canonical tag IDs, front image URL, and data completeness score (0–1)
traces_tags carries the "may contain" allergen warning separately from the declared allergens_tags; ["en:none"] is the label stating no traces, while an empty array means not yet entered — never trace-free
ingredients_analysis_tags carries the vegan, vegetarian, and palm-oil verdicts Open Food Facts computes itself, including its "maybe" states, rather than leaving the per-ingredient flags to be aggregated by the caller
Optional fields parameter restricts the response to a subset (e.g., scores only, or nutrition only); a field that cannot be read on its own arrives with what it depends on — nutriments brings the serving size its per-serving figures are measured against — and requested_fields echoes the full set that was fetched
Open Food Facts is crowd-sourced — a missing field means "not yet entered by contributors," not that the attribute is absent from the actual product
A barcode no contributor has recorded raises the not_found error carrying a recovery hint — it is never returned as an empty result

`off_search_products` _tool

Full-text query plus structured tag filters — categories_tag, brands_tag, labels_tag (one label, or an array that must all apply), allergens_tag, traces_tag (the "may contain" warning), ingredients_analysis_tag (one of the 12 vegan, vegetarian, and palm-oil verdicts), additives_tag, nutrition_grade (a–e), nova_group (1–4), countries_tag — and numeric nutrient_filters, all combining as AND; tag values are canonical IDs, resolved via off_browse_taxonomy (brands_tag matches an exact slug, not free text)
exclude_allergens and exclude_traces drop products that declare an allergen or warn of a trace, on both paths. Each value must be an allergen tag the Open Food Facts vocabulary confirms — an unrecognized one would exclude nothing, so it is rejected before any search is sent. A product with no allergen or trace data entered passes an exclusion, and every response carrying one says so and points to off_get_product for a per-product check
Every word of query must match a product's name, generic name, categories, labels, or brand (ingredients and quantity are not searched), in any of the 31 languages the text index analyzes, so a product named only in French or Russian is found by that name; stop words of English, French, Spanish, German, and Italian ("with", "the", "de", "mit") are not required, and query takes at most 24 words
On a search carrying query or nutrient_filters, each tag value is resolved to its canonical form before it is sent — a brand name is slugged (Nutella → nutella), and a case variant, synonym, or singular resolves where the Open Food Facts vocabulary confirms it (US → en:united-states, en:peanut → en:peanuts); anything unconfirmed is matched exactly, and an empty result names which values were
Numeric nutrient_filters express per-100 g thresholds over energy-kcal, fat, saturated-fat, carbohydrates, sugars, fiber, proteins, salt, and sodium — each a { nutrient, operator, value } triple with lt / lte / gt / gte; pair two entries on one nutrient for a range. They AND with every other filter and are served by the text backend, so supplying one routes the search there even without query
additives_tag filters only on searches carrying neither query nor nutrient_filters — both route to a backend with no additives field, so the pairing is rejected up front rather than silently returning zero hits
Pagination via page (1-based) and page_size (1–50, default 20); tag-only searches are served through page 10, and text searches serve only the first 10,000 results (page * page_size beyond that); a request past either bound is rejected before it is sent, and last_page reports the deepest page that can be requested
total is exact on tag-only searches; text searches stop counting at 10,000 and set total_is_lower_bound: true with the count rendered as 10000+
The two paths read different indexes: a search carrying query is answered by a text index that lags the live database, and says so on both response surfaces; a tag-only search reads the live database. A recently contributed product can be missing from the first and present in the second
sort_by (last_modified_t, unique_scans_n, created_t, popularity_key) orders newest or highest first on both paths; omitting it leaves text searches relevance-ranked
A page past the end of a result set is reported as an exhausted page naming the deepest page that holds products, not as a zero-match search — the broaden-the-filters guidance appears only when nothing matched
Returns summary rows (barcode, name, brand, Nutri-Score, NOVA, categories) — chain to off_get_product for full label data; counts reflect contributed products, not the market. Every returned barcode is one off_get_product accepts: a match Open Food Facts stores under a code it cannot serve (00000636) is left off the page and counted in omitted
Own client-side budget of ~10 requests/min, kept well inside what Open Food Facts asks of clients

`off_compare_products` _tool

Accepts 2–10 barcodes, compared in the order provided
Returns a normalized comparison table: energy (kcal/100g), fat, saturated fat, sugars, salt, protein, fiber, Nutri-Score, NOVA group, and Green-Score; missing nutrition data is preserved as null, never imputed
not_found lists barcodes with no contributor record (not an error — the product may simply not be entered yet)
failed lists barcodes whose fetch itself failed, with a per-barcode reason — kept separate from not_found, and a failed barcode never blocks the rows that did resolve

`off_browse_taxonomy` _tool

Facets categories, labels, allergens, additives, countries resolve live against the Open Food Facts taxonomy (case-insensitive substring match on tag ID, display name, or a common synonym — "shellfish" resolves to en:crustaceans); upstream tags are often plural, so pass the returned id through unchanged. Among the live matches, the tag spelling the term itself ranks first (lentil → en:lentils ahead of en:lentil-soups), so a small limit does not cut it
nova_groups and nutrition_grades are closed vocabularies, returned complete, with bare "1"–"4" / "a"–"e" ids
Live lookups fall back to a small in-process sample when Open Food Facts is unreachable or the budget is spent, and say so rather than failing; omitting search returns only that sample, since Open Food Facts can't enumerate a full facet — no total_in_facet is reported for the open facets
limit controls results (1–100, default 20); there is no offset or page — narrow the search term instead
Own client-side budget of ~10 requests/min, separate from the search budget

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 required — the identifying User-Agent header (required by OFF terms) is baked into the service layer
Token-bucket rate limiting per endpoint class: product reads (~15/min), search (~10/min), taxonomy resolution (~10/min). The product and search defaults are the per-IP ceilings Open Food Facts publishes; lower them on a shared outbound IP. Budgets count upstream requests, so a retried request spends its own slot and a budget exhausted mid-retry surfaces as rate_limited rather than sending. A local refusal says so — it never reports itself as an Open Food Facts rate limit
Automatic retry (4 attempts, 500ms base) for transient failures only — 5xx other than 501, timeouts, and 429 (honoring Retry-After), with HTML error page detection for 503 during high load. The HTTP status decides: a 4xx or a 501 is sent once and never retried, and the upstream's own explanation is surfaced instead — a rendered error page served with a refusal is reported as a refusal, not as load
Nutriments normalized from raw hyphenated keys (energy-kcal_100g) to underscore form — the _100g and _serving variants of every nutrient on the record, with the macros as named fields and the rest in an open map that carries each nutrient's own unit (micronutrients are reported in grams, so calcium 0.071 is 71 mg)
Live tag resolution for off_browse_taxonomy against the Open Food Facts taxonomy, merged behind a small in-process sample that covers offline operation and is authoritative for E-number lookups, which the upstream suggester answers poorly

Agent-friendly output:

Per-serving nutrition always carries its denominator — serving_size as printed plus the parsed serving_quantity/serving_quantity_unit, and an explicit note when Open Food Facts has recorded none
Computed scores (Nutri-Score, NOVA, Green-Score) returned as-is with regional caveat notes — not interpreted or normalized to health claims
Graceful partial failure — off_compare_products returns resolved rows even when others fail, splitting confirmed-missing barcodes into not_found and failed fetches into failed
Every failure carries a declared reason and a recovery hint on both client surfaces — timeouts, upstream outages, upstream rejections, and rate limits each resolve to their own error code and their own next step

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:

json

{
  "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.

json

{
  "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):

json

{
  "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:

json

{
  "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.3.0 or higher (or Node.js v24+).
No API key needed. The server sends an identifying User-Agent to comply with Open Food Facts' terms of service — this is baked in and requires no configuration.

Installation

Clone the repository:

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

Navigate into the directory:

cd openfoodfacts-mcp-server

Install dependencies:

bun install

Configure environment:

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

Configuration

All configuration is validated at startup via Zod schemas in src/config/server-config.ts.

Variable	Description	Default
`OFF_BASE_URL`	Open Food Facts API base URL. Override for local testing against a mock server.	`https://world.openfoodfacts.org`
`OFF_RATE_LIMIT_PRODUCT`	Product read rate limit (requests/min). Matches the 15 req/min/IP Open Food Facts documents for product reads.	`15`
`OFF_RATE_LIMIT_SEARCH`	Search rate limit (requests/min).	`10`
`OFF_RATE_LIMIT_TAXONOMY`	Taxonomy resolution rate limit (requests/min), shared by `off_browse_taxonomy`, tag-value resolution on text searches, and the check on allergen and trace exclusions. A spent budget falls back to the offline sample, or to the tag value as normalized, rather than failing — except that an exclusion it could not check is refused as retryable.	`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`
`LOGS_DIR`	Log file directory (Node.js only).	`<project-root>/logs`
`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 service — live resolution, offline sample, merge and fallback policy for `off_browse_taxonomy`, and tag-value canonicalization for text searches.
`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

Attribution

Open Food Facts data is released under the Open Database License (ODbL) 1.0. Downstream use must cite Open Food Facts.

Contributing

Bugs, feature requests, and documentation gaps all belong in an issue — see CONTRIBUTING.md for the forms, what makes a report actionable, and how to tell a server bug from a framework one. Vulnerabilities go through private disclosure, never a public issue.

Working on the code? Both gates must be green:

bun run devcheck
bun run test

License

Apache-2.0 — see LICENSE for details.

Install

Tools (4)

off_get_productoff_search_productsoff_compare_productsoff_browse_taxonomy

Configuration

Environment variables

OFF_BASE_URLdefault https://world.openfoodfacts.org

Open Food Facts API base URL override. Useful for testing against a mock server.

OFF_RATE_LIMIT_PRODUCTdefault 15

Product read rate limit (requests/min). Matches the 15 req/min/IP Open Food Facts documents for product reads.

OFF_RATE_LIMIT_SEARCHdefault 10

Search rate limit (requests/min).

OFF_RATE_LIMIT_TAXONOMYdefault 10

Taxonomy resolution rate limit (requests/min). Applies to the live tag-vocabulary lookups off_browse_taxonomy makes, to tag-value resolution on text searches, and to checking allergen and trace exclusions on every search; a spent budget falls back to the offline sample, or to the tag value as normalized, rather than failing, except that an exclusion it could not check is refused as retryable.

MCP_LOG_LEVELdefault info

Sets the minimum log level for output (e.g., 'debug', 'info', 'warn').

MCP_TRANSPORT_TYPEdefault http

Selects the HTTP transport.

MCP_HTTP_HOSTdefault 127.0.0.1

The hostname for the HTTP server.

MCP_HTTP_PORTdefault 3010

The port to run the HTTP server on.

MCP_HTTP_ENDPOINT_PATHdefault /mcp

The endpoint path for the MCP server.

MCP_AUTH_MODEdefault none

Authentication mode to use: 'none', 'jwt', or 'oauth'.

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "openfoodfacts-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@cyanheads/openfoodfacts-mcp-server@0.3.7"
      ],
      "env": {
        "OFF_BASE_URL": "https://world.openfoodfacts.org",
        "OFF_RATE_LIMIT_PRODUCT": "15",
        "OFF_RATE_LIMIT_SEARCH": "10",
        "OFF_RATE_LIMIT_TAXONOMY": "10",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

🛠️ Key Features

🚀 Use Cases

⚡ Developer Benefits

⚠️ Limitations

Topics

off_get_product

off_search_products

off_compare_products

off_browse_taxonomy

@cyanheads/openfoodfacts-mcp-server

Overview

Tools

Capability reference

off_get_product tool

off_search_products tool

off_compare_products tool

off_browse_taxonomy tool

Features

Getting started

Public Hosted Instance

Self-Hosted / Local

Prerequisites

Installation

Configuration

Running the server

Local development

Docker

Project structure

Development guide

Attribution

Contributing

License

Install

Configuration

Related servers

`off_get_product` _tool

`off_search_products` _tool

`off_compare_products` _tool

`off_browse_taxonomy` _tool