usda-mcp-server

---

概览

USDA FoodData Central 收录了约 400,000 种食品的营养数据，是美国政府的权威食品成分数据库。可按关键词或 UPC 搜索，获取按任意份量换算的完整营养成分信息，并排比较不同食品。

工具

工具	描述
usda_search_foods	按关键词、配料或 UPC/GTIN 搜索 SR Legacy、Foundation、Survey (FNDDS) 和 Branded 数据源中的食品
usda_get_food	根据 FDC ID 获取单种食品的完整营养成分信息，可选按份量换算
usda_get_foods	在单个请求中批量获取 2–20 个 FDC ID 对应的营养成分信息
usda_compare_foods	并排比较 2–5 种食品的营养成分，并格式化为 Markdown 表格
usda_list_nutrients	静态 FDC 营养素参考表（约 150 种营养素），包含 ID、名称、单位和类别

资源

资源	描述
usda://food/{fdcId}	根据 FDC ID 获取指定食品的完整营养成分信息
usda://nutrients	完整的 FDC 营养素参考列表
skill://usda-guide/SKILL.md	面向 Agent 的食品选择、份量重量和营养素缺失情况指南

也可以通过工具访问食品资料和营养素参考信息。读取食品资源前，先使用 usda_search_foods 查找 FDC ID。

功能参考

usda_search_foods _工具

• 按关键词、食材名称或 UPC/GTIN 代码查询；可选使用 dataType[] 筛选 SR Legacy、Foundation、Survey (FNDDS) 和 Branded，默认值为 ["SR Legacy"]（设置 brandOwner 后则默认为 ["Branded"]）
• 使用 brandOwner 和 foodCategory 筛选结果；通过 pageSize（最大 50，默认 10）和 pageNumber 分页
• 返回 FDC ID 及可用的预览营养素：蛋白质 (1003)、脂肪 (1004)、碳水化合物 (1005)、纤维 (1079) 和能量 (1008、1062、2047、2048)。保留原始数值、单位、顺序和不同的能量估算值；省略缺失项。要获取其他营养素或完整营养成分，请使用 usda_get_food
• 当查询有匹配项时，超过 totalPages 的页面会返回空的 foods[]、请求的页面、总数，以及包含有效 pageNumber 的提示
• 类型化错误：query_empty（查询为空白）、query_syntax（FDC 拒绝了查询语法）、no_results（请求的数据源中没有匹配项）

---

usda_get_food _工具

• 获取一个 fdcId 的完整营养成分；可选使用 nutrients[] 筛选特定 ID
• 可选的 unit（g / oz / lb / kg / serving）配合可选的 quantity，可按比例缩放 FDC 以每 100 g 为基准的所有数值；对于质量单位，quantity 默认为 100；对于 serving，默认为 1。serving 使用第一个有效份量；如果没有份量，则使用以 g / GRM / GM 为单位的正有限 Branded 标签份量（不区分大小写），再乘以 quantity
• servingInfo 标明解析出的份量或标签份量及其克重；allPortions[] 仅包含实际份量定义
• 类型化错误：not_found（FDC ID 无效）、quantity_without_unit、no_portion_data（没有有效份量或受支持的 Branded 克数标签）。体积、IU、毫克标签、缺失单位和无效大小都需要显式请求质量单位；不会推断密度

---

usda_get_foods _工具

• 一次调用批量获取 2–20 个 FDC ID；数值仅按每 100 g 返回（不按份量缩放）
• 强烈建议使用 nutrients[] 筛选——20 种食物的完整营养成分会很大
• 按 ID 部分失败——未返回数据的 ID 会列入 failed[]，不会导致整个批次中止

---

usda_compare_foods _工具

• 并排比较 2–5 个 FDC ID，按每种营养素一行、每种食物一列透视呈现
• 除非指定 nutrients[]，否则默认比较 12 种常见营养素（能量、蛋白质、脂肪、饱和脂肪、碳水化合物、纤维、总糖、钠、钾、钙、铁、维生素 C）
• 所有数值均缩放到统一的 quantity + unit 基准（默认为 100 g；quantity 是以 unit 为单位的数量，因此仅设置 unit: "oz" 时，比较基准为每 100 oz）
• 部分 ID 未返回数据时，仍使用有效食物继续处理；只有解析出的食物少于 2 种时才会抛出 too_few_foods
• 过滤掉所有食物在该营养素下均为 null 的行

---

usda_list_nutrients _工具

• 静态参考表，列出约 150 种受追踪的 FDC 营养素——不调用 API
• 可选的 category 筛选：macronutrients、vitamins、minerals、lipids、amino_acids、other
• 返回每种营养素的 ID、名称、SR 参考编号、单位和类别——可将名称解析为其他位置 nutrients[] 使用的 ID

---

usda://food/{fdcId} _资源

• 数据与 usda_get_food 相同，但不按份量缩放——以 application/json 格式返回每 100 g 的完整营养成分
• fdcId 必须是纯正整数（不带正负号、前导零、小数或指数）；其他任何值都会抛出 invalid_id
• 如果该 ID 在 FDC 中不存在，则返回 not_found

---

usda://nutrients _资源

• 完整的 FDC 营养素参考表——内容与未指定类别筛选的 usda_list_nutrients 相同
• 以 application/json 格式提供，并附带 1 小时的公共缓存提示，因为该表在构建时已打包，且对所有调用方都相同

skill://usda-guide/SKILL.md _资源

关于如何匹配食物记录、选择份量重量，以及报告营养素覆盖不完整情况的指南。插件安装包、npm、Docker 和桌面套件中均附带相同的 usda-guide。

功能

