Traffic MCP Server (SSE Transport)
Servidor MCP (Model Context Protocol) con transporte SSE (Server-Sent Events) que consume una API REST de predicción de tráfico. Diseñado para despliegue en la nube y consumo remoto.
Características
Este servidor MCP proporciona 3 herramientas principales:
- get_traffic_stations - Obtiene la lista de estaciones de tráfico disponibles
- predict_traffic_spi - Predice el Speed Performance Index usando modelo LSTM
- suggest_routes - Sugiere rutas óptimas entre estaciones usando Dijkstra
Instalación Local
Requisitos
- Python 3.10 o superior
- pip
Instalar dependencias
cd traffic_mcp_server
pip install mcp httpx starlette uvicorn[standard]
O usando el archivo de proyecto:
pip install -e .
Configuración
Variables de Entorno
TRAFFIC_API_URL: URL base de la API de tráfico (default: https://traffict-predict-api-452792205673.southamerica-west1.run.app)MCP_API_KEY: API key para autenticación (default: your-secure-api-key-here)PORT: Puerto del servidor (default: 8080)
Ejecutar localmente
# Con variables de entorno por defecto
python server.py
# Con variables de entorno personalizadas
export MCP_API_KEY="mi-api-key-segura"
export PORT=3000
python server.py
El servidor estará disponible en:
- SSE endpoint:
http://localhost:8080/sse - Health check:
http://localhost:8080/health
Despliegue en la Nube
Opción 1: Docker Local
# Construir la imagen
docker build -t traffic-mcp-server .
# Ejecutar el contenedor
docker run -p 8080:8080 \
-e MCP_API_KEY="mi-api-key-segura" \
-e TRAFFIC_API_URL="https://traffict-predict-api-452792205673.southamerica-west1.run.app" \
traffic-mcp-server
Opción 2: Google Cloud Run
# Configurar el proyecto de Google Cloud
export PROJECT_ID="tu-proyecto-gcp"
export SERVICE_NAME="traffic-mcp-server"
export REGION="us-central1"
# Construir y subir la imagen a Google Container Registry
gcloud builds submit --tag gcr.io/$PROJECT_ID/$SERVICE_NAME
# Desplegar en Cloud Run
gcloud run deploy $SERVICE_NAME \
--image gcr.io/$PROJECT_ID/$SERVICE_NAME \
--platform managed \
--region $REGION \
--allow-unauthenticated \
--set-env-vars MCP_API_KEY="tu-api-key-segura" \
--set-env-vars TRAFFIC_API_URL="https://traffict-predict-api-452792205673.southamerica-west1.run.app" \
--port 8080
# Obtener la URL del servicio
gcloud run services describe $SERVICE_NAME --region $REGION --format='value(status.url)'
Opción 3: AWS (ECS/Fargate)
# Crear repositorio ECR
aws ecr create-repository --repository-name traffic-mcp-server
# Autenticar Docker con ECR
aws ecr get-login-password --region us-east-1 | docker login --username AWS --password-stdin <account-id>.dkr.ecr.us-east-1.amazonaws.com
# Construir y subir imagen
docker build -t traffic-mcp-server .
docker tag traffic-mcp-server:latest <account-id>.dkr.ecr.us-east-1.amazonaws.com/traffic-mcp-server:latest
docker push <account-id>.dkr.ecr.us-east-1.amazonaws.com/traffic-mcp-server:latest
# Crear tarea y servicio en ECS (usar consola de AWS o CLI)
Opción 4: Heroku
# Login en Heroku
heroku login
# Crear app
heroku create traffic-mcp-server
# Configurar variables de entorno
heroku config:set MCP_API_KEY="tu-api-key-segura"
heroku config:set TRAFFIC_API_URL="https://traffict-predict-api-452792205673.southamerica-west1.run.app"
# Desplegar usando Git
git init
git add .
git commit -m "Initial commit"
heroku git:remote -a traffic-mcp-server
git push heroku main
Configuración en Claude Desktop
Una vez desplegado el servidor, configura Claude Desktop para usar el servidor remoto:
Configuración con SSE Transport
Agrega la siguiente configuración a tu archivo claude_desktop_config.json:
{
"mcpServers": {
"traffic-api": {
"url": "https://tu-servidor-desplegado.com/sse",
"transport": {
"type": "sse",
"headers": {
"Authorization": "Bearer tu-api-key-segura"
}
}
}
}
}
Ejemplo con Google Cloud Run:
{
"mcpServers": {
"traffic-api": {
"url": "https://traffic-mcp-server-xxxxx.a.run.app/sse",
"transport": {
"type": "sse",
"headers": {
"Authorization": "Bearer mi-api-key-super-segura-2024"
}
}
}
}
}
Notas importantes:
- Reemplaza
tu-servidor-desplegado.comcon la URL real de tu servidor desplegado - Reemplaza
tu-api-key-seguracon la misma API key que configuraste en el servidor (variableMCP_API_KEY) - Reinicia Claude Desktop después de modificar la configuración
Uso
Herramientas Disponibles
1. get_traffic_stations
Obtiene información de estaciones de tráfico con filtros opcionales.
Parámetros:
freeway(opcional): Número de autopista para filtrardirection(opcional): Dirección (N, S, E, W)
Ejemplo de uso en Claude:
¿Cuáles son las estaciones de la autopista 101 dirección Norte?
2. predict_traffic_spi
Predice el índice de rendimiento de velocidad usando datos históricos de 1 hora.
Parámetros:
sequence(requerido): Lista de 12 intervalos de 5 minutos, cada uno con 7 valores:- Total_Flow
- Avg_Occupancy
- Avg_Speed
- Hour
- Day_of_Week
- Lanes
- Lane_Type_encoded
Ejemplo de uso en Claude:
Predice el tráfico con esta secuencia: [[100, 0.5, 60, 8, 1, 4, 1], [105, 0.52, 58, 8, 1, 4, 1], ...]
Respuesta incluye:
- SPI predicho (0-100)
- Nivel de congestión (0-3)
- Clasificación difusa con membresías
- Descripción lingüística del estado
- Estado de transición
3. suggest_routes
Sugiere rutas óptimas entre dos estaciones considerando condiciones actuales.
Parámetros:
origin_station(requerido): ID de estación origendestination_station(requerido): ID de estación destinocurrent_predictions(requerido): Diccionario {station_id: spi_value}num_routes(opcional): Número de rutas alternativas (1-5, default: 3)
Ejemplo de uso en Claude:
Sugiere la mejor ruta desde la estación 400001 hasta la 400050 considerando estas predicciones de SPI: {400001: 85.5, 400002: 75.2, ...}
Respuesta incluye:
- Rutas ordenadas por tiempo total
- Distancia y tiempo estimado
- SPI promedio y mínimo por ruta
- Porcentaje de congestión
- Recomendación de mejor ruta
Endpoints del Servidor
POST /sse- Endpoint SSE para conexiones MCP (requiere autenticación)GET /health- Health check del servidor
API Endpoints Consumidos
El servidor se conecta a los siguientes endpoints de la API de tráfico:
GET /stations- Obtiene todas las estaciones disponiblesPOST /predict- Realiza predicción SPI usando LSTMPOST /routes/suggest- Calcula rutas óptimas con Dijkstra
Estructura del Proyecto
traffic_mcp_server/
├── server.py # Servidor MCP con SSE transport
├── pyproject.toml # Configuración del proyecto
├── Dockerfile # Configuración Docker para despliegue
└── README.md # Esta documentación
Seguridad
Autenticación
El servidor implementa autenticación básica mediante API Key:
- Las solicitudes al endpoint
/ssedeben incluir el header:Authorization: Bearer <API_KEY> - La API key se valida contra la variable de entorno
MCP_API_KEY - Conexiones no autenticadas reciben error 401
Recomendaciones
-
Genera una API key segura:
python -c "import secrets; print(secrets.token_urlsafe(32))" -
Usa HTTPS en producción (Cloud Run, Heroku y similares lo proporcionan automáticamente)
-
No expongas la API key en código fuente - usa variables de entorno
-
Restringe CORS en producción si es necesario (modificar
allow_originsenserver.py)
Monitoreo
Health Check
Verifica el estado del servidor:
curl https://tu-servidor.com/health
Respuesta esperada:
{
"status": "healthy",
"service": "traffic-mcp-server",
"traffic_api_url": "https://traffict-predict-api-452792205673.southamerica-west1.run.app"
}
Logs
El servidor usa logging estándar de Python. En producción:
Google Cloud Run:
gcloud logging read "resource.type=cloud_run_revision AND resource.labels.service_name=traffic-mcp-server" --limit 50
Heroku:
heroku logs --tail -a traffic-mcp-server
Docker:
docker logs <container-id> -f
Troubleshooting
Error 401 Unauthorized
Verifica que:
- El header
Authorizationesté incluido en la configuración de Claude Desktop - La API key coincida exactamente con
MCP_API_KEYdel servidor - El formato sea
Bearer <tu-api-key>(con espacio después de Bearer)
Conexión rechazada
Verifica que:
- El servidor esté corriendo (
/healthendpoint responde) - La URL en
claude_desktop_config.jsonsea correcta - El firewall/security group permita conexiones entrantes
Errores de la API de tráfico
Verifica que:
TRAFFIC_API_URLesté configurada correctamente- La API de tráfico esté disponible
- Los logs del servidor para detalles específicos
El servidor no aparece en Claude Desktop
Asegúrate de:
- Haber reiniciado Claude Desktop después de modificar la configuración
- La configuración JSON esté bien formada (sin errores de sintaxis)
- La URL del servidor incluya el path
/sse
Desarrollo
Ejecutar tests
pip install -e ".[dev]"
pytest
Desarrollo local con hot reload
uvicorn server:app --reload --host 0.0.0.0 --port 8080
Escalabilidad
Consideraciones de Rendimiento
- El servidor es asíncrono y puede manejar múltiples conexiones concurrentes
- Cada conexión SSE mantiene una sesión activa
- Timeouts configurados: 10s connect, 30s total por request
Escalado Horizontal
En Cloud Run o ECS, configura auto-scaling basado en:
- Número de conexiones concurrentes
- CPU/Memoria usage
- Request latency
Licencia
MIT
Soporte
Para reportar problemas o solicitar características, abre un issue en el repositorio del proyecto.
