openfoodfacts-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@openfoodfacts-mcp How many calories in a Sainsbury's buffalo chicken wrap?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
openfoodfacts-mcp
MCP server for the Open Food Facts API - search, read, and contribute to the world's largest open food database.
Use Cases
Look up a product by name: "How many calories in a Sainsbury's buffalo chicken wrap?" -> searches by name, finds the product, and returns nutrition data.
Look up a product by barcode: "What's in this product with barcode 3017620422003?" -> fetches Nutella's ingredients, Nutri-Score, and nutrition data.
Find healthy options: "Search for breakfast cereals with Nutri-Score A" -> searches with category and nutrition grade filters.
Contribute data: "Add the product name and brand for barcode 12345678" -> creates or updates a product entry on Open Food Facts.
Explore the database: "What brands of organic chocolate are in the database?" -> uses autocomplete and search to explore.
Related MCP server: Meals MCP Server
Setup
Follow the instructions on install-mcp, which generates the right config for your MCP client (Claude Code, Claude Desktop, Cursor, Cline, VS Code, and more).
Set OFF_USER_AGENT to identify your app (e.g. openfoodfacts-mcp/1.2.0 (you@example.com)). For write operations (adding/editing products, uploading images), also set OFF_USER_ID and OFF_PASSWORD.
Environment Variables
Variable | Required | Description |
| Yes | User-Agent string, e.g. |
| No | Open Food Facts username (for write operations) |
| No | Open Food Facts password (for write operations) |
| No | Country subdomain (default: |
Tools
Tool | Description | Auth |
| Get product info by barcode | No |
| Search with structured filters (brand, category, Nutri-Score) | No |
| Search with Lucene syntax, negation, and boolean logic | No |
| Autocomplete brands, categories, labels, etc. | No |
| Add or update a product | Yes |
| Upload a product image | Yes |
| Select, crop, and rotate an image | Yes |
| Call any OFF API endpoint directly | Depends |
| Get OFF API documentation | No |
Contributing
Pull requests are welcomed on GitHub! To get started:
Install Git and Node.js
Clone the repository
Install dependencies with
npm installRun
npm run testto run testsBuild with
npm run build
Releases
Versions follow the semantic versioning spec.
To release:
Use
npm version <major | minor | patch>to bump the versionRun
git push --follow-tagsto push with tagsWait for GitHub Actions to publish to the NPM registry.
Available Tools
10 toolsadd_or_edit_productAdd or edit productA
Add a new product or edit an existing one on Open Food Facts. Requires OFF_USER_ID and OFF_PASSWORD.
The more fields you fill, the more useful the entry. At minimum provide product_name, brands, and categories — these feed the search index, and a sparse entry won't be findable. If you have a photo of the pack, transcribe everything you can read: ingredients, nutrition, origins, traceability stamps, recycling icons, certifications.
Fields that drive derived data:
ingredients_text → allergens, additives, NOVA group, fruit/veg %
nutrition + categories → Nutri-Score
packagings + origins → Eco-Score
product_name + brands + categories + labels → search _keywords
Pitfalls learned the hard way:
Free-text packaging shapes get fuzzy-matched against the taxonomy. "Pouch" resolves to "en:pouch-flask" (a stand-up spouted pouch). Use taxonomy IDs like "en:bag" or "en:individual-bag" instead.
OFF has no generic "pouch" shape in its taxonomy. For vacuum-sealed individual portions use "en:individual-bag"; for plastic film wrap use "en:film".
Recommended workflow for adding a product from photos:
Check if product exists with get_product first to avoid overwriting good data
Upload photos with upload_image. Prefer more photos over fewer — panels with text (ingredients, nutrition, certifications, recycling instructions) are highest value as OFF can OCR them. Plain sides with just a colour or logo are lowest value but still worth uploading if you have them. Use the most appropriate imagefield (front, ingredients, nutrition, packaging) and "other" for the rest.
Call this tool with all fields you can read from the photos. Set both quantity and serving_size.
Set packagings_complete: true only when all packaging components are listed
For products with only prepared nutrition (jelly mixes, powdered drinks, etc.), use nutrition_prepared instead of nutrition. For values printed as "< 0.5g" on the packet, pass the string "< 0.5" — the less-than modifier will be preserved.
Nutrition fields mirror the label columns: nutrition (per 100g as sold), nutrition_per_serving (per serving as sold), nutrition_prepared (per 100g prepared), nutrition_prepared_per_serving (per serving prepared). OFF auto-derives per-serving from per-100g + serving_size, so nutrition_per_serving is only needed when the label shows explicit per-serving values you want to preserve.
Inputs: barcode (required), brands, labels, stores, +22 more.
autocompleteAutocompleteARead-only
Get autocomplete suggestions for Open Food Facts taxonomy entries (brands, categories, labels, etc.).
Inputs: query (required), tagtype (required), lc, limit.
call_apiCall APIA
Make a direct call to any Open Food Facts API endpoint. Use get_api_docs to see available endpoints. Auth credentials are included automatically for write operations if configured.
Two body modes for writes:
params: form-encoded (for /cgi/.pl and /api/v2/ legacy endpoints)
json_body: raw JSON (for /api/v3/* endpoints — required for structured fields like packagings)
Example v3 packagings write: method: PATCH endpoint: /api/v3/product/0123456789012 json_body: {"fields":"packagings","product":{"packagings":[{"number_of_units":1,"shape":{"id":"en:bag"},"material":{"id":"en:plastic"},"recycling":{"id":"en:recycle"}}]}}
WARNING: Do NOT use old-style prepared nutrition params like nutriment_fat_prepared — they have a known server bug that stores data incorrectly. Use new-style params instead: nutrition_input_sets_prepared_100g_nutrients_fat_value_string=0.5
Inputs: endpoint (required), method, params, json_body.
get_api_docsGet API docsARead-only
Get Open Food Facts API documentation. Useful for understanding available endpoints before using call_api.
Inputs: no named parameters.
get_productGet productARead-only
Get product information from Open Food Facts by barcode. Reads the primary database directly (no sync lag), so this is always current even when search_products returns stale results. Prefer this over search whenever you have a barcode. If this returns "product not found", the product genuinely isn't in the database — you can add it with add_or_edit_product.
Inputs: barcode (required), fields, language.
get_skillGet skillARead-only
Get the OFF upload skill document. This describes the recommended process for bulk uploading food packaging photos to Open Food Facts.
Inputs: no named parameters.
search_products_luceneSearch products (Lucene)ARead-only
Search Open Food Facts using the Search-a-licious Elasticsearch backend. Powered by Lucene query syntax with full boolean logic and negation support.
Use this instead of search_products_standard when you need:
Negation queries: find gluten-free cereals with allergens_tags_without="en:gluten"
Filter-only browsing: categories_tags without any text query (standard API times out on this)
Combined text + filter with relevance scoring: text matches are ranked by relevance within filter results
Boolean logic in raw Lucene: brands:"kellogg*" OR brands:"nestle"
Trade-offs vs search_products_standard:
Counts are approximate (capped at 10,000 for large result sets)
Brand tag matching may be narrower (less normalization than standard)
Data has a short sync delay (hours) from the primary database
popularity sort uses scan counts rather than the standard popularity algorithm
Response format matches search_products_standard: { count, page, page_size, page_count, products: [...] }
Inputs: page, query, fields, sort_by, +9 more.
search_products_standardSearch products (standard)ARead-only
Search Open Food Facts with structured filters. Best for simple keyword queries and brand/category filtering. Returns exact result counts and well-populated products. If you have a barcode, use get_product instead.
How search works: strict AND against a keyword index built from product_name, generic_name, brands, categories, origins, labels. One unmatched query word → zero results.
Tips:
Prefer 2-3 distinctive words over the full product name
Put brand names in brands_tags, not the query text
Brand normalization is generous: "sainsburys", "sainsbury's", "sainsbury-s" all match
For fresh produce, use brands_tags + categories_tags rather than text search
sort_by=popularity works well here (not supported in search_products_lucene)
If you get zero results, try dropping words or using search_products_lucene which has more flexible text matching.
Inputs: page, query, fields, sort_by, +4 more.
select_imageSelect/crop product imageA
Select, crop, and rotate a previously uploaded product image on Open Food Facts. Requires OFF_USER_ID and OFF_PASSWORD.
Inputs: imgid (required), barcode (required), imagefield (required), lc, +5 more.
upload_imageUpload product imageA
Upload a product image to Open Food Facts. Requires OFF_USER_ID and OFF_PASSWORD.
Prefer more photos over fewer. Panels with text (ingredients, nutrition, certifications, recycling instructions) are highest value as OFF can OCR them. Plain sides with just a colour or logo are lowest value but still worth uploading if you have them.
Use the most appropriate imagefield (front, ingredients, nutrition, packaging). Use "other" for additional photos — this uploads without selecting the image as a display image, which is useful when a good display image already exists or for supplementary angles.
The OFF server auto-selects images for front/nutrition/ingredients/packaging on upload unless one is already selected. If you get "status not ok" but a positive imgid, the image uploaded successfully but was not selected (e.g. a display image already exists).
For images on disk, base64-encode them first (e.g. via shell: base64 -i photo.jpg).
Inputs: barcode (required), image_data (required), imagefield (required), lc.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 10 tools
Most tools are clearly distinct (get vs search vs upload vs select), and the two search tools are explicitly differentiated by use case. However, add_or_edit_product vs upload_image and select_image overlap in the product-editing workflow, and call_api could be confused with get_api_docs or even the search tools for advanced users. Minor ambiguity but generally resolvable.
There's a reasonable pattern with verb_noun names (add_or_edit_product, get_product, upload_image, select_image), but 'autocomplete' and 'call_api' break the convention. Also search_products_standard vs search_products_lucene are verbose while others are concise.
10 tools for a food database MCP server is well-scoped, covering search, product management, and image handling. Though the list provided shows 8 tools, the count of 10 is still reasonable. Some tools like get_api_docs and get_skill are meta/helper tools but not excessive.
Core workflows are covered: search, get, add/edit, image upload/selection, plus a generic API escape hatch. Missing delete/obsolete operations and more granular taxonomy lookups, but the call_api and get_api_docs tools mitigate most gaps.
Maintenance
Related MCP Connectors
Unlock the power of food transparency with our Open Food Facts MCP server. Easily look up any food
MCP server for real-time product search by barcode (EAN, UPC, GTIN) or keyword on ean-search.org
Nutrition MCP — wraps Open Food Facts API (free, no auth)
Unofficial Edamam MCP — wraps three Edamam APIs in one pack: - Nutrition Analysis API…
Related MCP Servers
- AlicenseAqualityDmaintenanceMCP server for Open Food Facts, enabling food product lookup by barcode, search, nutrition facts, allergen checks, and eco-scores without an API key.8MIT
- FlicenseNot gradedqualityDmaintenanceMCP server for discovering and retrieving meal recipes from TheMealDB API, enabling search, random meals, category/ingredient filtering, and full recipe details.-
- FlicenseNot gradedqualityDmaintenanceAn MCP server for food-related queries powered by MiniMax AI, enabling natural language interaction via a chat API.-
- AlicenseNot gradedqualityBmaintenanceLook up food products by barcode, search by ingredient or nutrition filter, compare products side-by-side, and browse the canonical tag vocabulary via MCP.144 npm2Apache 2.0