English | 繁體中文

• 17 tools — 14 atomic + 3 composite (explore-area, plan-route, compare-places)
• 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 @junyinnnn for helping add support for streamablehttp.

All tools are annotated with readOnlyHint: true and destructiveHint: false — MCP clients can auto-approve these without user confirmation.

Prerequisite: Enable Places API (New) in Google Cloud Console before using place-related tools.

Works with Claude Desktop, Cursor, VS Code, and any MCP client that supports stdio:

{ "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, set GOOGLE_MAPS_ENABLED_TOOLS to 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 17 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"

Then configure your MCP client:

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

• Transport: stdio (--stdio) or Streamable HTTP (default)
• Tools: 17 Google Maps tools (14 atomic + 3 composite) — filterable via GOOGLE_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 17 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. See skills/google-maps/ for the agent skill definition and full parameter docs.

Geocode hundreds of addresses from a file:

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):

1. HTTP Headers (Highest priority)

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

2. Command Line

   mcp-google-map --apikey YOUR_API_KEY

3. Environment Variable (.env file or command line)

   GOOGLE_MAPS_API_KEY=your_api_key_here MCP_SERVER_PORT=3000

# 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 │ └── toolclass.ts # Legacy Google Maps API client ├── 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) └── 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
• @googlemaps/google-maps-services-js - Legacy API for geocoding, directions, distance matrix, 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, see Security Assessment Clarifications — a 23-item checklist covering licensing, data protection, credential management, tool contamination, and AI agent execution environment verification.

These are the real-world scenarios driving our tool decisions:

• Travel planning — "Plan a day trip in Tokyo" (geocode → search → directions → weather)
• Real estate analysis — "Analyze this neighborhood: schools, commute, flood risk" (search-nearby × N + elevation + distance-matrix)
• Logistics optimization — "Route these 12 deliveries efficiently from the warehouse" (plan-route)
• Field sales — "Visit 6 clients in Chicago, minimize drive time, find lunch spots" (plan-route + search-nearby)
• Disaster response — "Nearest open hospitals? Am I in a flood zone?" (search-nearby + elevation)
• Content creation — "Top 5 neighborhoods in Austin with restaurant density and airport distance" (explore-area + distance-matrix)
• Accessibility — "Wheelchair-accessible restaurants, avoid steep routes" (search-nearby + place-details + elevation)
• Local SEO — "Audit my restaurant's ranking vs competitors within 1km" (search-places + compare-places + explore-area)

See CHANGELOG.md for version history.

MIT

Community participation and contributions are welcome!

• Submit Issues: Report bugs or provide suggestions
• Create Pull Requests: Submit code improvements
• Documentation: Help improve documentation

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