usda-fdc-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., "@usda-fdc-mcp Calculate the total calories and protein for a recipe with rice, beans, and avocado."
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.
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 by name. Returns the FDC ID, description, data type, and a macro-completeness flag. |
| Return the nutrient panel for one FDC ID, scaled to a gram amount. |
| Search and scale in one call. Prefers a record with a complete macro panel. |
| 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 is1008.SR Legacy flaxseed carries omega-3 under the general PUFA 18:3 identifier
1270. The ALA-specific identifier is1404.Foundation raisins carry sugars under
1063. SR Legacy records use2000.
Related MCP server: nutrition-mcp
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 buildConfiguration
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/170554Quote 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 testThe 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 smokeThe 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 serverLicence
Licensed under the PolyForm Noncommercial License 1.0.0. Copyright 2026 Seraphine Renard.
Available Tools
4 toolsfood_nutritionLook up a food by name and scale it in one stepA
Search by name, pick the best match with a complete macro panel, and return its nutrients scaled to the given grams. Use this for ordinary 'how much magnesium is in 30g of pumpkin seeds' questions. Also returns runner-up matches so you can correct the choice.
Inputs: query (required), grams, data_types.
get_foodGet a food's nutrients scaled to a servingA
Full nutrient panel for one fdcId, scaled from FDC's per-100g basis to the grams you ask for, with %DV against FDA adult Daily Values. Includes a citable source line.
Inputs: fdc_id (required), grams.
recipe_nutritionSum an ingredient list into per-serving nutritionA
Give an ingredient list as {query or fdc_id, grams} and get summed totals divided by servings, with %DV and a per-ingredient breakdown of who contributed what. Ingredients absent from FDC (supplement powders, branded products) can be passed in manual_items with nutrients already known.
Inputs: items (required), servings, manual_items.
search_foodsSearch USDA FoodData CentralA
Find foods by name in USDA FoodData Central. Returns fdcId, description, dataType, and hasCoreMacros. Prefer entries where hasCoreMacros is true: Foundation records are analytically detailed but frequently omit Energy, while SR Legacy records carry a complete macro panel. Cached on disk.
Inputs: query (required), page_size, data_types.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
Each tool has a distinct role: get_food for known IDs, search_foods for discovery, food_nutrition for a name-based shortcut with nutrients, and recipe_nutrition for multi-ingredient calculations. However, the overlap between food_nutrition and search_foods/get_food could cause some initial confusion, but descriptions clarify the intended use.
Names mix verb_noun (get_food, search_foods) and noun_noun (food_nutrition, recipe_nutrition) patterns, which is inconsistent and less predictable. The mixed conventions make it harder to infer a tool's function from its name alone.
Four tools is well-scoped for a USDA food data server, covering search, ID-based lookup, convenience queries, and recipe analysis. Each tool earns its place without unnecessary bloat.
The surface covers the core workflow of finding a food, retrieving its nutrients, and combining foods into recipes. For a read-only database, there are no obvious gaps or dead ends.
Maintenance
Related MCP Connectors
Unlock the power of food transparency with our Open Food Facts MCP server. Easily look up any food
USDA FoodData Central nutrient lookup, FDA recall watch, EU FMCG labelling via remote MCP
Unofficial Edamam MCP — wraps three Edamam APIs in one pack: - Nutrition Analysis API…
MCP server exposing supplements database used by iNutriPlan.com
Related MCP Servers
- AlicenseAqualityBmaintenanceAn MCP server for the Open Food Facts API that allows users to search, read, and contribute to a global food database. It enables looking up nutrition data by barcode or name and managing product information through natural language.10341 npm4MIT
- AlicenseAqualityCmaintenanceMCP server for USDA nutrition data lookup, meal logging, and daily macro tracking.3MIT
- AlicenseNot gradedqualityDmaintenanceProvides access to USDA FoodData Central database, enabling food search, nutrition details, and comparison for dietary analysis via MCP.5MIT
- 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