# usda-mcp

[![CI](https://github.com/Asquarer02/usda-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/Asquarer02/usda-mcp/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/usda-mcp?color=blue)](https://pypi.org/project/usda-mcp/)
[![Python](https://img.shields.io/pypi/pyversions/usda-mcp)](https://pypi.org/project/usda-mcp/)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)

An [MCP](https://modelcontextprotocol.io) 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](https://docs.astral.sh/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`

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

**Windows** — `%APPDATA%\Claude\claude_desktop_config.json`

```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>

```bash
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:

```json
{
  "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:

```json
{
  "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:

```json
{
  "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:

```json
{
  "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

```bash
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](CONTRIBUTING.md) for setup, the data format, and the design
principles worth preserving.

## License

MIT — see [LICENSE](LICENSE).