by cablate
A powerful Model Context Protocol (MCP) server providing comprehensive Google Maps API integration with LLM processing capabilities.
# Add to your Claude Code skills
git clone https://github.com/cablate/mcp-google-mapskills/google-maps/)| | This project | Grounding Lite | |---|---|---| | Tools | 18 | 3 | | Geocoding | Yes | No | | Step-by-step directions | Yes | No | | Elevation | Yes | No | | Distance matrix | Yes | No | | Place details | Yes | No | | Timezone | Yes | No | | Weather | Yes | Yes | | Air quality | Yes | No | | Map images | Yes | No | | Composite tools (explore, plan, compare) | Yes | No | | Open source | MIT | No | | Self-hosted | Yes | Google-managed only | | Agent Skill | Yes | No |
# 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.
| Tool | Description |
|------|-------------|
| maps_search_nearby | Find places near a location by type (restaurant, cafe, hotel, etc.). Supports filtering by radius, rating, and open status. |
| maps_search_places | Free-text place search (e.g., "sushi restaurants in Tokyo"). Supports location bias, rating, open-now filters. |
| | Get full details for a place by its place_id — reviews, phone, website, hours. Optional param returns photo URLs. |
| | Convert an address or landmark name into GPS coordinates. |
| | Convert GPS coordinates into a street address. |
| | Calculate travel distances and times between multiple origins and destinations. |
| | Get step-by-step navigation between two points with route details. |
| | Get elevation (meters above sea level) for geographic coordinates. |
| | Get timezone ID, name, UTC/DST offsets, and local time for coordinates. |
| | Get current weather conditions or forecast — temperature, humidity, wind, UV, precipitation. |
| | Get air quality index, pollutant concentrations, and health recommendations by demographic group. |
| | Generate a map image with markers, paths, or routes — returned inline for the user to see directly. |
| | Geocode up to 50 addresses in one call — returns coordinates for each. |
| | Search for places along a route between two points — ranked by minimal detour time. |
| | |
| | Explore what's around a location — searches multiple place types and gets details in one call. |
| | Plan an optimized multi-stop route — uses Routes API waypoint optimization (up to 25 stops) for efficient ordering. |
| | Compare places side-by-side — searches, gets details, and optionally calculates distances. |
| | Track a business's local search ranking across a geographic grid — like LocalFalcon. Supports up to 3 keywords for batch scanning. Returns rank at each point, top-3 competitors, and metrics (ARP, ATRP, SoLV). |
No comments yet. Be the first to share your thoughts!
maps_place_detailsmaxPhotosmaps_geocodemaps_reverse_geocodemaps_distance_matrixmaps_directionsmaps_elevationmaps_timezonemaps_weathermaps_air_qualitymaps_static_mapmaps_batch_geocodemaps_search_along_routemaps_explore_areamaps_plan_routemaps_compare_placesmaps_local_rank_trackerAll tools are annotated with readOnlyHint: true and destructiveHint: false — MCP clients can auto-approve these without user confirmation.
Prerequisite: Enable Places API (New) and Routes API in Google Cloud Console before using place-related and routing 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 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"
Then configure your MCP client:
{
"mcpServers": {
"google-maps": {
"type": "http",
"url": "http://localhost:3000/mcp"
}
}
}
--stdio) or Streamable HTTP (default)GOOGLE_MAPS_ENABLED_TOOLSUse 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. 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):
HTTP Headers (Highest priority)
{
"mcp-google-map": {
"transport": "streamableHttp",
"url": "http://localhost:3000/mcp",
"headers": {
"X-Google-Maps-API-Key": "YOUR_API_KEY"
}
}
}
Command Line
mcp-google-map --apikey YOUR_API_KEY
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
│ ├── 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)
│ ├