Usda Mcp Server

cyanheads/usda-mcp-server

Wraps the USDA FoodData Central API with five tools for searching foods, fetching full nutrient profiles, batch lookups, side-by-side comparisons, and a static nutrient reference table. Search spans SR Legacy whole foods and branded products, including UPC lookup. The get_food tool returns full profiles with optional portion scaling in grams, ounces, pounds, or servings. Batch operations report partial failures instead of aborting when some IDs are missing. Compare_foods returns a markdown pivot table with values scaled to a common basis. Built on the author's mcp-ts-core framework with unified error handling and both stdio and streamable HTTP transports. Requires a free FoodData Central API key.

GitHub stars: 1
tools: 5
auth: Required
transport: STDIO, HTTP
env vars: 8
last updated: Nov 11, 2026

View on GitHub

Install

From registry metadata

$ npx add-mcp https://usda.caseyjhand.com/mcp --name usda

Run in your terminal. add-mcp asks which agents to add it to (Claude Code, Codex, Cursor and more). Add -g to install it for every project.

Review the command, arguments and environment values before installing. MCP servers run with your local permissions.

Other ways

Claude Code

$ claude mcp add --transport http usda https://usda.caseyjhand.com/mcp

Run in your terminal. Add --scope user to make it available in every project.

Tools

Verified live · 5 tools

Verified live against the running server on Nov 6, 2026.

usda_list_nutrientsLook 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. Filte...1 params

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. Filte...

Parameters* required

categorystring

Filter to a nutrient category. Omit to return all ~150 tracked nutrients. Options: macronutrients, vitamins, minerals, lipids, amino_acids, other.one of macronutrients · vitamins · minerals · lipids · amino_acids · other

usda_search_foodsSearch 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 o...6 params

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 o...

Parameters* required

brandOwnerstring

Filter branded results by brand owner name (e.g. "General Mills", "Kraft"). Only Branded records carry one, so setting this defaults dataType to ["Branded"] unless dataType is given explicitly.

dataTypearray

FDC data sources to search. Omitting this defaults to ["SR Legacy"] (common whole foods, complete nutrient profiles), or to ["Branded"] when brandOwner is set. Include "Branded" for packaged produc...

foodCategorystring

Filter by USDA food category (e.g. "Poultry Products", "Vegetables and Vegetable Products"). Case-sensitive.

pageNumberinteger

Page number (1-based). Use with totalPages to paginate. Pages past the end return empty foods with a notice when the query has matches.default: 1

pageSizeinteger

Number of results per page. Default 10, maximum 50.default: 10

query*string

Search terms — food name, ingredient, or UPC/GTIN code for branded products. Examples: "chicken breast raw", "banana", "012345678901". FDC reads Lucene syntax: "quoted phrases", +required and -excl...

usda_get_foodGet 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 va...4 params

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 va...

Parameters* required

fdcId*integer

FDC ID of the food. Use usda_search_foods to discover IDs.

nutrientsarray

Filter to specific nutrient IDs (e.g. [1003, 1004, 1005, 1008] for protein, fat, carbs, energy). Use usda_list_nutrients to look up IDs. Omit to return all available nutrients.

quantitynumber

Amount of food, in unit, to scale nutrient values to. Must be positive. Requires unit. Defaults to 100 when unit is g, oz, lb, or kg, and to 1 when unit is "serving". Omit both quantity and unit fo...

unitstring

Unit for quantity. "serving" uses the first valid portion weight, or a Branded label size in g/GRM/GM (case-insensitive) when no portion exists, multiplied by quantity. Required when quantity is pr...one of g · oz · lb · kg · serving

usda_get_foodsFetch 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 bat...2 params

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 bat...

Parameters* required

fdcIds*array

FDC IDs to fetch — 2 to 20 IDs. Use usda_search_foods to discover IDs.

nutrientsarray

Filter to specific nutrient IDs (e.g. [1003, 1004, 1005, 1008]). Strongly recommended — full profiles can be large. Use usda_list_nutrients to look up IDs.

usda_compare_foodsCompare 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, pr...4 params

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, pr...

Parameters* required

fdcIds*array

FDC IDs to compare — 2 to 5 foods. Use usda_search_foods to discover IDs.

nutrientsarray

Nutrient IDs to include in the comparison. Defaults to the 12 most common: energy (1008), protein (1003), total fat (1004), saturated fat (1258), carbohydrate (1005), fiber (1079), total sugars (20...

quantitynumber

Amount of food, in unit, that every value is scaled to. Must be positive. Default 100.default: 100

unitstring

Unit for quantity. Default "g". Does not support "serving" (each food's portion weight differs, so a serving basis would not compare equal amounts).one of g · oz · lb · kgdefault: g

Configuration

USDA_FDC_API_KEY*

USDA FoodData Central API key from data.gov. Required for all food data requests.

USDA_CLAMP_LIMITSdefault: true

When true, usda_get_foods fetches the first 20 distinct FDC IDs of a larger request and returns the rest as deferredIds; false rejects a request with more than 20 IDs.

MCP_LOG_LEVELdefault: info

Sets the minimum log level for output (e.g., 'debug', 'info', 'warn').

MCP_TRANSPORT_TYPEdefault: http

Selects the HTTP transport.

MCP_HTTP_HOSTdefault: 127.0.0.1

The hostname for the HTTP server.

MCP_HTTP_PORTdefault: 3010

The port to run the HTTP server on.

MCP_HTTP_ENDPOINT_PATHdefault: /mcp

The endpoint path for the MCP server.

MCP_AUTH_MODEdefault: none

Authentication mode to use: 'none', 'jwt', or 'oauth'.