内容
# NutriRef
[](https://glama.ai/mcp/servers/Younghef/nutriref-api)
**按调用付费的USDA营养数据，用于AI代理。** 通过[x402](https://www.x402.org/)微支付协议提供的结构化FoodData Central - 代理支付$0.001–$0.005美元每请求，无需注册，无需API密钥，无需人工授权流程。
实时地址：**<https://nutriref.xyz>**. 规范：[/openapi.json](https://nutriref.xyz/openapi.json) · Swagger：[/docs](https://nutriref.xyz/docs) · 集市发现：[/.well-known/x402](https://nutriref.xyz/.well-known/x402).
## 端点
| 方法 | 路径 | 价格 | 缓存 |
|---|---|---|---|
| `GET` | `/v1/nutrition/search?q=&limit=` | $0.001 | 24小时 |
| `GET` | `/v1/nutrition/detail/{fdc_id}` | $0.002 | 7天 |
| `POST` | `/v1/nutrition/compare` | $0.003 | 派生 |
| `POST` | `/v1/nutrition/recipe` | $0.005 | 派生 |
所有值均按100克计算。缺失的营养素为`null`，而非`0`。`compare`返回按营养素的赢家（蛋白质最高、钠最低等）。`recipe`按克缩放并求和。
## 从Claude（或任何MCP代理）使用
NutriRef提供了一个MCP服务器，通过四个端点作为原生工具暴露。 从PyPI安装：
```bash
pip install nutriref-mcp
```
然后将其添加到您的MCP客户端配置（Claude Desktop的`claude_desktop_config.json`，Claude Code的MCP设置等）：
```json
{
"mcpServers": {
"nutriref": {
"command": "nutriref-mcp",
"env": {
"PAYER_PRIVATE_KEY": "0x...your-funded-wallet-key...",
"NUTRIREF_BASE_URL": "https://nutriref.xyz"
}
}
}
}
```
> 如果不想安装？使用`uvx nutriref-mcp`作为`command`，按需运行。 如果要从克隆仓库运行，请执行`pip install -e ".[mcp]"`，并将`command`设置为`python`，参数为`["-m", "mcp_server"]`.
钱包需要在Base主网上拥有USDC - 由促进者赞助gas，因此您只需要稳定币余额。 代理现在具有`nutrition_search`、`nutrition_detail`、`nutrition_compare`、`nutrition_recipe`，并按调用自动支付。
## 从任何HTTP客户端使用
未支付的请求将获得`402 Payment Required`，并附有x402支付说明。 任何x402感知的客户端都会签署无gas的USDC授权（EIP-3009），并自动重试：
```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())
```
## 响应示例
`GET /v1/nutrition/detail/173944`:
```json
{
"fdc_id": 173944,
"description": "香蕉，生的",
"data_type": "基础",
"serving_size": 100, "serving_size_unit": "克",
"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
}
```
---
## 自主托管
NutriRef是开源的；`nutriref.xyz`上的实时实例是众多部署中的一个。 要运行您自己的实例：
```bash
cp .env.example .env
# 填写USDA_API_KEY（免费于https://fdc.nal.usda.gov/api-key-signup.html）
# 和X402_RECEIVER_ADDRESS（应接收付款的EVM地址）
docker compose up --build
curl http://localhost:8000/health
```
### 配置
| 变量 | 必需 | 默认值 | 目的 |
|---|---|---|---|
| `USDA_API_KEY` | 是 | — | 来自[fdc.nal.usda.gov](https://fdc.nal.usda.gov/api-key-signup.html)的免费密钥 |
| `USDA_BASE_URL` | 否 | `https://api.nal.usda.gov/fdc/v1` | |
| `REDIS_URL` | 否 | `redis://redis:6379/0` | 响应缓存 |
| `X402_NETWORK` | 否 | `base-sepolia` | 主网为`base` |
| `X402_RECEIVER_ADDRESS` | 是 | — | 接收USDC的EVM地址 |
| `X402_FACILITATOR_URL` | 否 | `https://x402.org/facilitator` | 主网为`https://api.cdp.coinbase.com` |
| `CDP_API_KEY_ID` | 仅限主网 | — | Coinbase Developer Platform密钥ID |
| `CDP_API_KEY_SECRET` | 仅限主网 | — | Coinbase Developer Platform密钥秘密 |
| `LOG_LEVEL` | 否 | `INFO` | |
对于主网，您需要Coinbase CDP账户和公共x402促进者，网址为`https://api.cdp.coinbase.com`。 测试网可免费使用社区促进者，网址为`https://x402.org/facilitator`.
### 架构
```
代理 → x402中间件 → 路由处理程序 → 缓存（Redis）→ USDA FDC API
```
`search`和`detail`直接缓存USDA响应。 `compare`和`recipe`由缓存的`detail`数据组成 - 预热时无需额外USDA调用。 缓存是一种有意义的成本杠杆：预热请求在<50ms内返回，且永远不会命中USDA.
### 测试
```bash
pip install -e ".[dev]"
pytest
```
## 示例：使用NutriRef的Claude代理
`examples/meal-planner/`是一个完整的、约150行的代理程序，为Claude提供了四个NutriRef端点作为工具，并要求其规划一天的膳食，以达到卡路里/蛋白质目标。 如果您将NutriRef集成到自己的代理中，值得阅读 - 工具架构和支付循环都在其中。 请参阅`examples/meal-planner/README.md`.
## 仓库布局
```
app/ # FastAPI服务
main.py # 应用程序工厂 + x402初始化
routes/ # search, detail, compare, recipe
landing.py # /（公共登陆页面）
discovery.py # /.well-known/x402, /llms.txt, /.well-known/ai-plugin.json, /logo.svg
usda.py # 异步USDA客户端
cache.py # Redis包装器
normalize.py # USDA → 平面13营养素架构
mcp_server/ # 代理使用的MCP服务器包装器
examples/ # 已完成的代理示例（膳食规划器）
scripts/ # CDP钱包启动 + 支付方测试
tests/ # pytest + respx + fakeredis
```
## 致谢
- [USDA FoodData Central](https://fdc.nal.usda.gov/) 提供数据。
- [x402](https://www.x402.org/) 提供支付协议。
- [`fastapi-x402`](https://pypi.org/project/fastapi-x402/) 提供服务器中间件（我们在启动时为Base主网USDC应用了一个小的EIP-712补丁）。
