# usda-mcp-server [Health: Active]

**Category:** 🗄️ Databases  
**Repository:** https://github.com/cyanheads/usda-mcp-server  
**GitHub Stars:** 1  
**npm Downloads (last month):** 1085  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/usda-mcp-server

## Description
Search foods, compare nutrients, and look up the full USDA FoodData Central database.

## Tools
Capabilities this server exposes over MCP:

- **usda_list_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.
- **usda_search_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.
- **usda_get_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.
- **usda_get_foods** — 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.
- **usda_compare_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.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "usda-mcp-server": {
    "command": "npx",
    "args": ["-y","@cyanheads/usda-mcp-server"],
    "env": {
      "USDA_FDC_API_KEY": ""
    }
  }
}
```

**Requires environment variables:** `USDA_FDC_API_KEY` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What usda-mcp-server does

usda-mcp-server brings USDA FoodData Central into MCP-compatible clients. The service covers roughly 400,000 food records from SR Legacy, Foundation, Survey (FNDDS), and Branded sources. Agents can search by food terms, ingredient names, or UPC/GTIN values; inspect a food's nutrient profile; retrieve several records together; and generate a side-by-side comparison.

The server also includes a bundled reference catalog of about 150 nutrients. Each entry includes its FDC identifier, name, unit, SR reference number, and category. This catalog helps an agent translate a nutrient name into the IDs accepted by the other tools.

## How it works

The server uses the USDA FoodData Central REST API at `api.nal.usda.gov/fdc/v1`. Search results include FDC IDs and a preview of common nutrients, while full records are available through the single-food tool or the `usda://food/{fdcId}` resource. The nutrient catalog is bundled with the server, so listing nutrients does not require an API request.

FoodData Central stores values on a per-100-gram basis. `usda_get_food` can convert those values to grams, ounces, pounds, kilograms, or a serving quantity. Serving resolution uses a valid food portion first, with a supported Branded gram-based label serving as a fallback. Comparisons normalize foods to one shared quantity and unit, and batch operations report failed IDs separately when some records cannot be returned.

Three resources are available: `usda://food/{fdcId}` for an unscaled JSON food profile, `usda://nutrients` for the complete nutrient dictionary, and `skill://usda-guide/SKILL.md` for guidance on selecting food records, choosing serving weights, and handling incomplete nutrient coverage.

## Setup and configuration

The package can run over STDIO or Streamable HTTP. A USDA FoodData Central API key is required through the `USDA_FDC_API_KEY` environment variable. The project publishes an npm package, a Docker image, a desktop bundle, and a hosted MCP endpoint at `https://usda.caseyjhand.com/mcp`.

MCP client installation links are provided for Claude Desktop, Cursor, and VS Code. For local package execution, the documented client configurations use `npx` with the `@cyanheads/usda-mcp-server` package. Transport, authentication, and storage options are supplied by the underlying MCP core framework, including `none`, JWT, or OAuth authentication and in-memory, filesystem, Supabase, or Cloudflare-backed storage where applicable.

## Tools and capabilities

- `usda_search_foods` searches by keyword, ingredient, or UPC/GTIN. It supports source, brand-owner, category, page-size, and page-number filters, with up to 50 results per page.
- `usda_get_food` returns one complete profile, optionally restricted to nutrient IDs and scaled to a mass unit or serving.
- `usda_get_foods` fetches 2–20 FDC IDs in one request. Results remain per 100 grams and can include a `failed` list for IDs without data.
- `usda_compare_foods` compares 2–5 foods in a Markdown table. It defaults to 12 common nutrients and continues with valid records when some IDs fail.
- `usda_list_nutrients` returns the static nutrient reference and can filter by macronutrients, vitamins, minerals, lipids, amino acids, or other nutrients.

Search defaults to SR Legacy unless a source is selected, or to Branded when `brandOwner` is supplied. Full profiles and comparisons preserve source information so callers can distinguish curated records from label-derived branded data.

## Limitations and notes

Portion scaling requires a supported mass unit or a valid portion definition. The server does not infer density, and volume, IU, milligram labels, missing units, and invalid serving sizes cannot be converted automatically. Batch retrieval does not perform portion scaling. Food resources accept only bare positive integer FDC IDs, and comparison requires at least two foods to resolve successfully.

Search exposes only selected preview nutrients; use the full-food tool for other nutrients or the complete profile. The nutrient reference is static and contains approximately 150 tracked nutrients rather than every possible field in FoodData Central.

_Full upstream README: https://allmcps.com/mcp/usda-mcp-server/readme_