MCP Google Map Server

Integra la API de Google Maps para consultas basadas en ubicación y procesamiento de datos.

GitHub

447

Prueba este MCPPatrocinado

Documentación

Dale a tu agente de IA la capacidad de entender el mundo físico —
geocodifica, traza rutas, busca y razona sobre ubicaciones.

English | 繁體中文

Travel planning demo — Kyoto 2-day, Tokyo outdoor, Japan 5-day, Bangkok budget

18 herramientas — 14 atómicas + 4 compuestas (explore-area, plan-route, compare-places, local-rank-tracker)
3 modos — stdio, StreamableHTTP, CLI ejecutable independiente
Agent Skill — definición de habilidad integrada que enseña a la IA cómo encadenar herramientas geo (skills/google-maps/)

vs Google Grounding Lite

	Este proyecto	Grounding Lite
Herramientas	18	3
Geocodificación	Sí	No
Indicaciones paso a paso	Sí	No
Elevación	Sí	No
Matriz de distancias	Sí	No
Detalles de lugares	Sí	No
Zona horaria	Sí	No
Clima	Sí	Sí
Calidad del aire	Sí	No
Imágenes de mapas	Sí	No
Herramientas compuestas (explore, plan, compare)	Sí	No
Código abierto	MIT	No
Autohospedado	Sí	Solo gestionado por Google
Agent Skill	Sí	No

Inicio rápido

# stdio (Claude Desktop, Cursor, etc.)
npx @cablate/mcp-google-map --stdio

# exec CLI — no server needed
npx @cablate/mcp-google-map exec geocode '{"address":"Tokyo Tower"}'

# HTTP server
npx @cablate/mcp-google-map --port 3000 --apikey "YOUR_API_KEY"

Agradecimientos especiales

Agradecimientos especiales a @junyinnnn por ayudar a añadir soporte para streamablehttp.

Herramientas disponibles

Herramienta	Descripción
`maps_search_nearby`	Encuentra lugares cerca de una ubicación por tipo (restaurante, cafetería, hotel, etc.). Admite filtrado por radio, calificación y estado de apertura.
`maps_search_places`	Búsqueda de lugares por texto libre (p. ej., «restaurantes de sushi en Tokio»). Admite sesgo de ubicación, calificación y filtros de abierto ahora.
`maps_place_details`	Obtén detalles completos de un lugar por su place_id — reseñas, teléfono, sitio web, horarios. El parámetro opcional `maxPhotos` devuelve URLs de fotos.
`maps_geocode`	Convierte una dirección o nombre de punto de referencia en coordenadas GPS.
`maps_reverse_geocode`	Convierte coordenadas GPS en una dirección postal.
`maps_distance_matrix`	Calcula distancias y tiempos de viaje entre múltiples orígenes y destinos. El modo de conducción admite `avoid_tolls` y `avoid_highways`.
`maps_directions`	Obtén navegación paso a paso entre dos puntos con detalles de la ruta. El modo de conducción admite `avoid_tolls` y `avoid_highways`.
`maps_elevation`	Obtén la elevación (metros sobre el nivel del mar) para coordenadas geográficas.
`maps_timezone`	Obtén ID de zona horaria, nombre, desfases UTC/DST y hora local para coordenadas.
`maps_weather`	Obtén condiciones climáticas actuales o pronóstico — temperatura, humedad, viento, UV, precipitación.
`maps_air_quality`	Obtén índice de calidad del aire, concentraciones de contaminantes y recomendaciones de salud por grupo demográfico.
`maps_static_map`	Genera una imagen de mapa con marcadores, rutas o trayectos — devuelta en línea para que el usuario la vea directamente.
`maps_batch_geocode`	Geocodifica hasta 50 direcciones en una sola llamada — devuelve coordenadas para cada una.
`maps_search_along_route`	Busca lugares a lo largo de una ruta entre dos puntos — clasificados por tiempo mínimo de desvío.
Herramientas compuestas
`maps_explore_area`	Explora lo que hay alrededor de una ubicación — busca múltiples tipos de lugares y obtiene detalles en una sola llamada.
`maps_plan_route`	Planifica una ruta optimizada de múltiples paradas — utiliza la optimización de waypoints de Routes API (hasta 25 paradas) para un orden eficiente. El modo de conducción admite `avoid_tolls` y `avoid_highways`.
`maps_compare_places`	Compara lugares lado a lado — busca, obtiene detalles y opcionalmente calcula distancias.
`maps_local_rank_tracker`	Realiza seguimiento del ranking de búsqueda local de un negocio en una cuadrícula geográfica — como LocalFalcon. Admite hasta 3 palabras clave para escaneo por lotes. Devuelve el ranking en cada punto, los 3 principales competidores y métricas (ARP, ATRP, SoLV).

