Google Maps

Give your AI agent the ability to understand the physical world —

- 18 tools— 14 atomic + 4 composite (explore-area, plan-route, compare-places, local-rank-tracker)
- 3 modes— stdio, StreamableHTTP, standalone exec CLI
- Agent Skill— built-in skill definition teaches AI how to chain geo tools (skills/google-maps/)

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

Special thanks to@junyinnnnfor helping add support forstreamablehttp.

Prerequisite: EnablePlaces API (New)andRoutes APIinGoogle Cloud Consolebefore using place-related and routing tools.

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

Reduce context usage— If you only need a subset of tools, setGOOGLE_MAPS_ENABLED_TOOLSto limit which tools are registered:

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

Omit or set to*for all 18 tools (default).

For multi-session deployments, per-request API key isolation, or remote access:

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"

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

- Transport: stdio (--stdio) or Streamable HTTP (default)
- Tools: 18 Google Maps tools (14 atomic + 4 composite) — filterable viaGOOGLE_MAPS_ENABLED_TOOLS

Use tools directly without running the MCP server:

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

All 18 tools available: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. Seeskills/google-maps/for the agent skill definition and full parameter docs.

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

Input: one address per line. Output: JSON with{ total, succeeded, failed, results[] }. Default concurrency: 20 parallel requests.

API keys can be provided in three ways (priority order):

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

Environment Variable(.env file or command line)

GOOGLE_MAPS_API_KEY=your_api_key_here MCP_SERVER_PORT=3000 MCP_SERVER_HOST=0.0.0.0

# 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

# 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

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)

- TypeScript- Type-safe development
- Node.js- Runtime environment
- @googlemaps/places- Google Places API (New) for place search and details
- Google Routes API- Directions, distance matrix, and waypoint optimization via REST
- @googlemaps/google-maps-services-js- Geocoding, timezone, elevation
- @modelcontextprotocol/sdk- MCP protocol implementation (v1.27+)
- Express.js- HTTP server framework
- Zod- Schema validation

- API keys are handled server-side
- Per-session API key isolation for multi-tenant deployments
- DNS rebinding protection available for production
- Input validation using Zod schemas

For enterprise security reviews, seeSecurity Assessment Clarifications— a 23-item checklist covering licensing, data protection, credential management, tool contamination, and AI agent execution environment verification.

To report a vulnerability, seeSECURITY.md.

Community participation and contributions are welcome! Please readCONTRIBUTING.mdfor development setup, coding guidelines, and the pull request process.

- Email:reahtuoo310109@gmail.com
- GitHub:CabLate

Official LatLng MCP endpoint for geocoding, reverse geocoding, and places search.