{"id":28767971,"url":"https://github.com/cablate/mcp-google-map","last_synced_at":"2026-04-01T20:53:31.496Z","repository":{"id":278889563,"uuid":"937106681","full_name":"cablate/mcp-google-map","owner":"cablate","description":"A powerful Model Context Protocol (MCP) server providing comprehensive Google Maps API integration with LLM processing capabilities.","archived":false,"fork":false,"pushed_at":"2026-03-21T05:40:22.000Z","size":26671,"stargazers_count":228,"open_issues_count":1,"forks_count":63,"subscribers_count":4,"default_branch":"main","last_synced_at":"2026-03-21T19:15:42.807Z","etag":null,"topics":["agent-skill","ai","ai-agent","dive","geocoding","geospatial","google-map","google-maps","mcp","mcp-server","model-context-protocol","places-api","streamable-http","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cablate.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY_ASSESSMENT.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-02-22T10:57:31.000Z","updated_at":"2026-03-21T13:03:46.000Z","dependencies_parsed_at":null,"dependency_job_id":"3f6ee387-ff0d-4843-80d5-b0cebd1af089","html_url":"https://github.com/cablate/mcp-google-map","commit_stats":null,"previous_names":["cablate/mcp-google-map"],"tags_count":25,"template":false,"template_full_name":null,"purl":"pkg:github/cablate/mcp-google-map","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cablate%2Fmcp-google-map","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cablate%2Fmcp-google-map/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cablate%2Fmcp-google-map/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cablate%2Fmcp-google-map/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cablate","download_url":"https://codeload.github.com/cablate/mcp-google-map/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cablate%2Fmcp-google-map/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31291868,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-01T13:12:26.723Z","status":"ssl_error","status_checked_at":"2026-04-01T13:12:25.102Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-skill","ai","ai-agent","dive","geocoding","geospatial","google-map","google-maps","mcp","mcp-server","model-context-protocol","places-api","streamable-http","typescript"],"created_at":"2025-06-17T13:02:46.077Z","updated_at":"2026-04-01T20:53:31.484Z","avatar_url":"https://github.com/cablate.png","language":"TypeScript","readme":"\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://www.npmjs.com/package/@cablate/mcp-google-map\"\u003e\u003cimg src=\"https://img.shields.io/npm/v/@cablate/mcp-google-map\" alt=\"npm version\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.npmjs.com/package/@cablate/mcp-google-map\"\u003e\u003cimg src=\"https://img.shields.io/npm/dm/@cablate/mcp-google-map\" alt=\"npm downloads\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/cablate/mcp-google-map/stargazers\"\u003e\u003cimg src=\"https://img.shields.io/github/stars/cablate/mcp-google-map?style=social\" alt=\"GitHub stars\"\u003e\u003c/a\u003e\n  \u003ca href=\"./LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/github/license/cablate/mcp-google-map\" alt=\"license\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"./assets/banner.webp\" alt=\"MCP Google Maps — AI-Powered Geospatial Tools\" width=\"800\"\u003e\n\u003c/p\u003e\n\n\u003ch3 align=\"center\"\u003e\u003cb\u003eGive your AI agent the ability to understand the physical world —\u003cbr\u003egeocode, route, search, and reason about locations.\u003c/b\u003e\u003c/h3\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cb\u003eEnglish\u003c/b\u003e | \u003ca href=\"./README.zh-TW.md\"\u003e繁體中文\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"./assets/demo-grid-en.png\" alt=\"Travel planning demo — Kyoto 2-day, Tokyo outdoor, Japan 5-day, Bangkok budget\" width=\"800\"\u003e\n\u003c/p\u003e\n\n- **18 tools** — 14 atomic + 4 composite (explore-area, plan-route, compare-places, local-rank-tracker)\n- **3 modes** — stdio, StreamableHTTP, standalone exec CLI\n- **Agent Skill** — built-in skill definition teaches AI how to chain geo tools ([`skills/google-maps/`](./skills/google-maps/))\n\n### vs Google Grounding Lite\n\n| | This project | [Grounding Lite](https://cloud.google.com/blog/products/ai-machine-learning/announcing-official-mcp-support-for-google-services) |\n|---|---|---|\n| Tools | **18** | 3 |\n| Geocoding | Yes | No |\n| Step-by-step directions | Yes | No |\n| Elevation | Yes | No |\n| Distance matrix | Yes | No |\n| Place details | Yes | No |\n| Timezone | Yes | No |\n| Weather | Yes | Yes |\n| Air quality | Yes | No |\n| Map images | Yes | No |\n| Composite tools (explore, plan, compare) | Yes | No |\n| Open source | MIT | No |\n| Self-hosted | Yes | Google-managed only |\n| Agent Skill | Yes | No |\n\n### Quick Start\n\n```bash\n# stdio (Claude Desktop, Cursor, etc.)\nnpx @cablate/mcp-google-map --stdio\n\n# exec CLI — no server needed\nnpx @cablate/mcp-google-map exec geocode '{\"address\":\"Tokyo Tower\"}'\n\n# HTTP server\nnpx @cablate/mcp-google-map --port 3000 --apikey \"YOUR_API_KEY\"\n```\n\n## Special Thanks\n\nSpecial thanks to [@junyinnnn](https://github.com/junyinnnn) for helping add support for `streamablehttp`.\n\n## Available Tools\n\n| Tool | Description |\n|------|-------------|\n| `maps_search_nearby` | Find places near a location by type (restaurant, cafe, hotel, etc.). Supports filtering by radius, rating, and open status. |\n| `maps_search_places` | Free-text place search (e.g., \"sushi restaurants in Tokyo\"). Supports location bias, rating, open-now filters. |\n| `maps_place_details` | Get full details for a place by its place_id — reviews, phone, website, hours. Optional `maxPhotos` param returns photo URLs. |\n| `maps_geocode` | Convert an address or landmark name into GPS coordinates. |\n| `maps_reverse_geocode` | Convert GPS coordinates into a street address. |\n| `maps_distance_matrix` | Calculate travel distances and times between multiple origins and destinations. |\n| `maps_directions` | Get step-by-step navigation between two points with route details. |\n| `maps_elevation` | Get elevation (meters above sea level) for geographic coordinates. |\n| `maps_timezone` | Get timezone ID, name, UTC/DST offsets, and local time for coordinates. |\n| `maps_weather` | Get current weather conditions or forecast — temperature, humidity, wind, UV, precipitation. |\n| `maps_air_quality` | Get air quality index, pollutant concentrations, and health recommendations by demographic group. |\n| `maps_static_map` | Generate a map image with markers, paths, or routes — returned inline for the user to see directly. |\n| `maps_batch_geocode` | Geocode up to 50 addresses in one call — returns coordinates for each. |\n| `maps_search_along_route` | Search for places along a route between two points — ranked by minimal detour time. |\n| **Composite Tools** | |\n| `maps_explore_area` | Explore what's around a location — searches multiple place types and gets details in one call. |\n| `maps_plan_route` | Plan an optimized multi-stop route — uses Routes API waypoint optimization (up to 25 stops) for efficient ordering. |\n| `maps_compare_places` | Compare places side-by-side — searches, gets details, and optionally calculates distances. |\n| `maps_local_rank_tracker` | 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). |\n\nAll tools are annotated with `readOnlyHint: true` and `destructiveHint: false` — MCP clients can auto-approve these without user confirmation.\n\n\u003e **Prerequisite**: Enable **Places API (New)** and **Routes API** in [Google Cloud Console](https://console.cloud.google.com) before using place-related and routing tools.\n\n## Installation\n\n### Method 1: stdio (Recommended for most clients)\n\nWorks with Claude Desktop, Cursor, VS Code, and any MCP client that supports stdio:\n\n```json\n{\n  \"mcpServers\": {\n    \"google-maps\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@cablate/mcp-google-map\", \"--stdio\"],\n      \"env\": {\n        \"GOOGLE_MAPS_API_KEY\": \"YOUR_API_KEY\"\n      }\n    }\n  }\n}\n```\n\n**Reduce context usage** — If you only need a subset of tools, set `GOOGLE_MAPS_ENABLED_TOOLS` to limit which tools are registered:\n\n```json\n{\n  \"env\": {\n    \"GOOGLE_MAPS_API_KEY\": \"YOUR_API_KEY\",\n    \"GOOGLE_MAPS_ENABLED_TOOLS\": \"maps_geocode,maps_directions,maps_search_places\"\n  }\n}\n```\n\nOmit or set to `*` for all 18 tools (default).\n\n### Method 2: HTTP Server\n\nFor multi-session deployments, per-request API key isolation, or remote access:\n\n```bash\nnpx @cablate/mcp-google-map --port 3000 --apikey \"YOUR_API_KEY\"\n```\n\nThen configure your MCP client:\n\n```json\n{\n  \"mcpServers\": {\n    \"google-maps\": {\n      \"type\": \"http\",\n      \"url\": \"http://localhost:3000/mcp\"\n    }\n  }\n}\n```\n\n### Server Information\n\n- **Transport**: stdio (`--stdio`) or Streamable HTTP (default)\n- **Tools**: 18 Google Maps tools (14 atomic + 4 composite) — filterable via `GOOGLE_MAPS_ENABLED_TOOLS`\n\n### CLI Exec Mode (Agent Skill)\n\nUse tools directly without running the MCP server:\n\n```bash\nnpx @cablate/mcp-google-map exec geocode '{\"address\":\"Tokyo Tower\"}'\nnpx @cablate/mcp-google-map exec search-places '{\"query\":\"ramen in Tokyo\"}'\n```\n\nAll 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/`](./skills/google-maps/) for the agent skill definition and full parameter docs.\n\n### Batch Geocode\n\nGeocode hundreds of addresses from a file:\n\n```bash\nnpx @cablate/mcp-google-map batch-geocode -i addresses.txt -o results.json\ncat addresses.txt | npx @cablate/mcp-google-map batch-geocode -i -\n```\n\nInput: one address per line. Output: JSON with `{ total, succeeded, failed, results[] }`. Default concurrency: 20 parallel requests.\n\n\n\n### API Key Configuration\n\nAPI keys can be provided in three ways (priority order):\n\n1. **HTTP Headers** (Highest priority)\n\n   ```json\n   {\n     \"mcp-google-map\": {\n       \"transport\": \"streamableHttp\",\n       \"url\": \"http://localhost:3000/mcp\",\n       \"headers\": {\n         \"X-Google-Maps-API-Key\": \"YOUR_API_KEY\"\n       }\n     }\n   }\n   ```\n\n2. **Command Line**\n\n   ```bash\n   mcp-google-map --apikey YOUR_API_KEY\n   ```\n\n3. **Environment Variable** (.env file or command line)\n   ```env\n   GOOGLE_MAPS_API_KEY=your_api_key_here\n   MCP_SERVER_PORT=3000\n   ```\n\n## Development\n\n### Local Development\n\n```bash\n# Clone the repository\ngit clone https://github.com/cablate/mcp-google-map.git\ncd mcp-google-map\n\n# Install dependencies\nnpm install\n\n# Set up environment variables\ncp .env.example .env\n# Edit .env with your API key\n\n# Build the project\nnpm run build\n\n# Start the server\nnpm start\n\n# Or run in development mode\nnpm run dev\n```\n\n### Testing\n\n```bash\n# Run smoke tests (no API key required for basic tests)\nnpm test\n\n# Run full E2E tests (requires GOOGLE_MAPS_API_KEY)\nnpm run test:e2e\n```\n\n### Project Structure\n\n```\nsrc/\n├── cli.ts                        # CLI entry point\n├── config.ts                     # Tool registration and server config\n├── index.ts                      # Package exports\n├── core/\n│   └── BaseMcpServer.ts          # MCP server with streamable HTTP transport\n├── services/\n│   ├── NewPlacesService.ts       # Google Places API (New) client\n│   ├── PlacesSearcher.ts         # Service facade layer\n│   ├── RoutesService.ts          # Google Routes API client (directions, distance matrix, waypoint optimization)\n│   └── toolclass.ts              # Google Maps API client (geocoding, timezone, elevation, static map)\n├── tools/\n│   └── maps/\n│       ├── searchNearby.ts       # maps_search_nearby tool\n│       ├── searchPlaces.ts       # maps_search_places tool\n│       ├── placeDetails.ts       # maps_place_details tool\n│       ├── geocode.ts            # maps_geocode tool\n│       ├── reverseGeocode.ts     # maps_reverse_geocode tool\n│       ├── distanceMatrix.ts     # maps_distance_matrix tool\n│       ├── directions.ts         # maps_directions tool\n│       ├── elevation.ts          # maps_elevation tool\n│       ├── timezone.ts           # maps_timezone tool\n│       ├── weather.ts            # maps_weather tool\n│       ├── airQuality.ts         # maps_air_quality tool\n│       ├── staticMap.ts          # maps_static_map tool\n│       ├── batchGeocode.ts       # maps_batch_geocode tool\n│       ├── searchAlongRoute.ts   # maps_search_along_route tool\n│       ├── exploreArea.ts        # maps_explore_area (composite)\n│       ├── planRoute.ts          # maps_plan_route (composite)\n│       ├── comparePlaces.ts      # maps_compare_places (composite)\n│       └── localRankTracker.ts   # maps_local_rank_tracker (composite)\n└── utils/\n    ├── apiKeyManager.ts          # API key management\n    └── requestContext.ts         # Per-request context (API key isolation)\ntests/\n└── smoke.test.ts                 # Smoke + E2E test suite\nskills/\n├── google-maps/                  # Agent Skill — how to USE the tools\n│   ├── SKILL.md                  # Tool map, recipes, invocation\n│   └── references/\n│       ├── tools-api.md          # Tool parameters + scenario recipes\n│       ├── travel-planning.md    # Travel planning methodology\n│       └── local-seo.md          # Local SEO / Google Business Profile ranking analysis\n└── project-docs/                 # Project Skill — how to DEVELOP/MAINTAIN\n    ├── SKILL.md                  # Architecture overview + onboarding\n    └── references/\n        ├── architecture.md       # System design, code map, 9-file checklist\n        ├── google-maps-api-guide.md  # API endpoints, pricing, gotchas\n        ├── geo-domain-knowledge.md   # GIS fundamentals, Japan context\n        └── decisions.md          # 10 ADRs (design decisions + rationale)\n```\n\n## Tech Stack\n\n- **TypeScript** - Type-safe development\n- **Node.js** - Runtime environment\n- **@googlemaps/places** - Google Places API (New) for place search and details\n- **Google Routes API** - Directions, distance matrix, and waypoint optimization via REST\n- **@googlemaps/google-maps-services-js** - Geocoding, timezone, elevation\n- **@modelcontextprotocol/sdk** - MCP protocol implementation (v1.27+)\n- **Express.js** - HTTP server framework\n- **Zod** - Schema validation\n\n## Security\n\n- API keys are handled server-side\n- Per-session API key isolation for multi-tenant deployments\n- DNS rebinding protection available for production\n- Input validation using Zod schemas\n\nFor enterprise security reviews, see [Security Assessment Clarifications](./SECURITY_ASSESSMENT.md) — a 23-item checklist covering licensing, data protection, credential management, tool contamination, and AI agent execution environment verification.\n\nTo report a vulnerability, see [SECURITY.md](SECURITY.md).\n\n## Roadmap\n\n### Recent Additions\n\n| Tool / Feature | What it unlocks | Status |\n|------|----------------|--------|\n| `maps_static_map` | Map images with pins/routes — multimodal AI can \"see\" the map | **Done** |\n| `maps_air_quality` | AQI, pollutants — health-aware travel, outdoor planning | **Done** |\n| `maps_batch_geocode` | Geocode up to 50 addresses in one call — data enrichment | **Done** |\n| `maps_search_along_route` | Find places along a route ranked by detour time — trip planning | **Done** |\n| `maps_explore_area` | One-call neighborhood overview (composite) | **Done** |\n| `maps_plan_route` | Optimized multi-stop itinerary (composite) | **Done** |\n| `maps_compare_places` | Side-by-side place comparison (composite) | **Done** |\n| `maps_local_rank_tracker` | Geographic grid rank tracking — local SEO analysis (composite) | **Done** |\n| `GOOGLE_MAPS_ENABLED_TOOLS` | Filter tools to reduce context usage | **Done** |\n\n### Planned\n\n| Feature | What it unlocks | Status |\n|---------|----------------|--------|\n| `maps_place_photo` | Place photos for multimodal AI — \"see\" the restaurant ambiance | Planned |\n| Language parameter | Multi-language responses (ISO 639-1) across all tools | Planned |\n| MCP Prompt Templates | `/travel-planner`, `/neighborhood-scout` slash commands in Claude Desktop | Planned |\n| Geo-Reasoning Benchmark | 10-scenario test suite measuring LLM geospatial reasoning accuracy | Research |\n\n### Use Cases We're Building Toward\n\nThese are the real-world scenarios driving our tool decisions:\n\n- **Travel planning** — \"Plan a day trip in Tokyo\" (geocode → search → directions → weather)\n- **Real estate analysis** — \"Analyze this neighborhood: schools, commute, flood risk\" (search-nearby × N + elevation + distance-matrix)\n- **Logistics optimization** — \"Route these 12 deliveries efficiently from the warehouse\" (plan-route)\n- **Field sales** — \"Visit 6 clients in Chicago, minimize drive time, find lunch spots\" (plan-route + search-nearby)\n- **Disaster response** — \"Nearest open hospitals? Am I in a flood zone?\" (search-nearby + elevation)\n- **Content creation** — \"Top 5 neighborhoods in Austin with restaurant density and airport distance\" (explore-area + distance-matrix)\n- **Accessibility** — \"Wheelchair-accessible restaurants, avoid steep routes\" (search-nearby + place-details + elevation)\n- **Local SEO** — \"Audit my restaurant's ranking vs competitors within 1km\" (search-places + compare-places + explore-area)\n\n## Changelog\n\nSee [CHANGELOG.md](./CHANGELOG.md) for version history.\n\n## License\n\nMIT\n\n## Contributing\n\nCommunity participation and contributions are welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, coding guidelines, and the pull request process.\n\n- Submit Issues: Report bugs or provide suggestions\n- Create Pull Requests: Submit code improvements\n- Documentation: Help improve documentation\n\n## Contact\n\n- Email: [reahtuoo310109@gmail.com](mailto:reahtuoo310109@gmail.com)\n- GitHub: [CabLate](https://github.com/cablate/)\n\n## Star History\n\n\u003ca href=\"https://glama.ai/mcp/servers/@cablate/mcp-google-map\"\u003e\n  \u003cimg width=\"380\" height=\"200\" src=\"https://glama.ai/mcp/servers/@cablate/mcp-google-map/badge\" alt=\"Google Map Server MCP server\" /\u003e\n\u003c/a\u003e\n\n[![Star History Chart](https://api.star-history.com/svg?repos=cablate/mcp-google-map\u0026type=Date)](https://www.star-history.com/#cablate/mcp-google-map\u0026Date)\n","funding_links":[],"categories":["📚 Projects (1974 total)","🤖 AI/ML","APIs and HTTP Requests","Location Services"],"sub_categories":["MCP Servers","How to Submit"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcablate%2Fmcp-google-map","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcablate%2Fmcp-google-map","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcablate%2Fmcp-google-map/lists"}