Usda MCP Server

Name: Usda MCP Server
Author: cyanheads

by cyanheadsversion 0.2.0i★ –iComputer or cloud

Registry nameio.github.cyanheads/usda-mcp-server

Install

Overview

Description from the maker (original English)

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

PopNx MCP’s three pillars

These three are never merged into one score: opinions, measurements and popularity are different things.

User voiceiNo reviews yetReviews open together with accounts in a later step
Our basic checksi3 of 3 passedChecked from public information; code not scanned yet
UsageiNot measured yet★ –

What you can do with it

We have not written a plain-language summary for this one yet. Below are the facts we read from the registry.

Connection: Computer or cloud
Transport: stdio, Streamable HTTP
Category: Search & AI memory
You need to fill in: USDA_FDC_API_KEY

Install

Pick the AI app you use, then copy the settings.

Before you install

Basic checks: 3 of 3 passed
Runs on the maker’s server: what you ask it goes through their server.
Can do 5 things (tools) usda_list_nutrients, usda_search_foods, usda_get_food, usda_get_foods …
You fill in yourself: USDA_FDC_API_KEY, MCP_LOG_LEVEL

You need

Runs in the cloudNothing to install; it connects over the internet
npmNode.js installed (for the npx command)

Which app do you use?

ClaudeClaude CodeCursorVS CodeChatGPT

Pick your app above. We remember it, so next time the button says “Install in …”.

Works in Claude on the web, desktop and mobile:

Open Settings → Connectors
Press Add custom connector
Paste the address below and press Add
If it asks you to sign in, sign in with the maker

https://usda.caseyjhand.com/mcp

Or run it on your computer

Open Claude Desktop → Settings → Developer → Edit Config, and paste this into claude_desktop_config.json

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

Run this in your terminal

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

Or run it on your computer

claude mcp add usda --env USDA_FDC_API_KEY=your-value --env MCP_LOG_LEVEL=your-value -- npx -y @cyanheads/usda-mcp-server

Fill in the empty values before running it.

Open in Cursor

Or copy the settings yourself

Paste into .cursor/mcp.json in your project, or ~/.cursor/mcp.json

{
  "mcpServers": {
    "usda": {
      "url": "https://usda.caseyjhand.com/mcp"
    }
  }
}

Or run it on your computer

Open in Cursor

Or copy the settings yourself

Paste into .cursor/mcp.json in your project, or ~/.cursor/mcp.json

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

Your browser asks to open the app, then the app shows the settings and asks you to confirm. Key values are left empty for you to fill in.

Open in VS Code

Or copy the settings yourself

Paste into .vscode/mcp.json in your project

{
  "servers": {
    "usda": {
      "type": "http",
      "url": "https://usda.caseyjhand.com/mcp"
    }
  }
}

Or run it on your computer

Open in VS Code

Or copy the settings yourself

Paste into .vscode/mcp.json in your project

{
  "servers": {
    "usda": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@cyanheads/usda-mcp-server"
      ],
      "env": {
        "USDA_FDC_API_KEY": "your-value",
        "MCP_LOG_LEVEL": "your-value"
      }
    }
  }
}

Your browser asks to open the app, then the app shows the settings and asks you to confirm. Key values are left empty for you to fill in.

ChatGPT connects only to servers on the internet:

Open ChatGPT on the web → Settings → Connectors (Apps)
Press Create or Add (some plans need Developer mode under Advanced first)
Paste the address below, give it a name and save
If it asks you to sign in, sign in with the maker

https://usda.caseyjhand.com/mcp

Menu names can differ slightly by plan and over time.

Your choice stays on this device in a cookie; no account needed.

Values you fill in

USDA_FDC_API_KEY required env
USDA FoodData Central API key from data.gov. Required for all food data requests.
MCP_LOG_LEVEL env
Sets the minimum log level for output (e.g., 'debug', 'info', 'warn').

These settings are generated from the maker’s registry entry. If the README says otherwise, follow the README.

What it can do

Tool names and descriptions exactly as the server reported them on Nov 7, 2026. The maker wrote them, not us; we show them as plain text.

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 b
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 omit
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 value
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
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, prote

Basic checksi

We check information anyone can see; we have not read the code. Checks that do not apply are left out of the count. · Checked Nov 7, 2026

✓ Pass
Maker matches the repo
The registry name was verified with the GitHub account cyanheads, which owns the repo
… Not checked yet
Still maintained
We have not read this repo from GitHub yet
… Not checked yet
Has a licence
We have not read this repo from GitHub yet
✓ Pass
Endpoint responds
Responded in 208 ms (HTTP 200)
– Not applicable
Sign-in with OAuth
No sign-in needed
✓ Pass
No hidden instructions in tool descriptions
Read 5 tool descriptions and found no hidden instructions to the AI

