Nutriref MCP server

NutriRef

Pay-per-call USDA nutrition data for AI agents. Structured FoodData Central via the x402 micropayment protocol — agents pay $0.001–$0.005 in USDC per request, no signup, no API keys, no human auth flows.

Live at ****. Spec at /openapi.json · Swagger at /docs · Bazaar discovery at /.well-known/x402.

Endpoints

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:

pip install nutriref-mcp

Then add this to your MCP client config (Claude Desktop's claudedesktopconfig.json, Claude Code's MCP settings, etc.):

{
  "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 nutritionsearch, nutritiondetail, nutritioncompare, nutritionrecipe 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:

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:

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

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

Shortened. The full README is on GitHub.