Content
# NutriRef
[](https://glama.ai/mcp/servers/Younghef/nutriref-api)
**Pay-per-call USDA nutrition data for AI agents.** Structured FoodData Central via the [x402](https://www.x402.org/) micropayment protocol — agents pay $0.001–$0.005 in USDC per request, no signup, no API keys, no human auth flows.
Live at **<https://nutriref.xyz>**. Spec at [/openapi.json](https://nutriref.xyz/openapi.json) · Swagger at [/docs](https://nutriref.xyz/docs) · Bazaar discovery at [/.well-known/x402](https://nutriref.xyz/.well-known/x402).
## Endpoints
| Method | Path | Price | Cache |
|---|---|---|---|
| `GET` | `/v1/nutrition/search?q=&limit=` | $0.001 | 24h |
| `GET` | `/v1/nutrition/detail/{fdc_id}` | $0.002 | 7d |
| `POST` | `/v1/nutrition/compare` | $0.003 | derived |
| `POST` | `/v1/nutrition/recipe` | $0.005 | derived |
All values per 100g. Missing nutrients are `null`, not `0`. `compare` returns per-nutrient winners (highest protein, lowest sodium, etc.). `recipe` scales by grams and sums.
## Use it from Claude (or any MCP agent)
NutriRef ships an MCP server that exposes the four endpoints as native tools. Install it from PyPI:
```bash
pip install nutriref-mcp
```
Then add this to your MCP client config (Claude Desktop's `claude_desktop_config.json`, Claude Code's MCP settings, etc.):
```json
{
"mcpServers": {
"nutriref": {
"command": "nutriref-mcp",
"env": {
"PAYER_PRIVATE_KEY": "0x...your-funded-wallet-key...",
"NUTRIREF_BASE_URL": "https://nutriref.xyz"
}
}
}
}
```
> Prefer not to install? Use `uvx nutriref-mcp` as the `command` to run it on demand. To work from a clone instead, `pip install -e ".[mcp]"` and set `command` to `python` with `args: ["-m", "mcp_server"]`.
The wallet needs USDC on Base mainnet — gas is sponsored by the facilitator, so you only need stablecoin balance. The agent now has `nutrition_search`, `nutrition_detail`, `nutrition_compare`, `nutrition_recipe` and auto-pays per call.
## Use it from any HTTP client
Unpaid requests get `402 Payment Required` with x402 payment instructions. Any x402-aware client signs a gasless USDC authorization (EIP-3009) and retries automatically:
```python
import asyncio
from eth_account import Account
from x402.client import x402Client
from x402.http.clients.httpx import wrapHttpxWithPayment
from x402.mechanisms.evm.exact import register_exact_evm_client
account = Account.from_key("0x...funded-wallet-key...")
client = x402Client(); register_exact_evm_client(client, account)
async def main():
async with wrapHttpxWithPayment(client, base_url="https://nutriref.xyz") as http:
r = await http.get("/v1/nutrition/detail/2012128")
print(r.json())
asyncio.run(main())
```
## Response example
`GET /v1/nutrition/detail/173944`:
```json
{
"fdc_id": 173944,
"description": "Banana, raw",
"data_type": "Foundation",
"serving_size": 100, "serving_size_unit": "g",
"calories": 89.0, "protein": 1.1, "fat": 0.3,
"carbs": 22.8, "fiber": 2.6, "sugar": 12.2,
"sodium": 1.0, "cholesterol": null, "saturated_fat": 0.1,
"vitamin_c": 8.7, "calcium": 5.0, "iron": 0.3, "potassium": 358.0
}
```
---
## Self-hosting
NutriRef is open source; the live instance at `nutriref.xyz` is one deployment among many possible. To run your own:
```bash
cp .env.example .env
# fill in USDA_API_KEY (free at https://fdc.nal.usda.gov/api-key-signup.html)
# and X402_RECEIVER_ADDRESS (an EVM address that should receive payments)
docker compose up --build
curl http://localhost:8000/health
```
### Configuration
| Var | Required | Default | Purpose |
|---|---|---|---|
| `USDA_API_KEY` | yes | — | Free key from [fdc.nal.usda.gov](https://fdc.nal.usda.gov/api-key-signup.html) |
| `USDA_BASE_URL` | no | `https://api.nal.usda.gov/fdc/v1` | |
| `REDIS_URL` | no | `redis://redis:6379/0` | Response cache |
| `X402_NETWORK` | no | `base-sepolia` | `base` for mainnet |
| `X402_RECEIVER_ADDRESS` | yes | — | EVM address that receives USDC |
| `X402_FACILITATOR_URL` | no | `https://x402.org/facilitator` | `https://api.cdp.coinbase.com` for mainnet |
| `CDP_API_KEY_ID` | mainnet only | — | Coinbase Developer Platform key ID |
| `CDP_API_KEY_SECRET` | mainnet only | — | Coinbase Developer Platform key secret |
| `LOG_LEVEL` | no | `INFO` | |
For mainnet you need a Coinbase CDP account and the public x402 facilitator at `https://api.cdp.coinbase.com`. Testnet works for free with the community facilitator at `https://x402.org/facilitator`.
### Architecture
```
agent → x402 middleware → route handler → cache (Redis) → USDA FDC API
```
`search` and `detail` cache USDA responses directly. `compare` and `recipe` compose from the cached `detail` data — no extra USDA calls when warm. The cache is a meaningful cost lever: warm requests return in <50ms and never hit USDA.
### Tests
```bash
pip install -e ".[dev]"
pytest
```
## Example: Claude agent that uses NutriRef
`examples/meal-planner/` is a complete, ~150-line agent that gives Claude
the four NutriRef endpoints as tools and asks it to plan a day of meals
hitting a calorie/protein goal. Worth reading if you're wiring NutriRef
into your own agent — the tool schemas and the payment loop are all
there. See `examples/meal-planner/README.md`.
## Repo layout
```
app/ # FastAPI service
main.py # app factory + x402 init
routes/ # search, detail, compare, recipe
landing.py # / (public landing page)
discovery.py # /.well-known/x402, /llms.txt, /.well-known/ai-plugin.json, /logo.svg
usda.py # async USDA client
cache.py # Redis wrapper
normalize.py # USDA → flat 13-nutrient schema
mcp_server/ # MCP server wrapper for agent use
examples/ # worked agent examples (meal planner)
scripts/ # CDP wallet bootstrap + payer-side test
tests/ # pytest + respx + fakeredis
```
## Acknowledgments
- [USDA FoodData Central](https://fdc.nal.usda.gov/) for the data.
- [x402](https://www.x402.org/) for the payment protocol.
- [`fastapi-x402`](https://pypi.org/project/fastapi-x402/) for the server middleware (with a small EIP-712 patch we apply at startup for Base mainnet USDC).
