usda-mcp

An MCP server that gives Claude a USDA-accurate food database and deterministic macro math — so it looks nutrition numbers up instead of recalling them, and calculates portions in Python instead of doing mental arithmetic.

Ask "build me a high-protein vegan dinner at 40g protein, 30g carb, 15g fat" and you get an answer whose numbers are exactly right, because a linear solver produced them.

You: high protein vegan dinner, 40g protein / 30g carb / 15g fat

Claude: 147 g Beans (Dry) ....... 37.5g pro,    0g carb,  1.5g fat
        5 oz Sweet Potato ......  2.5g pro,   30g carb,    0g fat
        0.96 tbsp Olive Oil ....    0g pro,    0g carb, 13.5g fat
        -----------------------------------------------------------
        Total .................. 40.0g pro, 30.0g carb, 15.0g fat — 415 kcal

Why this exists

LLMs are unreliable at two things this domain depends on: recalling specific nutrition values, and arithmetic. Ask a model for the macros in 6 oz of chicken breast and you get a plausible number that is often wrong by 15–20%.

This server removes both failure modes. It contains no AI logic at all — no model calls, no embeddings, no semantic search. It is a database and a pile of arithmetic. The calling model does the reasoning ("what counts as light?", "what goes with salmon?") and this server supplies every number.

Install

Requires uv (or any Python 3.10+ environment). Nothing else — no API key, no network access, no external services. It runs fully offline.

Add this to your Claude Desktop config:

macOS — ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "usda-mcp": {
      "command": "uvx",
      "args": ["usda-mcp"]
    }
  }
}

Windows — %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "usda-mcp": {
      "command": "uvx",
      "args": ["usda-mcp"]
    }
  }
}

Restart Claude Desktop. You should see six tools appear under the tools icon.

<details> <summary>Running from a clone instead</summary>

git clone https://github.com/Asquarer02/usda-mcp
cd usda-mcp
uv sync
uv run usda-mcp        # serves MCP over stdio

Then point the config at the checkout:

{
  "mcpServers": {
    "usda-mcp": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/usda-mcp", "run", "usda-mcp"]
    }
  }
}

</details>

Tools

Tool	What it does
list_foods	Browse or filter the database by category, descriptive tags, or dietary exclusions.
get_food	Look up one food by name, tolerant of casing and missing qualifiers.
calculate_macros	Scale a food to a real portion, converting units where physically valid.
filter_by_diet	Every food compatible with one restriction (vegan, gluten, shellfish, …).
build_meal	Solve for portions of one protein + one carb + one fat that hit macro targets.
list_available_tags	The real filter vocabulary, so the model never guesses a label that doesn't exist.

Example prompts

• "What are the macros in 6 oz of chicken breast?"
• "Give me a high-protein vegan dinner at 40g protein, 30g carb, 15g fat."
• "Show me every lean protein that isn't fish or shellfish."
• "I have 25g of protein left today and no carbs — what should I eat?"
• "Build three different 500-calorie gluten-free lunches."

What the tools actually return

get_food("salmon") — loose name, resolved:

{
  "name": "Salmon", "category": "proteins", "unit": "oz",
  "pro": 6.5, "carb": 0, "fat": 3.5,
  "tags": ["fatty_fish", "omega3"],
  "exclude_for": ["vegetarian", "vegan", "fish", "seafood"],
  "calories_per_unit": 57.5
}

calculate_macros("Chicken Breast (Cooked)", 6, "oz") — the database stores this food per gram, so the ounces are converted before scaling:

{
  "food": "Chicken Breast (Cooked)",
  "amount": 6.0, "unit": "oz",
  "amount_in_native_units": 170.0971, "native_unit": "g",
  "protein_g": 54.6, "carb_g": 0.0, "fat_g": 5.51, "calories": 268.0
}

How it works

Calories are derived, never stored. The dataset holds only protein, carb and fat, and calories come from the Atwater factors (4/4/9) in one function. There is no second source of truth to drift.

build_meal is a solver, not a search. One protein, one carb and one fat with three macro targets is a 3×3 linear system; it's solved by Cramer's rule for every combination in the database — all 164,150 of them. The scan is cheap enough to run exhaustively on every call, so there are no heuristics, sampling or early exits to reason about. Fits are exact, not "within tolerance".

Exactness turns out to be the easy part. For a 40/30/15 target, 77,026 combinations hit it exactly, including useless ones like 0.02 tbsp of ghee. So solutions are filtered for realistic portion sizes and ranked by how normal the servings look. Ties break on database order, so the same request always returns the same meal.

Impossible requests are reported, not faked. Ask for 200g of protein with zero carbs and zero fat and you get exact_match: false, the closest achievable combination, and the real per-macro error — never a fabricated fit.

Bad input gets a usable error, never silence. Every failure explains itself:

{
  "error": "unit_mismatch",
  "message": "Cannot convert 'g' to 'tbsp': 'g' is a mass unit and 'tbsp' is a volume unit.
              This database does not store densities, so mass and volume are not interchangeable.",
  "food": "Extra Virgin Olive Oil",
  "native_unit": "tbsp",
  "hint": "Extra Virgin Olive Oil is stored per 'tbsp'. Retry with unit='tbsp', or with any
           unit in the same measurement family."
}

Grams to tablespoons needs a density this dataset doesn't carry, so the conversion is refused rather than guessed. A wrong answer here would silently corrupt every number downstream.

Similarly, filter_by_diet("keto") returns an error rather than the whole database: keto isn't a label in the data, so filtering on it would remove nothing while looking like it worked.

The data

236 hand-curated entries across proteins (67), carbs (70), fats (35) and vegetables (64), with macros matching USDA FoodData Central values. Each entry carries descriptive tags (lean, omega3, whole_food) and exclude_for dietary/allergen labels (vegan, gluten, shellfish). 90 distinct tags and 38 exclusion labels are in use.

Macros are stored per the unit that's natural for each food — grams for meat, ounces for fish, tablespoons for oils, large for eggs, container for yogurt cups. calculate_macros handles the conversion; list_available_tags reports the real vocabulary.

The test suite guards the dataset itself: unique names, non-negative macros, consistent tag casing, and units the converter can classify.

Not medical or dietary advice. These are reference values for general meal planning. Real foods vary by brand, cut, and preparation. Consult a qualified professional for clinical or therapeutic dietary decisions.

Development

uv sync
uv run pytest              # 346 tests
uv run ruff check .
uv run ruff format .

The layout separates concerns so the logic is testable without an MCP client:

src/usda_mcp/
├── server.py          # tool definitions and docstrings only
├── nutrition.py       # calories, unit conversion, lookup, filtering
├── meal_builder.py    # the deterministic solver
└── food_database.py   # the data, and nothing else

Tool docstrings are treated as a deliverable rather than decoration — they're the entire interface the calling model sees, so they state exact enum values, which units convert, and what every failure returns. A test enforces that they stay substantial.

Roadmap

• Live USDA FoodData Central lookups — an optional search_usda tool backed by the official API for foods outside the curated set, behind the same tool interface. Would require an API key and unit normalisation, so it's deliberately out of v1.
• Per-food micronutrients (fibre, sodium, saturated fat).
• Multi-meal daily planning against a calorie budget.

Contributing

Issues and PRs welcome. Adding foods is the easiest contribution — append an entry to the right category in src/usda_mcp/food_database.py with USDA-sourced macros per unit, and tests/test_database.py will verify it.

See CONTRIBUTING.md for setup, the data format, and the design principles worth preserving.

License

MIT — see LICENSE.