Skip to content
Back to search

mcp-google-map

18 Google Maps tools and 3 Agent Skills for place search, routes, travel planning, and local SEO—via MCP or standalone CLI.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/cablate--mcp-google-map/badge.svg)](/listings/cablate--mcp-google-map)

HTML

<a href="/listings/cablate--mcp-google-map"><img src="/api/listings/cablate--mcp-google-map/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

claude plugin marketplace add cablate/mcp-google-map
claude plugin install mcp-google-map@cablate-maps

Start a new Claude Code session, set `GOOGLE_MAPS_API_KEY` in its environment, and run the same `doctor` check shown above. Claude exposes the installed Skills with the plugin namespace, for example `/mcp-google-map:google-maps-travel-planning`.

Each GitHub release also includes a versioned `mcp-google-map-claude-plugin-v*.zip` and SHA-256 checksum for direct distribution. The release workflow builds this archive from the same `skills/` source and validates it with Claude Code's official strict validator before publishing.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 20 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. {
  2. "name": "cablate-maps",
  3. "description": "Google Maps tools and workflows for AI agents",
  4. "owner": { "name": "CabLate", "url": "https://github.com/cablate" },
  5. "plugins": [
  6. {
  7. "name": "mcp-google-map",
  8. "displayName": "Google Maps CLI",
  9. "description": "Place research, travel planning, and local SEO without an MCP connection.",
  10. "source": {
  11. "source": "npm",
  12. "package": "@cablate/mcp-google-map",
  13. "version": "latest",
  14. "registry": "https://registry.npmjs.org"
  15. },
  16. "category": "Productivity",
  17. "tags": ["google-maps", "travel", "local-seo"]
  18. }
  19. ]
  20. }