基于 @cyanheads/mcp-ts-core 构建：支持 stdio 和 Streamable HTTP 传输、可插拔身份验证（none / jwt / oauth）、可切换存储（in-memory、filesystem、Supabase、Cloudflare KV/R2/D1），以及支持可选 OpenTelemetry 跟踪的结构化日志记录。

FoodData Central 专属功能：

• USDA FoodData Central REST API（api.nal.usda.gov/fdc/v1）的类型安全客户端
• 规范化层，可处理搜索、单条食物和批量端点返回的不一致 API 响应格式
• 批量 API 端点（/foods），支持报告每种食物的部分失败情况
• 检测 HTML 响应（限流代理会返回 200 HTML），并明确报告服务不可用错误
• 静态营养素参考字典——约 150 种营养素，包含 FDC ID、SR 编号、单位和类别；无需调用 API

便于 Agent 使用的输出：

• 保留来源信息——每条食物结果都包含 FDC 数据来源（dataType），让调用方知道读取的是经过整理的研究数据，还是从标签提取的品牌值
• 部分失败报告——批量工具（usda_get_foods、usda_compare_foods）会在返回成功结果的同时，提供结构化的 failed[] / missingData[] 条目，而不是让整个请求失败
• 交叉引用提示——描述中包含 FDC ID 和工具名称，让 Agent 明确知道接下来要调用哪个工具（搜索 → 获取 → 比较工作流）

开始使用

连接到托管实例，无需安装：

claude mcp add --transport http usda-mcp-server https://usda.caseyjhand.com/mcp

或在本地运行：

claude mcp add usda-mcp-server -e USDA_FDC_API_KEY=your-key -- npx -y @cyanheads/usda-mcp-server

对于其他客户端，将以下内容添加到 MCP 配置文件中：

{
  "mcpServers": {
    "usda-mcp-server": {
      "command": "npx",
      "args": ["-y", "@cyanheads/usda-mcp-server"],
      "env": { "USDA_FDC_API_KEY": "your-api-key" }
    }
  }
}

前往 api.data.gov/signup 免费获取密钥。搜索、查询和比较食物都需要密钥；静态营养素参考功能则不需要。如需使用 Docker 或从源码构建，请参阅运行服务。

配置

变量	描述	默认值
USDA_FDC_API_KEY	FoodData Central 相关工具所必需（搜索、获取、批量处理、比较）——启动服务或使用 usda_list_nutrients 无需此密钥。前往 api.data.gov 免费获取。	—
MCP_TRANSPORT_TYPE	传输方式：stdio 或 http。	stdio
MCP_HTTP_PORT	HTTP 服务的端口。	3010
MCP_AUTH_MODE	身份验证模式：none、jwt 或 oauth。	none
MCP_LOG_LEVEL	日志级别（RFC 5424）。	info
LOGS_DIR	日志文件目录（仅限 Node.js）。	<project-root>/logs
STORAGE_PROVIDER_TYPE	存储后端。	in-memory
OTEL_ENABLED	启用 OpenTelemetry 埋点（跨度、指标、完成日志）。	false

完整的可选覆盖项列表，请参阅 .env.example。

运行服务

需要 Bun v1.4.0 或更高版本（或 Node.js v24+）。

本地开发

git clone https://github.com/cyanheads/usda-mcp-server.git
cd usda-mcp-server && bun install
cp .env.example .env   # set USDA_FDC_API_KEY

• 构建并运行：

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:stdio
  # or
  bun run start:http
  

• 运行检查和测试：

  bun run devcheck   # Lint, format, typecheck, security
  bun run test       # Vitest test suite
  bun run lint:mcp   # Validate MCP definitions against spec
  

Docker

docker run --rm -e USDA_FDC_API_KEY=your-key -p 3010:3010 ghcr.io/cyanheads/usda-mcp-server:latest

镜像默认使用 HTTP 传输、无状态会话模式，并将日志写入 /var/log/usda-mcp-server。如需使用 stdio，请运行 docker run -i --rm -e MCP_TRANSPORT_TYPE=stdio -e USDA_FDC_API_KEY=your-key ghcr.io/cyanheads/usda-mcp-server:latest。如需在本地构建，请运行 docker build -t usda-mcp-server .；默认会安装 OpenTelemetry 对等依赖项，如需省略这些依赖项，可使用 --build-arg OTEL_ENABLED=false 构建。

项目结构

目录	用途
src/index.ts	createApp() 入口点 — 注册工具和资源，并初始化 FdcService。
src/config	使用 Zod 解析和验证服务专用环境变量（USDA_FDC_API_KEY）。
src/mcp-server/tools	工具定义（*.tool.ts）— 搜索、获取、批量处理、比较、列出营养素。
src/mcp-server/resources	资源定义（*.resource.ts）— 食品档案和营养素参考资料。
src/services/fdc	FdcService — USDA FDC API 客户端、数据规范化和静态营养素参考数据。
skills/	为调用该服务的 Agent 提供的已发布指南。
tests/	与 src/ 对应的单元测试 — 覆盖每个工具、资源和 FDC 服务。

开发指南

开发指南和架构规则请参阅 CLAUDE.md。简要说明：

• 处理程序抛出异常，由框架捕获 — 工具逻辑中不使用 try/catch
• 使用 ctx.log 记录请求范围内的日志，使用 ctx.state 存储租户范围内的数据
• 通过 src/mcp-server/*/definitions/index.ts 中的 barrel 文件注册新工具和资源
• 封装外部 API 调用：验证原始数据 → 规范化为领域类型 → 返回输出架构；绝不伪造缺失字段

贡献

欢迎提交问题。提交前请运行检查和测试：

bun run devcheck
bun run test

许可证

Apache-2.0 — 详情请参阅 LICENSE。