Todas las herramientas están anotadas con readOnlyHint: true y destructiveHint: false — los clientes MCP pueden aprobarlas automáticamente sin confirmación del usuario.

Requisito previo: Habilita Places API (New) y Routes API en Google Cloud Console antes de usar herramientas relacionadas con lugares y enrutamiento.

Instalación

Método 1: stdio (Recomendado para la mayoría de los clientes)

Funciona con Claude Desktop, Cursor, VS Code y cualquier cliente MCP que admita stdio:

{
  "mcpServers": {
    "google-maps": {
      "command": "npx",
      "args": ["-y", "@cablate/mcp-google-map", "--stdio"],
      "env": {
        "GOOGLE_MAPS_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

Reduce el uso de contexto — Si solo necesitas un subconjunto de herramientas, establece GOOGLE_MAPS_ENABLED_TOOLS para limitar qué herramientas se registran:

{
  "env": {
    "GOOGLE_MAPS_API_KEY": "YOUR_API_KEY",
    "GOOGLE_MAPS_ENABLED_TOOLS": "maps_geocode,maps_directions,maps_search_places"
  }
}

Omite o establece * para las 18 herramientas (predeterminado).

Método 2: Servidor HTTP

Para implementaciones de múltiples sesiones, aislamiento de clave API por solicitud o acceso remoto:

npx @cablate/mcp-google-map --port 3000 --apikey "YOUR_API_KEY"

# Bind to all interfaces for remote access (e.g. Docker, LAN)
npx @cablate/mcp-google-map --host 0.0.0.0 --port 3000 --apikey "YOUR_API_KEY"

Luego configura tu cliente MCP:

{
  "mcpServers": {
    "google-maps": {
      "type": "http",
      "url": "http://localhost:3000/mcp"
    }
  }
}

Información del servidor

Transporte: stdio (--stdio) o Streamable HTTP (predeterminado)
Herramientas: 18 herramientas de Google Maps (14 atómicas + 4 compuestas) — filtrables mediante GOOGLE_MAPS_ENABLED_TOOLS

Modo CLI Exec (Agent Skill)

Usa las herramientas directamente sin ejecutar el servidor MCP:

npx @cablate/mcp-google-map exec geocode '{"address":"Tokyo Tower"}'
npx @cablate/mcp-google-map exec search-places '{"query":"ramen in Tokyo"}'

Las 18 herramientas disponibles: geocode, reverse-geocode, search-nearby, search-places, place-details, directions, distance-matrix, elevation, timezone, weather, air-quality, static-map, batch-geocode-tool, search-along-route, explore-area, plan-route, compare-places, local-rank-tracker. Consulta skills/google-maps/ para la definición de la habilidad del agente y la documentación completa de parámetros.

Geocodificación por lotes

Geocodifica cientos de direcciones desde un archivo:

npx @cablate/mcp-google-map batch-geocode -i addresses.txt -o results.json
cat addresses.txt | npx @cablate/mcp-google-map batch-geocode -i -

Entrada: una dirección por línea. Salida: JSON con { total, succeeded, failed, results[] }. Concurrencia predeterminada: 20 solicitudes paralelas.

Configuración de la clave API

Las claves API se pueden proporcionar de tres maneras (en orden de prioridad):

Encabezados HTTP (Prioridad más alta)

{
  "mcp-google-map": {
    "transport": "streamableHttp",
    "url": "http://localhost:3000/mcp",
    "headers": {
      "X-Google-Maps-API-Key": "YOUR_API_KEY"
    }
  }
}

Línea de comandos
```
mcp-google-map --apikey YOUR_API_KEY
```

Variable de entorno (archivo .env o línea de comandos)

GOOGLE_MAPS_API_KEY=your_api_key_here
MCP_SERVER_PORT=3000
MCP_SERVER_HOST=0.0.0.0

Desarrollo

Desarrollo local

# Clone the repository
git clone https://github.com/cablate/mcp-google-map.git
cd mcp-google-map

# Install dependencies
npm install

# Set up environment variables
cp .env.example .env
# Edit .env with your API key

# Build the project
npm run build

# Start the server
npm start

# Or run in development mode
npm run dev

Pruebas

# Run smoke tests (no API key required for basic tests)
npm test

# Run full E2E tests (requires GOOGLE_MAPS_API_KEY)
npm run test:e2e

Estructura del proyecto

src/
├── cli.ts                        # CLI entry point
├── config.ts                     # Tool registration and server config
├── index.ts                      # Package exports
├── core/
│   └── BaseMcpServer.ts          # MCP server with streamable HTTP transport
├── services/
│   ├── NewPlacesService.ts       # Google Places API (New) client
│   ├── PlacesSearcher.ts         # Service facade layer
│   ├── RoutesService.ts          # Google Routes API client (directions, distance matrix, waypoint optimization)
│   └── toolclass.ts              # Google Maps API client (geocoding, timezone, elevation, static map)
├── tools/
│   └── maps/
│       ├── searchNearby.ts       # maps_search_nearby tool
│       ├── searchPlaces.ts       # maps_search_places tool
│       ├── placeDetails.ts       # maps_place_details tool
│       ├── geocode.ts            # maps_geocode tool
│       ├── reverseGeocode.ts     # maps_reverse_geocode tool
│       ├── distanceMatrix.ts     # maps_distance_matrix tool
│       ├── directions.ts         # maps_directions tool
│       ├── elevation.ts          # maps_elevation tool
│       ├── timezone.ts           # maps_timezone tool
│       ├── weather.ts            # maps_weather tool
│       ├── airQuality.ts         # maps_air_quality tool
│       ├── staticMap.ts          # maps_static_map tool
│       ├── batchGeocode.ts       # maps_batch_geocode tool
│       ├── searchAlongRoute.ts   # maps_search_along_route tool
│       ├── exploreArea.ts        # maps_explore_area (composite)
│       ├── planRoute.ts          # maps_plan_route (composite)
│       ├── comparePlaces.ts      # maps_compare_places (composite)
│       └── localRankTracker.ts   # maps_local_rank_tracker (composite)
└── utils/
    ├── apiKeyManager.ts          # API key management
    └── requestContext.ts         # Per-request context (API key isolation)
tests/
└── smoke.test.ts                 # Smoke + E2E test suite
skills/
├── google-maps/                  # Agent Skill — how to USE the tools
│   ├── SKILL.md                  # Tool map, recipes, invocation
│   └── references/
│       ├── tools-api.md          # Tool parameters + scenario recipes
│       ├── travel-planning.md    # Travel planning methodology
│       └── local-seo.md          # Local SEO / Google Business Profile ranking analysis
└── project-docs/                 # Project Skill — how to DEVELOP/MAINTAIN
    ├── SKILL.md                  # Architecture overview + onboarding
    └── references/
        ├── architecture.md       # System design, code map, 9-file checklist
        ├── google-maps-api-guide.md  # API endpoints, pricing, gotchas
        ├── geo-domain-knowledge.md   # GIS fundamentals, Japan context
        └── decisions.md          # 10 ADRs (design decisions + rationale)

Pila tecnológica

TypeScript - Desarrollo con seguridad de tipos
Node.js - Entorno de ejecución
@googlemaps/places - Google Places API (New) para búsqueda y detalles de lugares
Google Routes API - Indicaciones, matriz de distancias y optimización de waypoints vía REST
@googlemaps/google-maps-services-js - Geocodificación, zona horaria, elevación
@modelcontextprotocol/sdk - Implementación del protocolo MCP (v1.27+)
Express.js - Framework de servidor HTTP
Zod - Validación de esquemas

Seguridad

Las claves API se gestionan en el lado del servidor
Aislamiento de clave API por sesión para implementaciones multiinquilino
Protección contra DNS rebinding disponible para producción
Validación de entrada mediante esquemas Zod

Para revisiones de seguridad empresarial, consulta Security Assessment Clarifications — una lista de verificación de 23 elementos que cubre licencias, protección de datos, gestión de credenciales, contaminación de herramientas y verificación del entorno de ejecución del agente de IA.

Para informar una vulnerabilidad, consulta SECURITY.md.

Hoja de ruta

Adiciones recientes

Herramienta / Función	Qué desbloquea	Estado
`maps_static_map`	Imágenes de mapas con pines/rutas — la IA multimodal puede «ver» el mapa	Hecho
`maps_air_quality`	AQI, contaminantes — viajes conscientes de la salud, planificación al aire libre	Hecho
`maps_batch_geocode`	Geocodifica hasta 50 direcciones en una sola llamada — enriquecimiento de datos	Hecho
`maps_search_along_route`	Encuentra lugares a lo largo de una ruta clasificados por tiempo de desvío — planificación de viajes	Hecho
`maps_explore_area`	Resumen de vecindario en una sola llamada (compuesto)	Hecho
`maps_plan_route`	Itinerario optimizado de múltiples paradas (compuesto)	Hecho
`maps_compare_places`	Comparación de lugares lado a lado (compuesto)	Hecho
`maps_local_rank_tracker`	Seguimiento de ranking en cuadrícula geográfica — análisis SEO local (compuesto)	Hecho
`GOOGLE_MAPS_ENABLED_TOOLS`	Filtra herramientas para reducir el uso de contexto	Hecho

Planificado

Función	Qué desbloquea	Estado
`maps_place_photo`	Fotos de lugares para IA multimodal — «ver» el ambiente del restaurante	Planificado
Parámetro de idioma	Respuestas multilingües (ISO 639-1) en todas las herramientas	Planificado
Plantillas de prompt MCP	Comandos de barra `/travel-planner`, `/neighborhood-scout` en Claude Desktop	Planificado
Benchmark de razonamiento geo	Suite de pruebas de 10 escenarios que mide la precisión del razonamiento geoespacial de LLM	Investigación

Casos de uso que estamos desarrollando

Estos son los escenarios del mundo real que impulsan nuestras decisiones de herramientas:

Planificación de viajes — «Planifica una excursión de un día en Tokio» (geocode → search → directions → weather)
Análisis inmobiliario — «Analiza este vecindario: escuelas, desplazamientos, riesgo de inundación» (search-nearby × N + elevation + distance-matrix)
Optimización logística — «Enruta estas 12 entregas de manera eficiente desde el almacén» (plan-route)
Ventas de campo — «Visita 6 clientes en Chicago, minimiza el tiempo de conducción, encuentra lugares para almorzar» (plan-route + search-nearby)
Respuesta ante desastres — «¿Hospitales abiertos más cercanos? ¿Estoy en una zona de inundación?» (search-nearby + elevation)
Creación de contenido — «Los 5 mejores vecindarios en Austin con densidad de restaurantes y distancia al aeropuerto» (explore-area + distance-matrix)
Accesibilidad — «Restaurantes accesibles en silla de ruedas, evita rutas empinadas» (search-nearby + place-details + elevation)
SEO local — «Audita el ranking de mi restaurante frente a competidores en un radio de 1 km» (search-places + compare-places + explore-area)

Registro de cambios

Consulta CHANGELOG.md para el historial de versiones.

Licencia

MIT

Contribuciones

¡La participación y las contribuciones de la comunidad son bienvenidas! Lee CONTRIBUTING.md para la configuración de desarrollo, las pautas de codificación y el proceso de pull requests.

Envía Issues: Reporta errores o proporciona sugerencias
Crea Pull Requests: Envía mejoras de código
Documentación: Ayuda a mejorar la documentación

Contacto

Correo electrónico: reahtuoo310109@gmail.com
GitHub: CabLate