Compared with others in Search & AI memoryi

More stars than 0% of the other 7284 servers in this category
Published to the registry more recently than 75% of the other 7284 servers in this category
Basic checks equal to or better than 100% of the other 7284 servers in this category

Compared with every active server in this category in the registry. Stars count only when the publisher owns the repo.

Common questions

Is Usda MCP Server safe?

It passed 3 of 3 applicable basic checks. We have not read the code. Before adding a key or token, see what access the server asks for and use a key with only the permissions you need.

What keys or codes does it need?

You need to fill in: USDA_FDC_API_KEY

Does it run on my computer or in the cloud?

Either way works: install it on your computer or connect to the cloud version.

Is it still maintained?

The GitHub repo last changed –, and the latest version (0.2.0) reached the registry 12 days ago.

Which apps can use it?

Apps that support MCP, such as Claude Desktop, Claude Code, Cursor and VS Code. It connects by URL, so apps that accept remote MCP servers work too, such as ChatGPT in developer mode.

What can I use instead?

In the same category: Context7, Codebase Memory, Exa

Alternatives

Servers in the same category from other makers, sorted by stars.

Reading a card:★ GitHub starsiThree pillars: reviews · checks · usageiUpdated = latest version published to the registryi

Context7

by upstash

Feeds AI the latest docs for libraries and frameworks before it answers, so code it writes does not use outdated, removed functions.

Computer or cloud★ 64,224MITUpdated yesterday

Install

Codebase Memory

by DeusData

Codebase knowledge graph for AI agents — 162 languages, sub-ms queries, 99% fewer tokens.

Runs on your computer★ 48,148MITUpdated 21 days ago

Install

Exa

by exa-labs

Connect AI agents to Exa for web search, content fetching, and multi-step research.

Runs in the cloud★ 5,213MITUpdated last month

Install

README from the maker

Open the README

Copied from the maker’s repo as written. PopNx MCP has not reviewed or endorsed it. HTML, images and scripts are removed. Links lead off this site.

@cyanheads/usda-mcp-server Search foods, compare nutrients, and look up the full USDA FoodData Central database via MCP. STDIO or Streamable HTTP. 5 Tools • 3 Resources

Public Hosted Server: https://usda.caseyjhand.com/mcp

Overview

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.

Tools

Tool	Description
`usda_search_foods`	Search foods by keyword, ingredient, or UPC/GTIN across SR Legacy, Foundation, Survey (FNDDS), and Branded data sources
`usda_get_food`	Full nutrient profile for one food by FDC ID, with optional per-portion scaling
`usda_get_foods`	Batch nutrient fetch for 2–20 FDC IDs in a single request
`usda_compare_foods`	Side-by-side nutrient comparison for 2–5 foods, formatted as a markdown table
`usda_list_nutrients`	Static FDC nutrient reference table (~150 nutrients) with IDs, names, units, and categories

Resources

Resource	Description
`usda://food/{fdcId}`	Full nutrient profile for a specific food by FDC ID
`usda://nutrients`	Complete FDC nutrient reference list
`skill://usda-guide/SKILL.md`	Food selection, serving-weight, and missing-nutrient guidance for agents

Food profiles and the nutrient reference are also reachable via tools. Use usda_search_foods to discover FDC IDs before reading food resources.

Capability reference

`usda_search_foods` tool

Query by keyword, ingredient name, or UPC/GTIN code; optional dataType[] 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 paginate
Returns FDC IDs plus available preview nutrients: protein (1003), fat (1004), carbohydrate (1005), fiber (1079), and energy (1008, 1062, 2047, 2048). Original values, units, order, and distinct energy estimates are preserved; missing entries are omitted. Use usda_get_food for other nutrients or the full profile
A page past totalPages returns empty foods[], the requested page, totals, and a notice with a valid pageNumber when the query has matches
Typed errors: query_empty (blank query), query_syntax (FDC rejected the query syntax), no_results (nothing matched in the requested data sources)

`usda_get_food` tool