README.md · README · 197 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # Google Maps for AI agents
  2. **Stop rebuilding place search, routing, and location workflows for every AI app.**
  3. `@cablate/mcp-google-map` turns Google Maps Platform into 18 read-only agent tools and three focused Skills. An agent can find real places, verify routes, compare options, build practical itineraries, or audit local search visibility—through MCP or a standalone CLI.
  4. You choose the integration model: Codex or Claude Code Plugin when you want Skills without MCP setup, stdio for desktop MCP clients, or Streamable HTTP for shared and remote deployments.
  5. <p align="center"><b>English</b> · <a href="./README.zh-TW.md">繁體中文</a></p>
  6. <p align="center"><img src="./assets/banner.webp" alt="Google Maps tools and workflows for AI agents" width="800"></p>
  7. <p align="center">
  8. <a href="https://www.npmjs.com/package/@cablate/mcp-google-map"><img src="https://img.shields.io/npm/v/@cablate/mcp-google-map" alt="npm version"></a>
  9. <a href="https://www.npmjs.com/package/@cablate/mcp-google-map"><img src="https://img.shields.io/npm/dm/@cablate/mcp-google-map" alt="npm downloads"></a>
  10. <a href="https://github.com/cablate/mcp-google-map/actions/workflows/ci.yml"><img src="https://github.com/cablate/mcp-google-map/actions/workflows/ci.yml/badge.svg" alt="CI status"></a>
  11. <a href="./LICENSE"><img src="https://img.shields.io/github/license/cablate/mcp-google-map" alt="MIT license"></a>
  12. </p>
  13. ## Why use it?
  14. Giving an agent a raw Maps API is only the beginning. Useful answers often require several dependent calls: resolve a place, preserve its identity, search around it, check opening details, calculate travel time, and explain what was actually verified. This project packages that work into one consistent interface.
  15. - **Move from lookup to outcome.** Atomic tools handle geocoding, place details, directions, weather, air quality, and maps. Composite tools explore areas, compare candidates, optimize stops, and measure local rankings.
  16. - **Use the same capabilities with or without MCP.** The standalone `exec` CLI works with Agent Skills and automation; the MCP server exposes the same 18 tools over stdio or HTTP.
  17. - **Give agents workflow guidance, not just function names.** Three Skills cover general map research, evidence-backed travel planning, and local SEO. Codex loads their full instructions only when a request matches.
  18. - **Keep deployment and credentials under your control.** Run locally or self-host. API keys remain in your environment or request headers, with per-session isolation for HTTP deployments.
  19. - **Start narrow and grow later.** Register only the tools you need with `GOOGLE_MAPS_ENABLED_TOOLS`, or use the full catalog.
  20. <p align="center"><img src="./assets/demo-grid-en.png" alt="Examples of travel planning with checked places and routes" width="800"></p>
  21. ## What can an agent do?
  22. | Outcome | How the project helps |
  23. |---|---|
  24. | Find and evaluate real places | Natural-language and nearby search, place details, ratings, hours, reviews, and distance comparison |
  25. | Build a trip that works geographically | Candidate discovery, along-route stops, travel-time checks, multi-stop optimization, weather, and static maps |
  26. | Research a neighborhood | Multi-category exploration plus targeted distance, elevation, timezone, weather, and air-quality checks |
  27. | Plan field work or deliveries | Route matrices and optimized stop ordering for up to 25 stops |
  28. | Audit local search visibility | Geographic grid ranking, competitor discovery, ARP, ATRP, and SoLV metrics |
  29. | Enrich location data | Single or batch geocoding, reverse geocoding, and structured JSON output |
  30. These are data and planning tools, not guarantees of safety, accessibility, opening status, or ranking outcomes. Applications displaying Places reviews, photos, or AI summaries must follow the [content attribution and storage guidance](./skills/_shared/content-attribution.md).
  31. ## Choose your integration
  32. | Use | Best for | What runs |
  33. |---|---|---|
  34. | **Codex Plugin** | Asking Codex map, travel, or local SEO questions without MCP configuration | A matching Skill loads on demand and calls the standalone CLI |
  35. | **Claude Code Plugin** | Installing the same three Skills from a Claude marketplace | Skills are namespaced under `mcp-google-map` and call the standalone CLI |
  36. | **Standalone CLI** | Scripts, automation, and other Skill-compatible agents | One stateless command returns JSON |
  37. | **MCP stdio** | Claude Desktop, Cursor, VS Code, and other local MCP clients | The client starts a local MCP process |
  38. | **Streamable HTTP** | Multi-session, containerized, LAN, or remote access | A self-hosted server exposes `/mcp` |
  39. All options require Node.js 22+ and a Google Maps Platform API key. Live calls may be billable. Enable the APIs needed by your selected tools; common place and route workflows require **Places API (New)**, **Routes API**, and often **Geocoding API**.
  40. ## Start with Codex—no MCP required
  41. ```bash
  42. codex plugin marketplace add cablate/mcp-google-map --ref main
  43. codex plugin add mcp-google-map@cablate
  44. ```
  45. Set `GOOGLE_MAPS_API_KEY` in the environment where Codex runs, then start a new conversation. Verify the local setup without making a Google API request:
  46. ```bash
  47. npx -y @cablate/mcp-google-map doctor
  48. ```
  49. Success means the `node`, `package`, and `api-key` checks pass and `live-api` is skipped. Use `doctor --live` only when you intend to send potentially billable checks to Geocoding, Places, and Routes.
  50. Try asking:
  51. > Plan a practical two-day Kyoto itinerary. Group nearby places, check travel times, and explain any opening-hour assumptions.
  52. Codex selects `google-maps` for general location research, `google-maps-travel-planning` for itineraries, or `google-maps-local-seo` for business visibility analysis. The plugin does not register or start an MCP server. See the [no-MCP walkthrough](./examples/agent-skill-demo.md) for a reproducible example.
  53. ## Install in Claude Code—no MCP required
  54. ```bash
  55. claude plugin marketplace add cablate/mcp-google-map
  56. claude plugin install mcp-google-map@cablate-maps
  57. ```
  58. Start a new Claude Code session, set `GOOGLE_MAPS_API_KEY` in its environment, and run the same `doctor` check shown above. Claude exposes the installed Skills with the plugin namespace, for example `/mcp-google-map:google-maps-travel-planning`.
  59. Each GitHub release also includes a versioned `mcp-google-map-claude-plugin-v*.zip` and SHA-256 checksum for direct distribution. The release workflow builds this archive from the same `skills/` source and validates it with Claude Code's official strict validator before publishing.
  60. ## Use the standalone CLI
  61. Every MCP tool also has a short CLI name:
  62. ```bash
  63. npx -y @cablate/mcp-google-map exec geocode '{"address":"Tokyo Tower"}'
  64. npx -y @cablate/mcp-google-map exec search-places '{"query":"quiet cafes in Kyoto"}'
  65. npx -y @cablate/mcp-google-map exec directions '{"origin":"Tokyo Station","destination":"Tokyo Skytree","mode":"transit"}'
  66. ```
  67. Each call is stateless. Successful calls return `{ "success": true, "data": ... }` on stdout; failures exit nonzero and write structured JSON to stderr.
  68. For bulk address enrichment:
  69. ```bash
  70. npx @cablate/mcp-google-map batch-geocode -i addresses.txt -o results.json
  71. cat addresses.txt | npx @cablate/mcp-google-map batch-geocode -i -
  72. ```
  73. ## Connect an MCP client
  74. ### stdio
  75. ```json
  76. {
  77. "mcpServers": {
  78. "google-maps": {
  79. "command": "npx",
  80. "args": ["-y", "@cablate/mcp-google-map", "--stdio"],
  81. "env": { "GOOGLE_MAPS_API_KEY": "YOUR_API_KEY" }
  82. }
  83. }
  84. }
  85. ```
  86. To reduce tool-list context, add a comma-separated allowlist such as `"GOOGLE_MAPS_ENABLED_TOOLS": "maps_geocode,maps_directions,maps_search_places"`. Omit it or use `*` to expose all tools.
  87. ### Streamable HTTP
  88. ```bash
  89. npx @cablate/mcp-google-map --host 127.0.0.1 --port 3000 --apikey "YOUR_API_KEY"
  90. ```
  91. ```json
  92. {
  93. "mcpServers": {
  94. "google-maps": {
  95. "type": "http",
  96. "url": "http://127.0.0.1:3000/mcp"
  97. }
  98. }
  99. }
  100. ```
  101. Bind to `0.0.0.0` only when the server must accept external connections. For multi-tenant deployments, prefer the `X-Google-Maps-API-Key` request header so keys remain isolated by session.
  102. ## Tool catalog
  103. | Group | Tools |
  104. |---|---|
  105. | Places and discovery | `maps_search_places`, `maps_search_nearby`, `maps_place_details`, `maps_explore_area`, `maps_compare_places`, `maps_search_along_route` |
  106. | Location and routing | `maps_geocode`, `maps_reverse_geocode`, `maps_directions`, `maps_distance_matrix`, `maps_plan_route`, `maps_batch_geocode` |
  107. | Context and visualization | `maps_elevation`, `maps_timezone`, `maps_weather`, `maps_air_quality`, `maps_static_map` |
  108. | Local SEO | `maps_local_rank_tracker` |
  109. All 18 tools declare `readOnlyHint: true` and `destructiveHint: false`. Exact parameters, response shapes, and workflow recipes live in the [tool reference](./skills/google-maps/references/tools-api.md).
  110. ## API key and Google Cloud setup
  111. The key must belong to a Google Cloud project with billing enabled and restrictions compatible with the runtime. The [setup and diagnostics guide](./skills/_shared/setup-and-diagnostics.md) maps each capability to its required API and explains common failures.
  112. Credential priority is:
  113. 1. `X-Google-Maps-API-Key` HTTP request header
  114. 2. `--apikey` command-line option
  115. 3. `GOOGLE_MAPS_API_KEY` environment variable
  116. Prefer environment variables or request headers. Command-line secrets can appear in shell history and process listings.
  117. ## Trust and limits
  118. - Place and route facts come from the Google Maps Platform APIs enabled for your project; weather availability has regional limitations.
  119. - A successful API response does not prove accessibility, safety, legal suitability, or real-time availability.
  120. - The package preserves source and disclosure metadata where returned, but your interface remains responsible for compliant attribution and storage.
  121. - HTTP mode supports per-session API-key isolation and DNS rebinding protection.
  122. - This project is MIT licensed and self-hostable. See [SECURITY.md](./SECURITY.md) for vulnerability reporting and [Security Assessment Clarifications](./SECURITY_ASSESSMENT.md) for the review checklist.
  123. ## Development
  124. ```bash
  125. git clone https://github.com/cablate/mcp-google-map.git
  126. cd mcp-google-map
  127. npm ci
  128. npm run build
  129. npm run test:unit
  130. npm test
  131. ```
  132. Live E2E calls require `GOOGLE_MAPS_API_KEY` and may be billable: `npm run test:e2e`.
  133. Contributions are welcome. Read [CONTRIBUTING.md](./CONTRIBUTING.md) before opening a pull request. Release history is in [CHANGELOG.md](./CHANGELOG.md).
  134. ## Acknowledgements
  135. Thanks to [@junyinnnn](https://github.com/junyinnnn) for helping add Streamable HTTP support.
  136. ## License
  137. [MIT](./LICENSE)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.