USDA Nutrition MCP Server

Access nutrition information for over 600,000 foods from the USDA FoodData Central database.

Professional Model Context Protocol (MCP) enabled server for USDA FoodData Central
Transforms 600k+ foods into intelligent nutrition tools for Claude Desktop and other MCP clients

This project showcasesprofessional MCP implementation skills:

✅Dual Architecture- Both MCP protocol server AND HTTP API
✅Production Bridge- Smartmcp_bridge.pywith hosted/local/custom server support
✅Three Deployment Options- Hosted service, local development, custom server
✅Type-Safe Models- Pydantic schemas with proper validation
✅Docker + Cloud Run- Complete deployment pipeline

Option 1: Minimal Installation (Recommended)

Download just the bridge file - no need to clone the entire repository:

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

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

# 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

Option 2: Full Repository (For Development)

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

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

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

Seeexamples/configs/claude_desktop_config_examples.jsonfor detailed configuration examples.

Live API:https://usda-nutrition-mcp-oc46l7ob5a-uc.a.run.app
Documentation: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}'

SeeAPI_USAGE.mdfor complete integration examples with Python, JavaScript, LangChain, and OpenAI.

You:"Compare the protein content of chicken breast vs salmon"
- search_foods("chicken breast")→ Finds FDC ID 171077
- search_foods("salmon")→ Finds FDC ID 175167
- compare_foods([171077, 175167])→ Gets comparison data
- Provides detailed analysis with recommendations

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

- src/mcp_server.py- FastMCP protocol server
- src/mcp_http_server.py- FastAPI HTTP server
- src/mcp_bridge.py- Smart bridge with server auto-detection
- src/usda_client.py- API client with retry logic
- src/models/- Type-safe Pydantic schemas

The bridge automatically detects server type and provides appropriate user feedback:

# 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

- Automatic SSL/HTTPS
- Health checks and monitoring
- Auto-scaling based on demand
- Structured logging

- FDC_API_KEY- USDA FoodData Central API key (required for local)
- ENVIRONMENT- "development" or "production"
- LOG_LEVEL- Logging level (DEBUG, INFO, etc.)

- Hosted Service: 1,000 requests/hour (shared)
- Local Deployment: 1,000 requests/hour (your key)
- Enterprise: Contact for higher limits

# 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

- USDA API mocking with httpx-mock
- Async MCP server testing
- Integration test examples
- Performance benchmarking
- Fork the repository
- Create feature branch:git checkout -b feature/amazing-feature
- Run tests:python -m pytest tests/
- Run linting:ruff check src/
- Submit pull request

MIT License - seeLICENSEfile for details.

🎯 Ready to use? Seeexamples/configs/claude_desktop_config_examples.jsonfor setup instructions!

🔗 Live API:https://usda-nutrition-mcp-oc46l7ob5a-uc.a.run.app/docs

Medical terminology intelligence for AI agents — ICD-10-CM lookup, MedDRA hierarchy and SOC mapping, RxNorm drug concepts, CTCAE v5.0 grading, and cross-terminology mapping.