google-maps-mcp-server

Servidor MCP basado en STDIO para las APIs de Google Maps Platform

Documentación

Google Maps MCP Server

Un servidor de Model Context Protocol (MCP) que proporciona acceso integral a las APIs de Google Maps Platform. Este servidor permite a los LLMs realizar geocodificación, búsqueda de lugares, enrutamiento y otras operaciones geoespaciales a través de una interfaz estandarizada.

Características

🗺️ Integración integral de Google Maps - Acceso a las APIs de Places, Routes, Geocoding y utilidades
🔍 Búsqueda avanzada de lugares - Búsqueda por texto, búsqueda cercana, autocompletado e información detallada de lugares
🛣️ Enrutamiento inteligente - Cálculo de rutas con tráfico en tiempo real, peajes y rutas alternativas
📍 Geocodificación precisa - Geocodificación directa e inversa con soporte internacional
🌐 Servicios de geolocalización - Estimación de ubicación basada en IP y WiFi/celular
📊 Recursos enriquecidos - Documentación y ejemplos integrados accesibles a través de recursos MCP
🔒 Seguridad primero - Validación de entrada, limitación de velocidad y manejo seguro de claves API

Inicio rápido

1. Obtener la clave API de Google Maps

Visita la Google Cloud Console
Crea un nuevo proyecto o selecciona uno existente
Habilita las APIs requeridas (consulta los requisitos de API por herramienta a continuación)
Crea una clave API y restringe su uso a las APIs habilitadas
Importante: Este servidor utiliza las nuevas APIs de Google Maps Platform (Places API (New) y Routes API), no las versiones heredadas

Requisitos de API por herramienta

Herramienta	API requerida de Google Cloud Console
`geocode_search`, `geocode_reverse`	Geocoding API
`places_search_text`, `places_nearby`, `places_autocomplete`, `places_details`, `places_photos`	Places API (New)
`routes_compute`, `routes_matrix`	Routes API
`elevation_get`	Elevation API
`timezone_get`	Time Zone API
`geolocation_estimate`	Geolocation API
`roads_nearest`	Roads API
`ip_geolocate`, `nearby_find`	Geolocation API + Places API (New)

2. Configurar el cliente MCP

Añade el servidor a la configuración de tu cliente MCP:

Cursor

Añade a la configuración MCP de Cursor (~/.cursor/mcp.json o mediante Command Palette > Open MCP Settings > New MCP Server):

{
  "mcpServers": {
    "google-maps": {
      "command": "npx",
      "args": ["-y", "google-maps-mcp-server"],
      "env": {
        "GOOGLE_MAPS_API_KEY": "your-api-key-here"
      }
    }
  }
}

Con limitación de velocidad personalizada:

{
  "mcpServers": {
    "google-maps": {
      "command": "npx",
      "args": ["-y", "google-maps-mcp-server"],
      "env": {
        "GOOGLE_MAPS_API_KEY": "your-api-key-here",
        "GOOGLE_MAPS_RATE_LIMIT_ENABLED": "true",
        "GOOGLE_MAPS_RATE_LIMIT_WINDOW_MS": "120000",
        "GOOGLE_MAPS_RATE_LIMIT_MAX_REQUESTS": "200"
      }
    }
  }
}

Claude Desktop

Añade a claude_desktop_config.json:

{
  "mcpServers": {
    "google-maps": {
      "command": "npx",
      "args": ["google-maps-mcp-server"],
      "env": {
        "GOOGLE_MAPS_API_KEY": "your-api-key-here"
      }
    }
  }
}

Con limitación de velocidad deshabilitada:

{
  "mcpServers": {
    "google-maps": {
      "command": "npx",
      "args": ["google-maps-mcp-server"],
      "env": {
        "GOOGLE_MAPS_API_KEY": "your-api-key-here",
        "GOOGLE_MAPS_RATE_LIMIT_ENABLED": "false"
      }
    }
  }
}

Otros clientes MCP

# Set environment variable
export GOOGLE_MAPS_API_KEY="your-api-key-here"

# Run the server
npx google-maps-mcp-server

Herramientas disponibles

Geocodificación

geocode_search - Convierte direcciones en coordenadas
geocode_reverse - Convierte coordenadas en direcciones

Lugares

places_search_text - Busca lugares con lenguaje natural
places_nearby - Encuentra lugares dentro de un radio
places_autocomplete - Obtén sugerencias de lugares
places_details - Obtén información detallada de lugares
places_photos - Obtén URLs de fotos de lugares

Enrutamiento

routes_compute - Calcula rutas óptimas
routes_matrix - Calcula matrices de distancias

Utilidades

elevation_get - Obtén datos de elevación
timezone_get - Obtén información de zona horaria
geolocation_estimate - Estima la ubicación a partir de datos WiFi/celular
roads_nearest - Encuentra las carreteras más cercanas

Herramientas especiales

nearby_find - Encuentra ciudades, pueblos o POIs cercanos
ip_geolocate - Geolocaliza usando dirección IP

Ejemplos de uso

Encontrar restaurantes cercanos