Full nutrient profile for one fdcId; optional nutrients[] filter to specific IDs
Optional unit (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 quantity
servingInfo identifies the resolved portion or label serving and its gram weight; allPortions[] contains actual portion definitions only
Typed errors: not_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 inferred

`usda_get_foods` tool

Batch fetch for 2–20 FDC IDs in one call; values are per-100g only (no portion scaling)
nutrients[] filter strongly recommended — full profiles for 20 foods are large
Per-ID partial failure — IDs that return no data land in failed[] instead of aborting the batch

`usda_compare_foods` tool

Side-by-side comparison for 2–5 FDC IDs, pivoted one row per nutrient and one column per food
Defaults to 12 commonly compared nutrients (energy, protein, fat, saturated fat, carbs, fiber, total sugars, sodium, potassium, calcium, iron, vitamin C) unless nutrients[] is given
All values scaled to a common quantity + unit basis (default 100 g; quantity is an amount in unit, so unit: "oz" alone compares per 100 oz)
Proceeds with the valid foods when some IDs return no data; only throws too_few_foods when fewer than 2 resolve
Rows where every food is null for that nutrient are filtered out

`usda_list_nutrients` tool

Static reference table of ~150 tracked FDC nutrients — no API call
Optional category filter: macronutrients, vitamins, minerals, lipids, amino_acids, other
Returns each nutrient's ID, name, SR reference number, unit, and category — resolve a name to the ID used by nutrients[] elsewhere

`usda://food/{fdcId}` resource

Same data as usda_get_food without portion scaling — full nutrient profile per 100g as application/json
fdcId must be a bare positive integer (no sign, leading zero, decimal, or exponent); anything else throws invalid_id
not_found when the ID doesn't exist in FDC

`usda://nutrients` resource

Complete FDC nutrient reference — same content as usda_list_nutrients with no category filter
Served as application/json with a 1-hour public cache hint, since the table is bundled at build time and identical for every caller

`skill://usda-guide/SKILL.md` resource

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

Features

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:

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

Connect to the hosted instance, no install:

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

Or run it locally:

claude mcp add usda-mcp-server -e USDA_FDC_API_KEY=your-key -- npx -y @cyanheads/usda-mcp-server

For other clients, add this to the MCP config file:

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

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.

Configuration

Variable	Description	Default
`USDA_FDC_API_KEY`	Required for FoodData Central-backed tools (search, get, batch, compare) — not for startup or `usda_list_nutrients`. Get a free key at api.data.gov.	—
`MCP_TRANSPORT_TYPE`	Transport: `stdio` or `http`.	`stdio`
`MCP_HTTP_PORT`	Port for HTTP server.	`3010`
`MCP_AUTH_MODE`	Auth mode: `none`, `jwt`, or `oauth`.	`none`
`MCP_LOG_LEVEL`	Log level (RFC 5424).	`info`
`LOGS_DIR`	Directory for log files (Node.js only).	`/logs`
`STORAGE_PROVIDER_TYPE`	Storage backend.	`in-memory`
`OTEL_ENABLED`	Enable OpenTelemetry instrumentation (spans, metrics, completion logs).	`false`

See .env.example for the full list of optional overrides.

Running the server

Requires Bun v1.4.0 or higher (or Node.js v24+).

Local development

git clone https://github.com/cyanheads/usda-mcp-server.git

cd usda-mcp-server && bun install cp .env.example .env # set USDA_FDC_API_KEY

Build and run:

  # One-time build

bun run rebuild

Run the built server

bun run start:stdio

or

bun run start:http

Run checks and tests:

  bun run devcheck   # Lint, format, typecheck, security

bun run test # Vitest test suite bun run lint:mcp # Validate MCP definitions against spec

Docker

docker run --rm -e USDA_FDC_API_KEY=your-key -p 3010:3010 ghcr.io/cyanheads/usda-mcp-server:latest

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

Only the beginning is shown; read the rest in the repo

Usda MCP Server

Overview

PopNx MCP’s three pillars

What you can do with it

Install

Before you install

Or run it on your computer

Or run it on your computer

Or run it on your computer

Or run it on your computer

Values you fill in

What it can do

Basic checksi

Maker matches the repo

Still maintained

Has a licence

Endpoint responds

Sign-in with OAuth

No hidden instructions in tool descriptions

Compared with others in Search & AI memoryi

Common questions

Alternatives

Context7

Codebase Memory

Exa

README from the maker

Overview

Tools

Resources

Capability reference

usda_search_foods tool

usda_get_food tool

usda_get_foods tool

usda_compare_foods tool

usda_list_nutrients tool

usda://food/{fdcId} resource

usda://nutrients resource

skill://usda-guide/SKILL.md resource

Features

Getting started

Configuration

Running the server

Local development

Run the built server

or

Docker

`usda_search_foods` tool

`usda_get_food` tool

`usda_get_foods` tool

`usda_compare_foods` tool

`usda_list_nutrients` tool

`usda://food/{fdcId}` resource

`usda://nutrients` resource

`skill://usda-guide/SKILL.md` resource