usda-mcp-server

<div align="center">
  <h1>@cyanheads/usda-mcp-server</h1>
  <p><b>Search foods, compare nutrients, and look up the full USDA FoodData Central database via MCP. STDIO or Streamable HTTP.</b>
  <div>5 Tools • 2 Resources</div>
  </p>
</div>

<div align="center">

[![Version](https://img.shields.io/badge/Version-0.1.9-blue.svg?style=flat-square)](./CHANGELOG.md) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![Docker](https://img.shields.io/badge/Docker-ghcr.io-2496ED?style=flat-square&logo=docker&logoColor=white)](https://github.com/users/cyanheads/packages/container/package/usda-mcp-server) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^2.0.0-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![npm](https://img.shields.io/npm/v/@cyanheads/usda-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/usda-mcp-server) [![TypeScript](https://img.shields.io/badge/TypeScript-^7.0.2-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.4.0-blueviolet.svg?style=flat-square)](https://bun.sh/)

</div>

<div align="center">

[![Install in Claude Desktop](https://img.shields.io/badge/Install_in-Claude_Desktop-D97757?style=for-the-badge&logo=anthropic&logoColor=white)](https://github.com/cyanheads/usda-mcp-server/releases/latest/download/usda-mcp-server.mcpb) [![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=usda-mcp-server&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBjeWFuaGVhZHMvdXNkYS1tY3Atc2VydmVyIl0sImVudiI6eyJVU0RBX0ZEQ19BUElfS0VZIjoieW91ci1hcGkta2V5In19) [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=for-the-badge&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect?url=vscode:mcp/install?%7B%22name%22%3A%22usda-mcp-server%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40cyanheads%2Fusda-mcp-server%22%5D%2C%22env%22%3A%7B%22USDA_FDC_API_KEY%22%3A%22your-api-key%22%7D%7D)

[![Framework](https://img.shields.io/badge/Built%20on-@cyanheads/mcp--ts--core-67E8F9?style=flat-square)](https://www.npmjs.com/package/@cyanheads/mcp-ts-core)

</div>

<div align="center">

**Public Hosted Server:** [https://usda.caseyjhand.com/mcp](https://usda.caseyjhand.com/mcp)

</div>

---

## Tools

Five tools covering the USDA FoodData Central workflow — from discovery to detailed nutrient analysis:

| Tool | Description |
|:---|:---|
| `usda_search_foods` | Search foods by keyword across SR Legacy, Foundation, Survey FNDDS, and Branded data sources, with nutrient preview and pagination |
| `usda_get_food` | Full nutrient profile for one food by FDC ID, with optional per-portion scaling (g, oz, lb, kg, or serving) |
| `usda_get_foods` | Batch nutrient fetch for 2–20 FDC IDs in a single request; failed IDs reported in `failed[]` instead of aborting |
| `usda_compare_foods` | Side-by-side nutrient comparison for 2–5 foods, formatted as a markdown table scaled to a common gram basis |
| `usda_list_nutrients` | Static FDC nutrient reference table (~150 nutrients) with IDs, names, units, and categories — no API call required |

### `usda_search_foods`

Search USDA FoodData Central foods by keyword, UPC/GTIN code, or ingredient.

- Covers all FDC data sources: SR Legacy (common whole foods, complete nutrient profiles), Foundation, Survey FNDDS, and Branded (packaged products)
- Defaults to SR Legacy; include `"Branded"` in `dataType` for packaged products or UPC lookup
- Brand owner filter to narrow branded results (e.g. `"General Mills"`) — setting `brandOwner` without `dataType` searches Branded, since only Branded records carry a brand owner
- Food category filter (e.g. `"Poultry Products"`, `"Vegetables and Vegetable Products"`)
- Pagination via `pageSize` (up to 50) and `pageNumber`
- Returns FDC IDs and a preview of key nutrients (energy, protein, fat, carbs) — use `usda_get_food` for the full profile

---

### `usda_get_food`

Full nutrient profile for one food by FDC ID.

- All available nutrients (or a filtered subset via `nutrients[]`) with amounts per 100g
- Optional portion scaling — provide `quantity` + `unit` to scale values (e.g. `quantity=200, unit="g"` → per-200g values)
- `unit="serving"` scales to the food's first defined portion weight
- Returns all named portion definitions (`allPortions[]`) alongside the serving info
- Filtering `nutrients[]` to specific IDs strongly reduces context size for common queries (use `usda_list_nutrients` to look up IDs)

---

### `usda_get_foods`

Batch nutrient fetch for 2–20 FDC IDs.

- All values per 100g (no portion scaling in batch mode)
- `nutrients[]` filter strongly recommended — full profiles for 20 foods are large
- Per-item partial failure: `failed[]` carries IDs that returned no data, so one missing food doesn't abort the batch
- More efficient than N individual `usda_get_food` calls when you already have FDC IDs

---

### `usda_compare_foods`

Side-by-side nutrient comparison for 2–5 foods.

- Returns a pivot table — one row per nutrient, one column per food — and formats it as a markdown table
- Defaults to the 12 most commonly compared nutrients (energy, protein, fat, saturated fat, carbs, fiber, total sugars, sodium, potassium, calcium, iron, vitamin C)
- Pass custom `nutrients[]` for specific comparisons (e.g. just iron and vitamin C)
- All values scaled to a common gram basis (default 100g; override with `quantity` + `unit`)
- Proceeds with valid foods when some IDs aren't found — only fails when fewer than 2 IDs return data
- Rows where all values are null (nutrient not tracked for any of the selected foods) are filtered out

---

### `usda_list_nutrients`

FDC nutrient reference table — all ~150 tracked nutrients.

- Returns IDs, names, SR reference numbers, units, and categories
- Optional `category` filter: `macronutrients`, `vitamins`, `minerals`, `lipids`, `amino_acids`, `other`
- Resolves nutrient names (e.g. `"vitamin C"`) to FDC IDs (1162) for use in `nutrients[]` params
- Static data — no API call, instant response; call once and reuse the IDs

## Resources and prompts

| Type | Name | Description |
|:---|:---|:---|
| Resource | `usda://food/{fdcId}` | Full nutrient profile for a specific food by FDC ID — same data as `usda_get_food` without portion scaling |
| Resource | `usda://nutrients` | Complete FDC nutrient reference list — all ~150 tracked nutrients with IDs, names, units, and categories |

All resource data is also reachable via tools. Use `usda_search_foods` to discover FDC IDs before reading food resources.

## Features

Built on [`@cyanheads/mcp-ts-core`](https://www.npmjs.com/package/@cyanheads/mcp-ts-core):

- Declarative tool and resource definitions — single file per primitive, framework handles registration and validation
- Unified error handling — handlers throw, framework catches, classifies, and formats
- Pluggable auth: `none`, `jwt`, `oauth`
- Swappable storage backends: `in-memory`, `filesystem`, `Supabase`, `Cloudflare KV/R2/D1`
- Structured logging with optional OpenTelemetry tracing
- STDIO and Streamable HTTP transports

USDA FDC-specific:

- Type-safe client for the USDA FoodData Central REST API (`api.nal.usda.gov/fdc/v1`)
- Normalization layer that handles inconsistent API response shapes across search, single-food, and batch endpoints
- Batch API endpoint (`/foods`) with per-food partial failure reporting
- HTML response detection (rate-limit proxy returns 200 HTML) with service-unavailable error surfacing
- Static nutrient reference dictionary — ~150 nutrients with FDC IDs, SR numbers, units, and categories; no API call required

Agent-friendly output:

- Provenance preserved — FDC data source (`dataType`) on every food result so callers know whether they're reading curated research data or label-derived branded values
- Partial failure reporting — batch tools (`usda_get_foods`, `usda_compare_foods`) return successes alongside structured `failed[]` / `missingData[]` entries rather than failing the whole request
- Cross-reference hints — FDC IDs and tool names in descriptions so agents know exactly which call to make next (search → get → compare workflow)

## Getting started

### Public Hosted Instance

A public instance is available at `https://usda.caseyjhand.com/mcp` — no installation required. Point any MCP client at it via Streamable HTTP:

```json
{
  "mcpServers": {
    "usda-mcp-server": {
      "type": "streamable-http",
      "url": "https://usda.caseyjhand.com/mcp"
    }
  }
}
```

### Self-Hosted / Local

Add the following to your MCP client configuration file. See [data.gov API key signup](https://api.data.gov/signup/) to generate a free API key.

```json
{
  "mcpServers": {
    "usda-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/usda-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "USDA_FDC_API_KEY": "your-api-key"
      }
    }
  }
}
```

Or with npx (no Bun required):

```json
{
  "mcpServers": {
    "usda-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/usda-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "USDA_FDC_API_KEY": "your-api-key"
      }
    }
  }
}
```

Or with Docker:

```json
{
  "mcpServers": {
    "usda-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MCP_TRANSPORT_TYPE=stdio",
        "-e", "USDA_FDC_API_KEY=your-api-key",
        "ghcr.io/cyanheads/usda-mcp-server:latest"
      ]
    }
  }
}
```

For Streamable HTTP, set the transport and start the server:

```sh
MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 USDA_FDC_API_KEY=your-api-key bun run start:http
# Server listens at http://localhost:3010/mcp
```