{
  "tool": "places_nearby",
  "arguments": {
    "location": {"lat": 37.7749, "lng": -122.4194},
    "radius_meters": 1000,
    "included_types": ["restaurant"],
    "max_results": 10
  }
}

Obtener indicaciones de conducción

{
  "tool": "routes_compute",
  "arguments": {
    "origin": {"address": "San Francisco, CA"},
    "destination": {"address": "Los Angeles, CA"},
    "travel_mode": "DRIVE",
    "routing_preference": "TRAFFIC_AWARE"
  }
}

Geocodificar una dirección

{
  "tool": "geocode_search",
  "arguments": {
    "query": "1600 Amphitheatre Parkway, Mountain View, CA",
    "language": "en"
  }
}

Geolocalizar por dirección IP

{
  "tool": "ip_geolocate",
  "arguments": {
    "reverse_geocode": true
  }
}

La herramienta ip_geolocate también admite un parámetro opcional ip_override para probar con diferentes direcciones IP:

{
  "tool": "ip_geolocate",
  "arguments": {
    "ip_override": "8.8.8.8",
    "reverse_geocode": true
  }
}

Nota: El parámetro ip_override acepta direcciones IPv4 o IPv6 públicas. Los rangos de IP privados y reservados (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, 127.0.0.0/8) son rechazados. La anulación de IP se realiza con el mejor esfuerzo y la API de Geolocalización de Google puede no siempre respetar la solicitud.

Configuración

Variables de entorno

GOOGLE_MAPS_API_KEY (requerido) - Tu clave API de Google Maps Platform

Configuración de limitación de velocidad

GOOGLE_MAPS_RATE_LIMIT_ENABLED (opcional, predeterminado: true) - Habilita/deshabilita la limitación de velocidad
- Establécelo en false para deshabilitar la limitación de velocidad por completo
GOOGLE_MAPS_RATE_LIMIT_WINDOW_MS (opcional, predeterminado: 60000) - Ventana de limitación de velocidad en milisegundos
- Controla la ventana de tiempo para la limitación de velocidad (p. ej., 60000 = 1 minuto)
GOOGLE_MAPS_RATE_LIMIT_MAX_REQUESTS (opcional, predeterminado: 100) - Máximo de solicitudes por ventana
- Número máximo de solicitudes permitidas por endpoint dentro de la ventana de tiempo

Ejemplos de configuraciones de limitación de velocidad

# Default rate limiting (100 requests per minute per endpoint)
GOOGLE_MAPS_API_KEY="your-api-key-here"

# Disable rate limiting entirely
GOOGLE_MAPS_API_KEY="your-api-key-here"
GOOGLE_MAPS_RATE_LIMIT_ENABLED=false

# Custom rate limiting (200 requests per 2 minutes per endpoint)
GOOGLE_MAPS_API_KEY="your-api-key-here"
GOOGLE_MAPS_RATE_LIMIT_WINDOW_MS=120000
GOOGLE_MAPS_RATE_LIMIT_MAX_REQUESTS=200

# Stricter rate limiting (50 requests per 30 seconds per endpoint)
GOOGLE_MAPS_API_KEY="your-api-key-here"
GOOGLE_MAPS_RATE_LIMIT_WINDOW_MS=30000
GOOGLE_MAPS_RATE_LIMIT_MAX_REQUESTS=50

Cuotas de API y facturación

Este servidor utiliza las APIs de Google Maps Platform que requieren que la facturación esté habilitada. Supervisa tu uso en la Google Cloud Console para evitar cargos inesperados. Considera implementar límites de uso en tu aplicación.

Recursos

El servidor proporciona recursos MCP integrados con documentación y ejemplos:

google-maps://docs/api-overview - Descripción general y capacidades de la API
google-maps://docs/place-types - Referencia completa de tipos de lugares
google-maps://docs/travel-modes - Modos de viaje disponibles
google-maps://docs/field-masks - Optimización de campos de Places API
google-maps://examples/common-queries - Consultas y patrones de ejemplo

Accede a estos a través de la interfaz de recursos de tu cliente MCP.

Desarrollo

Compilación desde el código fuente

git clone <repository-url>
cd google-maps-mcp-server
npm install
npm run build

Pruebas

npm test

Uso de MCP Inspector

npm run build

GOOGLE_MAPS_API_KEY="your-api-key-here" npx @modelcontextprotocol/inspector ./dist/index.js

Manejo de errores

El servidor devuelve errores estructurados con contexto útil:

{
  "error": {
    "code": "QUOTA_EXCEEDED",
    "message": "API quota exceeded",
    "context": {
      "endpoint": "/places/textsearch",
      "status": 429
    }
  }
}

Códigos de error comunes:

INVALID_REQUEST - Parámetros de entrada no válidos
API_KEY_INVALID - Clave API no válida o faltante
QUOTA_EXCEEDED - Cuota de API excedida
REQUEST_FAILED - Solicitud de red o API fallida

Seguridad

Las claves API nunca se registran ni se exponen
La validación de entrada previene ataques de inyección
La limitación de velocidad protege contra el abuso
Las direcciones IP se cifran (hash) en los registros por privacidad

Contribuciones

¡Las contribuciones son bienvenidas! Envía pull requests a nuestro repositorio de GitHub.

Licencia

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