Google Maps

Servidor MCP de Google Maps para Cloud Run

Un servidor de Google Maps Model Context Protocol (MCP) diseñado para su implementación en Google Cloud Run con acceso público. Este servidor proporciona funcionalidad de Google Maps a clientes de Claude Desktop a través de una API segura con límite de solicitudes.

Características

• Cálculo de rutas: Rutas de conducción óptimas con datos de tráfico en tiempo real
• Comparación de rutas: Compara múltiples alternativas de rutas con diferentes opciones
• Tráfico en vivo: Condiciones de tráfico actuales y análisis de tiempo de viaje
• Estimación de costos: Cálculos de costos de viaje, incluyendo estimaciones de combustible y peajes
• Acceso público: Sin autenticación requerida para compartir fácilmente
• Límite de solicitudes: 50 solicitudes por hora por dirección IP
• Optimizado para Cloud Run: Diseñado para implementación sin servidor en GCP

Requisitos previos

• Cuenta de Google Cloud Platform con facturación habilitada
• CLI de Google Cloud (gcloud) instalada y configurada
• Node.js 18+ para desarrollo local
• Clave API de Google Maps con las APIs requeridas habilitadas

APIs de Google Maps requeridas

Antes de la implementación, habilita estas APIs en tu proyecto de GCP:

1. Directions API - Para cálculos de rutas
2. Geocoding API - Para resolución de direcciones
3. Maps JavaScript API - Para codificación de polilíneas (opcional)

Habilita las APIs a través de Google Cloud Console o CLI:

gcloud services enable directions-backend.googleapis.com
gcloud services enable geocoding-backend.googleapis.com
gcloud services enable maps-backend.googleapis.com

Inicio rápido

1. Obtén tu clave API de Google Maps

1. Ve a Google Cloud Console > Credenciales
2. Crea una nueva clave API o usa una existente
3. Restringe la clave a las APIs requeridas mencionadas anteriormente
4. Anota tu clave API para la implementación

2. Implementa en Cloud Run

# Clone the repository
git clone <your-repo-url>
cd google-maps-mcp-cloudrun

# Set your Google Maps API key
export GOOGLE_MAPS_API_KEY="your-api-key-here"

# Deploy using the provided script
./simple-deploy.sh your-gcp-project-id us-central1

3. Extrae la URL del servicio

Después de la implementación, extrae la URL de tu servicio:

# Get the service URL
SERVICE_URL=$(gcloud run services describe google-maps-mcp \
  --region us-central1 \
  --format="value(status.url)")

echo "Your MCP Server URL: $SERVICE_URL/sse"

Implementación manual

Si prefieres la implementación manual:

# Set your project
gcloud config set project YOUR_PROJECT_ID

# Enable required services
gcloud services enable run.googleapis.com cloudbuild.googleapis.com

# Deploy
gcloud run deploy google-maps-mcp \
  --source . \
  --region us-central1 \
  --platform managed \
  --allow-unauthenticated \
  --set-env-vars GOOGLE_MAPS_API_KEY="your-api-key-here" \
  --memory 1Gi \
  --cpu 1 \
  --max-instances 10 \
  --timeout 300 \
  --port 8080

Configuración de Claude Desktop

Agrega esta configuración a tus ajustes de Claude Desktop:

{
  "mcpServers": {
    "google-maps": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://YOUR-SERVICE-URL.run.app/sse"
      ]
    }
  }
}

Reemplaza YOUR-SERVICE-URL.run.app con la URL real de tu servicio de Cloud Run.

Cómo encontrar tu configuración de Claude Desktop

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%/Claude/claude_desktop_config.json

Herramientas disponibles

El servidor MCP proporciona estas herramientas a Claude:

1. calculate_route - Calcula rutas de conducción óptimas con tráfico
2. compare_routes - Compara múltiples alternativas de rutas
3. get_live_traffic - Obtén condiciones de tráfico actuales
4. estimate_costs - Calcula costos de viaje (combustible + peajes)

Endpoints del servicio

• Endpoint MCP: https://your-service.run.app/sse
• Verificación de estado: https://your-service.run.app/health
• Estadísticas de uso: https://your-service.run.app/stats

Desarrollo local

# Install dependencies
npm install

# Copy environment template
cp .env.example .env

# Edit .env with your API key
# GOOGLE_MAPS_API_KEY=your-api-key-here

# Start development server
npm run dev

# Test locally
npm test

Solución de problemas

Problemas comunes de implementación

1. Permiso denegado

# Error: Permission denied
gcloud auth login
gcloud config set project YOUR_PROJECT_ID

2. API no habilitada

# Error: API not enabled
gcloud services enable run.googleapis.com
gcloud services enable cloudbuild.googleapis.com

3. Facturación no habilitada

• Visita Consola de Facturación de GCP
• Habilita la facturación para tu proyecto

4. Clave API no válida

# Check API key restrictions in Console
# Ensure Directions API and Geocoding API are enabled

5. El servicio no se inicia

# Check logs for errors
gcloud run services logs read google-maps-mcp --region us-central1 --limit 50

Problemas comunes en tiempo de ejecución

Límite de solicitudes

• Cada IP está limitada a 50 solicitudes por hora
• Consulta el endpoint /stats para ver el uso actual
• Considera implementar autenticación de usuarios para límites más altos

Cuota de API excedida

• Supervisa el uso de tu API de Google Maps en Consola de GCP
• Aumenta las cuotas si es necesario
• Considera implementar almacenamiento en caché para solicitudes repetidas

Prueba de tu implementación

# Test health endpoint
curl "https://your-service.run.app/health"

# Test stats endpoint
curl "https://your-service.run.app/stats"

# Test with Claude Desktop
# Add the configuration and try asking Claude to calculate a route

Consideraciones de seguridad

• La clave API se almacena como variable de entorno (segura)
• El servicio permite acceso público (sin autenticación requerida)
• El límite de solicitudes previene el abuso (50 solicitudes/hora por IP)
• No se registra ni almacena información sensible

Gestión de costos

• Cloud Run: Precio de pago por solicitud
• Google Maps API: Precio de pago por llamada a la API
• Monitoreo: Usa alertas de facturación de GCP para rastrear costos

Configura alertas de facturación:

# Set up billing budget alerts in GCP Console
# Billing > Budgets & Alerts

Enlaces de documentación

• Model Context Protocol (MCP)
• Documentación de Google Cloud Run
• Documentación de la plataforma Google Maps
• Configuración de MCP en Claude Desktop

Recursos de soporte y solución de problemas

• Solución de problemas de Cloud Run
• Solución de problemas de Google Maps API
• Soporte de GCP

Licencia

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

Contribuciones

1. Haz un fork del repositorio
2. Crea una rama de funcionalidad
3. Realiza tus cambios
4. Prueba exhaustivamente
5. Envía una solicitud de extracción

---

Nota: Este servidor está diseñado para fines de desarrollo y prueba. Para uso en producción con alto tráfico, considera implementar medidas de seguridad y monitoreo adicionales.