usda-fdc-mcp

A stdio MCP server that answers food composition questions from USDA FoodData Central.

What it does

The server exposes four tools over the Model Context Protocol.

Tool	Purpose
search_foods	Search foods by name. Returns the FDC ID, description, data type, and a macro-completeness flag.
get_food	Return the nutrient panel for one FDC ID, scaled to a gram amount.
food_nutrition	Search and scale in one call. Prefers a record with a complete macro panel.
recipe_nutrition	Sum an ingredient list into per-serving totals with a per-ingredient breakdown.

FoodData Central reports every amount per 100 g. The server scales each amount to the grams that you request. The percent Daily Value uses the FDA adult values in 21 CFR 101.9.

Nutrient identifiers

FoodData Central gives each nutrient two identifiers. The modern nutrientId for protein is 1003. The legacy NDB nutrientNumber for protein is "203". A filter on the wrong identifier returns an empty nutrient table and no error. The server keys on nutrientId in every code path.

Response shapes

The two endpoints put nutrient values in different fields.

/foods/search  ->  [{ nutrientId: 1003, value: 16.5 }]
/food/{id}     ->  [{ nutrient: { id: 1003 }, amount: 16.5 }]

The server normalizes both shapes. Results from either endpoint are interchangeable.

Alias identifiers

A nutrient can arrive under a different identifier in a different data type. The value then reads as missing. The server resolves three known cases.

• Foundation cashews carry energy as Atwater factors under 2048. The canonical energy identifier is 1008.
• SR Legacy flaxseed carries omega-3 under the general PUFA 18:3 identifier 1270. The ALA-specific identifier is 1404.
• Foundation raisins carry sugars under 1063. SR Legacy records use 2000.

Requirements

• Node.js 20 or later.
• An internet connection for live lookups.
• A FoodData Central API key. Read the API key section below.

Install

npm install
npm run build

Configuration

API key

The server reads the key from the USDA_FDC_API_KEY environment variable. The server falls back to DEMO_KEY when that variable is absent.

DEMO_KEY is the shared key that USDA publishes. It allows about 30 requests per hour for each IP address. Use DEMO_KEY for light testing only.

Get a free personal key at https://fdc.nal.usda.gov/api-key-signup. A personal key allows 1,000 requests per hour.

Pass the key through the environment. Do not commit the key to a file.

Cache

The server writes every response to a disk cache at ~/.cache/usda-fdc-mcp. Set USDA_FDC_CACHE_DIR to move the cache. A cached food still answers after you reach the rate limit.

MCP client

Add the server to your MCP client configuration. Replace /path/to/usda-fdc-mcp with the path to your own clone.

{
  "mcpServers": {
    "usda-fdc": {
      "command": "node",
      "args": ["/path/to/usda-fdc-mcp/dist/index.js"],
      "env": {
        "USDA_FDC_API_KEY": "your_key_here"
      }
    }
  }
}

Usage

A name search can return a neighbouring food

search_foods ranks its results by relevance. It returns a plausible food when the exact food falls outside the result order. It reports no error in that case.

A query for raisins seedless returns golden raisins (168164) before dark seedless raisins (168165). The two records differ by nearly half on iron. Golden raisins hold 0.98 mg per 100 g. Dark seedless raisins hold 1.79 mg per 100 g.

Read the description field on each hit before you use the numbers. Call get_food with a known FDC ID when the exact food matters.

Ingredients that FoodData Central does not hold

FoodData Central holds few supplement powders and few branded products. Pass such an item through manual_items. Take its figures from the product label or from published literature.

{
  "items": [
    { "query": "bananas raw", "grams": 118, "label": "1 medium banana" },
    { "query": "seeds hemp seed hulled", "grams": 30 }
  ],
  "manual_items": [
    { "label": "whey isolate, 1 scoop", "nutrients": { "energy_kcal": 120, "protein_g": 30 } }
  ],
  "servings": 1
}

Source citation

Every get_food result carries a source string.

USDA FoodData Central, FDC ID 170554 (SR Legacy), https://fdc.nal.usda.gov/food-details/170554

Quote that string when you publish a nutrition figure. The figure then stays traceable to its source record.

Tests

Run the offline test. It needs no network access and no API quota.

npm test

The offline test replays four cached FoodData Central records from test/fixtures. It asserts that each alias case resolves to the correct number.

Run the smoke test to check the live API contract. It consumes API quota.

npm run smoke

The smoke test confirms that both endpoint shapes parse to the same numbers. It confirms that gram scaling is linear. It confirms that the percent Daily Value and the source string are populated.

Development

npm run dev     # run the server from source through tsx
npm run build   # compile TypeScript into dist/
npm start       # run the compiled server

Licence

Licensed under the PolyForm Noncommercial License 1.0.0. Copyright 2026 Seraphine Renard.