usda-mcp-server

---

概要

米国政府公認の食品成分データベース、USDA FoodData Central に収録された約 400,000 品目の食品栄養データを利用できます。キーワードまたは UPC で検索し、任意の分量に換算した栄養素の詳細情報を取得して、食品を並べて比較できます。

ツール

ツール	説明
usda_search_foods	SR Legacy、Foundation、Survey（FNDDS）、Branded の各データソースを対象に、キーワード、食材、UPC/GTIN で食品を検索します
usda_get_food	FDC ID で食品 1 品目の栄養素の詳細情報を取得します。分量に応じた換算も指定できます
usda_get_foods	1 回のリクエストで 2～20 個の FDC ID の栄養データを一括取得します
usda_compare_foods	2～5 品目の食品の栄養素を並べて比較し、Markdown テーブル形式で表示します
usda_list_nutrients	ID、名称、単位、カテゴリを含む FDC 栄養素参照テーブル（約 150 種）を提供します

リソース

リソース	説明
usda://food/{fdcId}	FDC ID で指定した食品の栄養素の詳細情報
usda://nutrients	FDC 栄養素の参照リスト全体
skill://usda-guide/SKILL.md	エージェント向けの食品選択、分量の重量、栄養素データの欠損に関するガイダンス

食品の詳細情報と栄養素の参照情報は、ツールからも取得できます。食品リソースを読み込む前に、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 を超えるページを指定した場合、検索条件に一致する食品があれば、有効な pageNumber を示す通知とともに、空の foods[]、要求されたページ、合計数を返します。
• 型付きエラー：query_empty（クエリが空白）、query_syntax（FDC がクエリ構文を拒否）、no_results（指定したデータソースに一致する結果がない）

---

usda_get_food _ツール

• 1 つの fdcId の全栄養プロファイルを返します。任意の nutrients[] フィルターで特定の ID に絞り込めます。
• 任意の unit（g / oz / lb / kg / serving）を指定すると、任意の quantity に応じて FDC の 100 g あたりの基準値からすべての値を換算します。質量単位では quantity のデフォルトは 100、serving では 1 です。サービングの場合、最初の有効な分量を使用します。分量がない場合は、g / GRM / GM（大文字と小文字を区別しない）で表された正の有限値の Branded ラベル上の容量に quantity を掛けます。
• servingInfo は、解決された分量またはラベル上のサービングとそのグラム重量を示します。allPortions[] には実際の分量定義のみが含まれます。
• 型付きエラー：not_found（FDC ID が不正）、quantity_without_unit、no_portion_data（有効な分量またはサポート対象の Branded のグラム単位ラベルがない）。体積、IU、ミリグラム単位のラベル、単位の欠損、無効な容量の場合は、明示的に質量単位を指定する必要があります。密度は推定されません。

---

usda_get_foods _ツール

• 1 回の呼び出しで 2～20 個の FDC ID を一括取得します。値は 100 g あたりのみで、分量換算は行われません。
• nutrients[] フィルターの使用を強く推奨します。20 品目の全栄養プロファイルは大きなデータになります。
• ID ごとに部分的な失敗を処理します。データが返されない ID はバッチ全体を中断せず、failed[] に格納されます。

---

usda_compare_foods _ツール

• 2～5 個の FDC ID を横並びで比較します。栄養素ごとに 1 行、食品ごとに 1 列の形式です。
• 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 と同じデータを、分量換算なしで返します。全栄養プロファイルを 100 g あたりの値として application/json 形式で提供します。
• fdcId は正の整数のみを指定できます（符号、先頭のゼロ、小数、指数表記は不可）。それ以外の場合は invalid_id をスローします。
• ID が FDC に存在しない場合は not_found になります。

---

usda://nutrients _リソース

• FDC 栄養素の完全な参照情報です。カテゴリーのフィルターがない usda_list_nutrients と同じ内容です。
• テーブルはビルド時に同梱され、すべての呼び出し元で同一であるため、1 時間のパブリックキャッシュヒント付きで application/json 形式で提供されます。

skill://usda-guide/SKILL.md _リソース

食品レコードの照合、1食分の重量の選択、不完全な栄養素データの報告に関するガイダンスです。同じusda-guideが、プラグインのインストール、npm、Docker、デスクトップバンドルにも含まれています。

機能

@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呼び出しは不要です

エージェントに適した出力：

• 出典情報を保持 — すべての食品結果にFDCデータソース（dataType）を含めるため、呼び出し元は、厳選された研究データとラベル由来のブランド値のどちらを参照しているか確認できます
• 部分的な失敗の報告 — バッチツール（usda_get_foods、usda_compare_foods）はリクエスト全体を失敗させるのではなく、成功した結果と構造化されたfailed[] / missingData[]エントリを併せて返します
• 相互参照のヒント — 説明にFDC IDとツール名を記載し、エージェントが次に呼び出すべきツールを正確に把握できるようにします（検索 → 取得 → 比較のワークフロー）

はじめに

インストールせずに、ホストされたインスタンスに接続します。

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	サーバー固有の環境変数（USDA_FDC_API_KEY）を Zod で解析・検証します。
src/mcp-server/tools	ツール定義（*.tool.ts）です。検索、取得、一括処理、比較、栄養素の一覧表示を行います。
src/mcp-server/resources	リソース定義（*.resource.ts）です。食品プロファイルと栄養素リファレンスを提供します。
src/services/fdc	FdcService です。USDA FDC API クライアント、データの正規化、静的な栄養素リファレンスデータを扱います。
skills/	サーバーを呼び出すエージェント向けに公開されるガイダンスです。
tests/	src/ に対応する単体テストです。すべてのツール、リソース、FDC サービスを対象とします。

開発ガイド

開発ガイドラインとアーキテクチャ上のルールについては、CLAUDE.md を参照してください。要点は次のとおりです。

• ハンドラーは例外をスローし、フレームワークが捕捉します。ツールのロジックで try/catch を使用しないでください
• リクエスト単位のログには ctx.log を、テナント単位のストレージには ctx.state を使用してください
• src/mcp-server/*/definitions/index.ts のバレル経由で新しいツールとリソースを登録してください
• 外部 API 呼び出しは、未加工データの検証 → ドメイン型への正規化 → 出力スキーマの返却という手順でラップしてください。不足しているフィールドを捏造しないでください

貢献

Issue を歓迎します。提出前にチェックとテストを実行してください。

bun run devcheck
bun run test

ライセンス

Apache-2.0 — 詳細は LICENSE を参照してください。