io.github.cyanheadsPublished by GitHub account cyanheadsv0.2.0Updated Oct 26, 2026
Search foods, compare nutrients, and look up the full USDA FoodData Central database.
Searches the USDA FoodData Central database and returns nutrient profiles, batch lookups and side-by-side food comparisons for an AI assistant.
Web executable via Streamable HTTP. Remote servers run from the web runtime once configured in a workspace.
Paste this prompt into Claude Code, Codex, Cursor or another agent — or into SourceWeft chat. The agent reads this server's install guide, shows you its publisher, endpoint and sign-in, and adds it to your client once you agree. Keys never go into a command.
Read https://sourceweft.com/mcp/io.github.cyanheads%2Fusda-mcp-server/install.md and connect the MCP server it describes to my client. Before changing any config, show me its publisher, endpoint and sign-in method and wait for my OK. Never put an API key in a command or in a file I would commit; ask me where it should come from.Add this to your client's mcpServers config.
{
"mcpServers": {
"usda": {
"type": "http",
"url": "https://usda.caseyjhand.com/mcp"
}
}
}Search foods, compare nutrients, and look up the full USDA FoodData Central database via MCP. STDIO or Streamable HTTP.
Public Hosted Server: https://usda.caseyjhand.com/mcp
Nutrition data for roughly 400,000 foods from USDA FoodData Central, the US government's authoritative food composition database. Search by keyword or UPC, pull full nutrient profiles scaled to any portion, and compare foods side by side.
Food profiles and the nutrient reference are also reachable via tools. Use usda_search_foods to discover FDC IDs before reading food resources.
usda_search_foods tooldataType[] filter across SR Legacy, Foundation, Survey (FNDDS), and Branded, defaulting to ["SR Legacy"] (or ["Branded"] once brandOwner is set)brandOwner and foodCategory filters narrow results; pageSize (max 50, default 10) and pageNumber paginateusda_get_food for other nutrients or the full profiletotalPages returns empty foods[], the requested page, totals, and a notice with a valid pageNumber when the query has matchesquery_empty (blank query), query_syntax (FDC rejected the query syntax), no_results (nothing matched in the requested data sources)usda_get_food toolfdcId; optional nutrients[] filter to specific IDsunit (g / oz / lb / kg / serving) with an optional quantity scales every value from the FDC per-100g basis; quantity defaults to 100 for mass units and 1 for serving. Serving uses the first valid portion, or a positive finite Branded label size in g / GRM / GM (case-insensitive) when no portion exists, multiplied by quantityservingInfo identifies the resolved portion or label serving and its gram weight; allPortions[] contains actual portion definitions onlynot_found (bad FDC ID), quantity_without_unit, no_portion_data (no valid portion or supported Branded gram label). Volume, IU, milligram labels, missing units, and invalid sizes require an explicit mass-unit request; no density is inferredusda_get_foods toolnutrients[] filter strongly recommended — full profiles for 20 foods are largefailed[] instead of aborting the batchusda_compare_foods toolnutrients[] is givenquantity + unit basis (default 100 g; quantity is an amount in unit, so unit: "oz" alone compares per 100 oz)too_few_foods when fewer than 2 resolveusda_list_nutrients toolcategory filter: macronutrients, vitamins, minerals, lipids, amino_acids, othernutrients[] elsewhereusda://food/{fdcId} resourceusda_get_food without portion scaling — full nutrient profile per 100g as application/jsonfdcId must be a bare positive integer (no sign, leading zero, decimal, or exponent); anything else throws invalid_idnot_found when the ID doesn't exist in FDCusda://nutrients resourceusda_list_nutrients with no category filterapplication/json with a 1-hour public cache hint, since the table is bundled at build time and identical for every callerskill://usda-guide/SKILL.md resourceGuidance for matching food records, choosing a serving weight, and reporting incomplete nutrient coverage. The same usda-guide ships with plugin installs, npm, Docker, and the desktop bundle.
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.
FoodData Central-specific:
api.nal.usda.gov/fdc/v1)/foods) with per-food partial failure reportingAgent-friendly output:
dataType) on every food result so callers know whether they're reading curated research data or label-derived branded valuesusda_get_foods, usda_compare_foods) return successes alongside structured failed[] / missingData[] entries rather than failing the whole requestConnect to the hosted instance, no install:
Or run it locally:
For other clients, add this to the MCP config file:
Get a free key at api.data.gov/signup. Food search, lookup, and comparison require it; the static nutrient reference works without it. For Docker or a source build, see Running the server.
See .env.example for the full list of optional overrides.
Requires Bun v1.4.0 or higher (or Node.js v24+).
Build and run:
Run checks and tests:
The image defaults to HTTP transport, stateless session mode, and logs to /var/log/usda-mcp-server. For stdio, use docker run -i --rm -e MCP_TRANSPORT_TYPE=stdio -e USDA_FDC_API_KEY=your-key ghcr.io/cyanheads/usda-mcp-server:latest. To build locally, run docker build -t usda-mcp-server .; OpenTelemetry peer dependencies are installed by default — build with --build-arg OTEL_ENABLED=false to omit them.
See CLAUDE.md for development guidelines and architectural rules. The short version:
try/catch in tool logicctx.log for request-scoped logging, ctx.state for tenant-scoped storagesrc/mcp-server/*/definitions/index.tsIssues are welcome. Run checks and tests before submitting:
Apache-2.0 — see LICENSE for details.
Source: README.md at commit 79679ba
List USDA Nutrients
Look up the FDC nutrient reference table — all tracked nutrients with their numeric IDs, names, SR reference numbers, units, and categories. Use to resolve a nutrient name (e.g. "vitamin C") to its FDC ID (1162) before passing it to the nutrients[] filter on other tools. Filter by category (macronutrients, vitamins, minerals, lipids, amino_acids, or other) to narrow results. The data is static — call once and reuse the IDs.
categorySearch USDA Foods
Search USDA FoodData Central foods by keyword. Returns matching foods with FDC IDs and available preview nutrients: protein (1003), fat (1004), carbohydrate (1005), fiber (1079), and energy (1008, 1062, 2047, 2048), preserving distinct energy estimates. Missing nutrients are omitted. Use the returned fdcId with usda_get_food for other nutrients or the full profile, or usda_compare_foods for side-by-side comparisons. When dataType is omitted, defaults to SR Legacy (common whole foods with complete profiles) — or to Branded when brandOwner is set, since only Branded records carry one. Set dataType to ["Branded"] for packaged products, or include a UPC/GTIN code as the query. Pass brandOwner (e.g. "General Mills") to narrow branded results.
queryrequireddataTypepageSizebrandOwnerpageNumberfoodCategoryGet USDA Food
Get the full nutrient profile for one food by FDC ID. Returns all available nutrients (or a filtered subset via the nutrients[] param) with optional per-portion scaling. Use usda_search_foods to discover FDC IDs. Provide unit, optionally with quantity, to scale all nutrient values from per-100g to that amount (e.g. quantity=200, unit="g" → per-200g values). quantity defaults to 100 for g, oz, lb, and kg and to 1 for serving. Serving uses the first valid portion, or a positive finite Branded label size in g/GRM/GM (case-insensitive) when no portion exists; quantity multiplies that weight. Other label units require an explicit mass-unit request. quantity without unit is rejected. Narrow nutrients[] to specific IDs to reduce response size for focused queries.
unitfdcIdrequiredquantitynutrientsGet USDA Foods (Batch)
Fetch nutrient profiles for 2–20 foods in a single API call. More efficient than calling usda_get_food N times when you already have multiple FDC IDs. All values are per 100g (no portion scaling). Use the nutrients[] filter to limit response size — strongly recommended for batch calls. For side-by-side comparison with a formatted table, use usda_compare_foods instead. Failed IDs (not found or no data) are reported in the failed[] array rather than aborting the entire batch.
fdcIdsrequirednutrientsCompare USDA Foods
Compare nutrients side-by-side for 2–5 foods. Returns a structured table — one row per nutrient, one column per food — formatted as markdown. Best for "spinach vs kale iron" or "which has more protein?" questions. Omit nutrients[] to use the 12 most common defaults (energy, protein, fat, saturated fat, carbs, fiber, sugars, sodium, potassium, calcium, iron, vitamin C); provide nutrients[] with specific FDC IDs to compare different nutrients. All values are scaled to the same basis, quantity in unit: default 100 g, so unit="oz" alone compares per 100 oz and quantity alone is grams. If one or more FDC IDs are not found, the comparison proceeds with the valid foods — only throws too_few_foods when fewer than 2 IDs return data.
unitfdcIdsrequiredquantitynutrients100% of the applicable checks met
How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.
claude mcp add --transport http usda-mcp-server https://usda.caseyjhand.com/mcpclaude mcp add usda-mcp-server -e USDA_FDC_API_KEY=your-key -- npx -y @cyanheads/usda-mcp-server{ "mcpServers": { "usda-mcp-server": { "command": "npx", "args": ["-y", "@cyanheads/usda-mcp-server"], "env": { "USDA_FDC_API_KEY": "your-api-key" } } }}git clone https://github.com/cyanheads/usda-mcp-server.gitcd usda-mcp-server && bun installcp .env.example .env # set USDA_FDC_API_KEY# One-time buildbun run rebuild
# Run the built serverbun run start:stdio# orbun run start:httpbun run devcheck # Lint, format, typecheck, securitybun run test # Vitest test suitebun run lint:mcp # Validate MCP definitions against specdocker run --rm -e USDA_FDC_API_KEY=your-key -p 3010:3010 ghcr.io/cyanheads/usda-mcp-server:latestbun run devcheckbun run test