USDA Nutrition Mcp Server

🥗 USDA 栄養 MCP 対応サーバー

USDA FoodData Central 向けのプロフェッショナルな Model Context Protocol（MCP）対応サーバー
60 万件以上の食品を、Claude Desktop やその他の MCP クライアント向けのインテリジェントな栄養ツールに変換します

🌟 このプロジェクトで実証できること

このプロジェクトは、プロフェッショナルな MCP 実装スキルを示します。

✅ デュアルアーキテクチャ - MCP プロトコルサーバーと HTTP API の両方に対応
✅ 本番環境向けブリッジ - ホスト型／ローカル／カスタムサーバーに対応するスマートな mcp_bridge.py
✅ 3 種類のデプロイ方法 - ホスト型サービス、ローカル開発、カスタムサーバー
✅ 型安全なモデル - 適切なバリデーションを備えた Pydantic スキーマ
✅ Docker + Cloud Run - 完全なデプロイパイプライン

🚀 Claude Desktop ですぐに使う

オプション 1：最小限のインストール（推奨）

ブリッジファイルだけをダウンロードします。リポジトリ全体をクローンする必要はありません。

# Download the bridge
wget https://raw.githubusercontent.com/zen-apps/mcp-nutrition-tools/main/src/mcp_bridge.py

# Install dependencies
pip install mcp httpx

次に、Claude Desktop の設定に追加します。

{
  "mcpServers": {
    "usda-nutrition": {
      "command": "python3",
      "args": ["/path/to/downloaded/mcp_bridge.py"]
    }
  }
}

仮想環境を使用する Mac ユーザー向け

# Navigate to your project
cd /Users/yourusername/your-project-folder

# Create new venv in the project folder
python3 -m venv venv

# Activate it
source venv/bin/activate

# Install dependencies
pip install mcp httpx

# Test it works
python src/mcp_bridge.py --server-url https://usda-nutrition-mcp-356272800218.us-central1.run.app

オプション 2：リポジトリ全体（開発向け）

{
  "mcpServers": {
    "usda-nutrition": {
      "command": "python3",
      "args": ["/path/to/mcp-nutrition-tools/src/mcp_bridge.py"],
      "cwd": "/path/to/mcp-nutrition-tools"
    }
  }
}

オプション 2：ローカル開発

{
  "mcpServers": {
    "usda-nutrition": {
      "command": "python3",
      "args": [
        "/path/to/mcp-nutrition-tools/src/mcp_bridge.py",
        "--server-url",
        "http://localhost:8080"
      ],
      "cwd": "/path/to/mcp-nutrition-tools"
    }
  }
}

オプション 3：カスタムサーバー

{
  "mcpServers": {
    "usda-nutrition": {
      "command": "python3", 
      "args": [
        "/path/to/mcp-nutrition-tools/src/mcp_bridge.py",
        "--server-url",
        "https://your-server.com"
      ],
      "cwd": "/path/to/mcp-nutrition-tools"
    }
  }
}

詳しい設定例については、examples/configs/claude_desktop_config_examples.json を参照してください。

🔧 Claude Desktop 以外のユーザー向け

HTTP API を直接利用する

ライブ API：https://usda-nutrition-mcp-oc46l7ob5a-uc.a.run.app
ドキュメント：https://usda-nutrition-mcp-oc46l7ob5a-uc.a.run.app/docs

# Search foods
curl -X POST "https://usda-nutrition-mcp-oc46l7ob5a-uc.a.run.app/tools/search_foods" \
  -H "Content-Type: application/json" \
  -d '{"query": "chicken breast", "page_size": 5}'

# Get nutrition details  
curl -X POST "https://usda-nutrition-mcp-oc46l7ob5a-uc.a.run.app/tools/get_food_nutrition" \
  -H "Content-Type: application/json" \
  -d '{"fdc_id": 171688}'

Python、JavaScript、LangChain、OpenAI との完全な統合例については、API_USAGE.md を参照してください。

🛠 利用可能な MCP ツール

設定すると、Claude Desktop で以下の栄養ツールを利用できます。

