USDA Nutrition MCP Server

Accede a información nutricional de más de 600,000 alimentos de la base de datos USDA FoodData Central.

GitHub
5
Prueba este MCPPatrocinado

Documentación

🥗 Servidor USDA Nutrition MCP Habilitado

Servidor profesional habilitado para Model Context Protocol (MCP) para USDA FoodData Central
Transforma más de 600,000 alimentos en herramientas inteligentes de nutrición para Claude Desktop y otros clientes MCP

License: MIT Python 3.11+ MCP Compatible Hosted Service

🌟 Lo Que Esto Demuestra

Este proyecto muestra habilidades profesionales de implementación de MCP:

✅ Arquitectura Dual - Tanto servidor de protocolo MCP como API HTTP
✅ Puente de Producción - mcp_bridge.py inteligente con soporte de servidores alojados, locales y personalizados
✅ Tres Opciones de Despliegue - Servicio alojado, desarrollo local, servidor personalizado
✅ Modelos Type-Safe - Esquemas Pydantic con validación adecuada
✅ Docker + Cloud Run - Pipeline de despliegue completo

🚀 Inicio Rápido para Claude Desktop

Opción 1: Instalación Mínima (Recomendada)

Descarga solo el archivo puente - no es necesario clonar el repositorio completo:

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

# Install dependencies
pip install mcp httpx

Luego agrega a tu configuración de Claude Desktop:

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

Usuarios de Mac con Entorno Virtual

# 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

Opción 2: Repositorio Completo (Para Desarrollo)

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

Opción 2: Desarrollo Local

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

Opción 3: Servidor Personalizado

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

Consulta examples/configs/claude_desktop_config_examples.json para ejemplos detallados de configuración.

🔧 Para Usuarios que No Usan Claude Desktop

API HTTP Directa

API en Vivo: https://usda-nutrition-mcp-oc46l7ob5a-uc.a.run.app
Documentación: 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}'

Consulta API_USAGE.md para ejemplos completos de integración con Python, JavaScript, LangChain y OpenAI.

🛠 Herramientas MCP Disponibles

Una vez configurado, Claude Desktop obtiene estas herramientas de nutrición:

  • search_foods - Busca en la base de datos USDA por texto
  • get_food_nutrition - Obtén nutrición detallada para alimentos específicos
  • compare_foods - Compara nutrición entre múltiples alimentos

Ejemplo de Interacción con Claude

Tú: "Compara el contenido de proteína entre pechuga de pollo y salmón"

Claude: Usa herramientas MCP automáticamente:

  1. search_foods("chicken breast") → Encuentra FDC ID 171077
  2. search_foods("salmon") → Encuentra FDC ID 175167
  3. compare_foods([171077, 175167]) → Obtiene datos de comparación
  4. Proporciona análisis detallado con recomendaciones

🏗 Inmersión Profunda en la Arquitectura

Diseño de Servidor Dual

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

Detalles Clave de Implementación:

  • src/mcp_server.py - Servidor de protocolo FastMCP
  • src/mcp_http_server.py - Servidor HTTP FastAPI
  • src/mcp_bridge.py - Puente inteligente con auto-detección de servidor
  • src/usda_client.py - Cliente API con lógica de reintentos
  • src/models/ - Esquemas Pydantic type-safe

Lógica del Puente Inteligente

El puente detecta automáticamente el tipo de servidor y proporciona retroalimentación adecuada al usuario:

# 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)")

📦 Instalación y Desarrollo

# 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/

🐳 Opciones de Despliegue

Desarrollo Local

# Run HTTP server locally
python -m src.mcp_http_server

# Run with Docker
make up

Despliegue en Producción

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

El despliegue en producción incluye:

  • SSL/HTTPS automático
  • Verificaciones de salud y monitoreo
  • Auto-escalado según demanda
  • Registro estructurado

🔑 Configuración

Variables de Entorno

  • FDC_API_KEY - Clave API de USDA FoodData Central (requerida para local)
  • ENVIRONMENT - "development" o "production"
  • LOG_LEVEL - Nivel de registro (DEBUG, INFO, etc.)

Límites de Tasa

  • Servicio Alojado: 1,000 solicitudes/hora (compartido)
  • Despliegue Local: 1,000 solicitudes/hora (tu clave)
  • Empresarial: Contacta para límites más altos

🧪 Estrategia de Pruebas

# 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

El conjunto de pruebas incluye:

  • Simulación de API USDA con httpx-mock
  • Pruebas de servidor MCP asíncrono
  • Ejemplos de pruebas de integración
  • Benchmarking de rendimiento

🤝 Contribuciones

  1. Haz un fork del repositorio
  2. Crea una rama de características: git checkout -b feature/amazing-feature
  3. Ejecuta las pruebas: python -m pytest tests/
  4. Ejecuta el linting: ruff check src/
  5. Envía una solicitud de extracción

📄 Licencia

Licencia MIT - consulta el archivo LICENSE para más detalles.

🎯 ¿Listo para usar? ¡Consulta examples/configs/claude_desktop_config_examples.json para instrucciones de configuración!

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