Skip to main content
Glama
Nutriscan MCP connector

Nutriscan MCP connector

by si-essence

nutriscan-mcp (Nutriscan MCP connector)

MCP server for packaged foods from Open Food Facts and generic foods from USDA FoodData Central, plus a local meal log. TypeScript, official @modelcontextprotocol/sdk, stdio + Streamable HTTP.

Setup

npm install && npm run build
export NUTRISCAN_CONTACT=you@example.com   # optional; sent in the Open Food Facts User-Agent
export USDA_API_KEY=your_data_gov_key      # optional; omit to use the shared DEMO_KEY
npm start                                  # stdio
npm run start:http                         # Streamable HTTP at http://localhost:3000/mcp (PORT to change), /health
npm test                                   # mocked tests, no network and no key
npm run live-check                         # one real barcode, one real search, one USDA DEMO_KEY search

Claude Desktop / any stdio client:

{
  "mcpServers": {
    "nutriscan": {
      "command": "node",
      "args": ["/workspace/connectors/nutriscan/dist/index.js"],
      "env": { "USDA_API_KEY": "...", "NUTRISCAN_CONTACT": "you@example.com" }
    }
  }
}

Docker: docker build -t nutriscan . && docker run -p 3000:3000 -e USDA_API_KEY=... -v nutriscan-data:/data nutriscan

HTTP mode has no authentication. Keep it on localhost.

Related MCP server: Food Tracker MCP Server

Tools

Tool

What it returns

barcode_lookup

One Open Food Facts product by EAN-8, UPC-A, or EAN-13: name, brand, Nutri-Score, NOVA, allergens, additives, nutrients per 100 g

product_search

Full-text name search (barcode, name, brand, Nutri-Score, NOVA). Optional brand and country

allergens_additives

Allergens, traces, E-numbers, and a short ingredients line for one barcode

nutriscore_nova

Nutri-Score letter (A best, E worst) and NOVA group (1–4), each with a one-line meaning

nutrients_per_serving

Nutrients scaled to one label serving, servings, or grams

usda_food_search

USDA FoodData Central search: fdcId, description, data type, nutrients per 100 g, sodium in mg

compare_products

Two barcodes side by side per 100 g. barcode_a / barcode_b come back as a / b

meal_log_add

Append one food to the local JSON log. A barcode snapshots nutrients for the amount eaten

meal_log_list

Newest local entries. Optional UTC date and limit

meal_log_day_total

Sum of one UTC day. Entries without nutrients are counted and not added

A 12-digit UPC that is missing is retried once as an EAN-13 with a leading zero. Nutri-Score or NOVA being absent is not an error. These tools are not medical or dietary advice. A lower nutrient number is not always the better choice (protein and fiber often are desirable).

Environment

Variable

Default

Role

NUTRISCAN_CONTACT

contact@example.com

Contact in the User-Agent Nutriscan/0.1 (<contact>)

USDA_API_KEY

DEMO_KEY

FoodData Central key. Never printed or returned

NUTRISCAN_DATA_DIR

./data

Directory for meals.json (relative to the process working directory)

NUTRISCAN_OFF_SEARCH_PER_MINUTE

10

Local cap on Open Food Facts searches

NUTRISCAN_OFF_PRODUCT_PER_MINUTE

100

Local cap on Open Food Facts product reads

USDA_HOURLY_LIMIT

30 with DEMO_KEY, else 1000

Local USDA hourly cap

USDA_DAILY_LIMIT

50 with DEMO_KEY, else 100000

Local USDA daily cap (resets 00:00 UTC)

NUTRISCAN_OFF_BASE_URL

https://world.openfoodfacts.org

Product and search host

NUTRISCAN_USDA_BASE_URL

https://api.nal.usda.gov/fdc/v1

FoodData Central host

MCP_TRANSPORT

stdio, or http

Same as --http

PORT

3000

HTTP listen port

DEMO_KEY is a shared example key: about 30 requests per hour and 50 per day per IP. Sign up for a free key at https://fdc.nal.usda.gov/api-key-signup (about 1,000 requests per hour). The key is sent only as the api_key query parameter and is stripped from errors.

Caching and rate limits

  • In-memory TTL cache: product reads 1 hour, Open Food Facts search 10 minutes, USDA search 24 hours. A cache hit does not spend quota. The cache resets when the process restarts.

  • Open Food Facts product reads (barcode, allergens, Nutri-Score, nutrients, compare, and a meal log that passes a barcode) share one budget, default 100 per minute. Searches have a separate budget, default 10 per minute.

  • Open Food Facts documents its own platform caps (about 10 searches per minute, and a lower per-IP cap on product reads, recently described as about 15 per minute). Exceeding the platform cap can get an IP blocked. For unattended use, set NUTRISCAN_OFF_PRODUCT_PER_MINUTE=15.

  • Product reads use GET /api/v2/product/{barcode} with a fields list so the response stays small. Name search uses the full-text search endpoint GET /cgi/search.pl (search_terms, json=1) because API v2 search does not accept free-text search_terms. If that endpoint returns HTTP 502 or 503, the same search is sent once to Search-a-licious at https://search.openfoodfacts.org/search.

  • USDA calls are capped locally to the demo limits when the key is DEMO_KEY, and to about 1,000 per hour otherwise. When a limit is hit, the tool returns isError with a [rate-limit] message and a retry hint. Cached data is still served.

  • Every Open Food Facts request sends User-Agent: Nutriscan/0.1 (<contact>).