• search_foods - テキストで USDA データベースを検索します
• get_food_nutrition - 特定の食品の詳しい栄養情報を取得します
• compare_foods - 複数の食品の栄養情報を比較します

Claude とのやり取りの例

あなた： 「鶏むね肉とサーモンのタンパク質含有量を比較して」

Claude： MCP ツールを自動的に使用します：

1. search_foods("chicken breast") → FDC ID 171077 を検索
2. search_foods("salmon") → FDC ID 175167 を検索
3. compare_foods([171077, 175167]) → 比較データを取得
4. 推奨事項を含む詳しい分析を提示

🏗 アーキテクチャの詳細

デュアルサーバー設計

Claude Desktop ←→ mcp_bridge.py ←→ HTTP API ←→ USDA FoodData Central
     (MCP)              ↑              ↑              ↑
                   Smart Bridge    FastAPI       Rate Limited
                                                   Client

主な実装の詳細：

• src/mcp_server.py - FastMCP プロトコルサーバー
• src/mcp_http_server.py - FastAPI HTTP サーバー
• src/mcp_bridge.py - サーバーを自動検出するスマートブリッジ
• src/usda_client.py - リトライロジックを備えた API クライアント
• src/models/ - 型安全な Pydantic スキーマ

スマートブリッジのロジック

ブリッジはサーバーの種類を自動的に検出し、適切なフィードバックをユーザーに提供します。

# Hosted service detection
if "usda-nutrition-mcp-oc46l7ob5a-uc.a.run.app" in args.server_url:
    print("🌐 Using hosted service (1,000 requests/hour shared)")

# Local development  
elif "localhost" in args.server_url:
    print("🏠 Using local server (requires your USDA API key)")

📦 インストールと開発

# Clone and setup
git clone https://github.com/zen-apps/mcp-nutrition-tools
cd mcp-nutrition-tools
pip install -r requirements.txt

# Get USDA API key (for local development)
# Visit: https://fdc.nal.usda.gov/api-guide.html
echo "FDC_API_KEY=your_key_here" > .env

# Test MCP server
python -m src.mcp_server

# Test HTTP server  
python -m src.mcp_http_server

# Run tests
python -m pytest tests/ -v

# Code quality
ruff check src/
ruff format src/
mypy src/

🐳 デプロイ方法

ローカル開発

# Run HTTP server locally
python -m src.mcp_http_server

# Run with Docker
make up

本番環境へのデプロイ

# Deploy to Google Cloud Run
export FDC_API_KEY="your_usda_key"
./scripts/deploy-gcp.sh

本番環境へのデプロイには以下が含まれます。

• SSL/HTTPS の自動設定
• ヘルスチェックとモニタリング
• 需要に応じた自動スケーリング
• 構造化ログ

🔑 設定

環境変数

• FDC_API_KEY - USDA FoodData Central API キー（ローカル環境で必要）
• ENVIRONMENT - 「development」または「production」
• LOG_LEVEL - ログレベル（DEBUG、INFO など）

レート制限

• ホスト型サービス：1,000 リクエスト／時間（共有）
• ローカルデプロイ：1,000 リクエスト／時間（ご自身のキーを使用）
• エンタープライズ：より高い上限についてはお問い合わせください

🧪 テスト戦略

# Quick connectivity test
python test_quick.py

# Full test suite with mocking
python -m pytest tests/ -v

# Test specific MCP tools
python examples/live_demo.py

テストスイートには以下が含まれます。

• httpx-mock による USDA API のモック
• 非同期 MCP サーバーのテスト
• 統合テストの例
• パフォーマンスのベンチマーク

🤝 コントリビューション

1. リポジトリをフォークします
2. 機能ブランチを作成します：git checkout -b feature/amazing-feature
3. テストを実行します：python -m pytest tests/
4. リントを実行します：ruff check src/
5. プルリクエストを送信します

📄 ライセンス

MIT ライセンスについては、LICENSE ファイルをご覧ください。

---

🎯 すぐに使えますか？セットアップ手順は examples/configs/claude_desktop_config_examples.json をご覧ください！

🔗 ライブ API：https://usda-nutrition-mcp-oc46l7ob5a-uc.a.run.app/docs