Meal log

meal_log_add, meal_log_list, and meal_log_day_total read and write { "entries": [ ... ] } at $NUTRISCAN_DATA_DIR/meals.json. Dates are UTC. Nothing is uploaded. A barcode stores a snapshot of the nutrients for the grams eaten, so later edits on Open Food Facts do not change history. Entries without a barcode are listed but left out of the nutrient sum (withoutNutrients). The file is capped at 5,000 entries. Invalid JSON is reported and not overwritten.

Attribution and licenses

Data from Open Food Facts (openfoodfacts.org), available under the ODbL.

The Open Food Facts database is under the Open Database License (ODbL). Database contents are under the Database Contents License. The ODbL is share-alike: if you publish a database derived from Open Food Facts data, that database must be released under the ODbL as well. Looking up products through this server does not by itself publish a database. Product images on Open Food Facts are under CC-BY-SA and are not returned here. Do not use the Open Food Facts name or logo to imply that Open Food Facts endorses this project. Product names and pack shots belong to their owners.

USDA FoodData Central data are in the public domain under CC0 1.0. Please cite: U.S. Department of Agriculture, Agricultural Research Service. FoodData Central, 2019. fdc.nal.usda.gov.

License

MIT, see LICENSE. This is an independent, unofficial connector and is not endorsed by the Nutriscan project or its owners.

Available Tools

10 tools
allergens_additivesA
Read-only

List allergens, may-contain traces, and additives (E-numbers) for one Open Food Facts product by barcode, plus a short ingredients line. Use for allergy and ingredient questions.

Inputs: barcode (required).

barcode_lookupA
Read-only

Look up one packaged food on Open Food Facts by barcode (EAN-8, UPC-A, or EAN-13). Returns name, brand, quantity, Nutri-Score, NOVA group, allergens, additives, and key nutrients per 100 g. Use when the user has a barcode. For a name, use product_search.

Inputs: barcode (required).

compare_productsA
Read-only

Compare two Open Food Facts products by barcode on nutrients per 100 g, Nutri-Score, NOVA, and allergens. barcode_a and barcode_b are returned as a and b. Says which side is numerically lower. A lower number is not always better (protein and fiber are often desirable). Not dietary advice.

Inputs: barcode_a (required), barcode_b (required).

meal_log_addA

Append one eaten food to the local meal log (a JSON file on disk; nothing is uploaded). Pass a barcode to snapshot Open Food Facts nutrients, plus grams or servings. Without a barcode, pass a name and grams (nutrients are then omitted from totals). Optional meal slot and UTC date (YYYY-MM-DD).

Inputs: date, meal, name, note, +3 more.

meal_log_day_totalA
Read-only

Sum energy and key nutrients for one UTC day in the local meal log. Entries logged without nutrients are counted separately and are not added into the totals. Optional date (YYYY-MM-DD), default today UTC.

Inputs: date.

meal_log_listA
Read-only

List entries in the local meal log, newest first. Optional UTC date (YYYY-MM-DD) and limit. Does not call Open Food Facts or USDA.

Inputs: date, limit.

nutrients_per_servingA
Read-only

Energy and key nutrients for one Open Food Facts product, scaled from per-100 g data to one label serving, a number of servings, or a gram amount. Pass grams when the product has no serving size. Salt is in grams. If both grams and servings are set, grams wins.

Inputs: barcode (required), grams, servings.

nutriscore_novaA
Read-only

Return the Nutri-Score letter (A best to E worst) and NOVA processing group (1 minimally processed to 4 ultra-processed) for one barcode, each with a one-line meaning. Missing scores are null, not an error. Not medical or dietary advice.

Inputs: barcode (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.8/5.0

    Scored across 10 tools

    Disambiguation4/5

    Each tool targets a distinct action/resource, and descriptions explicitly disambiguate the closest pairs (product_search for names vs barcode_lookup for barcodes; barcode_lookup for per-100 g tables vs nutrients_per_serving for scaled values). The only mild overlaps are barcode_lookup vs nutriscore_nova/allergens_additives, which return subsets of the same product data but are clearly scoped by purpose.

    Naming Consistency3/5

    All names are snake_case and mostly follow a noun-first-with-verb-suffix pattern (product_search, barcode_lookup, meal_log_add, meal_log_list), with domain prefixes grouping meal_log_* tools nicely. However, compare_products is verb-first while everything else is noun-first, and several tools (nutrients_per_serving, allergens_additives, nutriscore_nova) are noun phrases with no verb at all, so the pattern is readable but not uniform.

    Tool Count5/5

    Ten tools is well within the ideal range and each one earns its place: three lookup/search entry points, three nutrient-analysis tools, three meal-log tools, and one comparison tool. No obviously redundant or filler tools.

    Completeness3/5

    The read side is thorough (name search, barcode lookup, USDA fallback, nutrients, scores, allergens, comparison), and meal logging covers add/list/day-total. But the meal log has no delete, update, or clear operation, so a mistakenly logged entry is a permanent dead end that will skew day totals — a notable lifecycle gap.

    Maintenance

    ActivityMaintained
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Provides access to a comprehensive food database with 300,000+ items, enabling nutritional data lookups, food searches, and barcode scanning with all processing happening locally for privacy and speed.
      211
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables tracking food intake and nutrition using the USDA FoodData Central database. Supports logging meals, setting daily nutrition goals, viewing food diaries, and analyzing nutrition trends over time with local SQLite storage.
      7 npm
      1
      MIT