MCP Google Map Server

面向 AI Agent 的 Google Maps

无需为每个 AI 应用重新构建地点搜索、路线规划和位置工作流。

@cablate/mcp-google-map 将 Google Maps Platform 转化为 18 个只读 Agent 工具和 3 个专用 Skills。Agent 可以查找真实地点、核验路线、比较选项、制定实用行程，或审查本地搜索曝光度——通过 MCP 或独立 CLI 均可使用。

由你选择集成方式：想要 Skills 且无需配置 MCP 时使用 Codex 或 Claude Code Plugin；桌面 MCP 客户端使用 stdio；共享部署和远程部署使用 Streamable HTTP。

English · 繁體中文

为什么使用它？

为 Agent 提供原始 Maps API 只是第一步。要获得有用的答案，通常需要多次相互依赖的调用：解析地点、保留其身份、搜索周边、查看营业详情、计算出行时间，并说明实际核验了哪些信息。本项目将这些工作整合为统一的接口。

• 从查询迈向结果。 原子工具可处理地理编码、地点详情、路线、天气、空气质量和地图。组合工具可探索区域、比较候选项、优化停靠点，并衡量本地排名。
• 无论是否使用 MCP，都能使用相同的功能。 独立的 exec CLI 可与 Agent Skills 和自动化配合使用；MCP 服务则通过 stdio 或 HTTP 提供相同的 18 个工具。
• 为 Agent 提供工作流指南，而不只是函数名称。 3 个 Skills 分别涵盖一般地图研究、有依据的旅行规划和本地 SEO。只有请求与其匹配时，Codex 才会加载完整说明。
• 部署方式和凭据由你掌控。 可在本地运行或自行托管。API 密钥保留在你的环境或请求标头中；HTTP 部署按会话隔离。
• 先从小范围开始，再逐步扩展。 使用 GOOGLE_MAPS_ENABLED_TOOLS 仅注册所需工具，也可以使用完整目录。

Agent 可以做什么？

目标	项目如何提供帮助
查找并评估真实地点	自然语言搜索和附近搜索、地点详情、评分、营业时间、评论和距离比较
制定地理位置合理的行程	发现候选地点、查找沿途停靠点、核验出行时间、优化多站点路线、查看天气和静态地图
研究街区	多类别探索，并针对距离、海拔、时区、天气和空气质量进行定向核验
规划实地工作或配送	路线矩阵和最多 25 个停靠点的优化排序
审查本地搜索曝光度	地理网格排名、竞争对手发现、ARP、ATRP 和 SoLV 指标
丰富位置数据	单次或批量地理编码、反向地理编码和结构化 JSON 输出

这些是数据和规划工具，不能保证安全性、无障碍状况、营业状态或排名结果。展示 Places 评论、照片或 AI 摘要的应用必须遵循内容署名和存储指南。 <translated_markdown>

选择集成方式

用途	最适合	运行方式
Codex Plugin	无需配置 MCP，即可向 Codex 咨询地图、旅行或本地 SEO 问题	按需加载匹配的 Skill，并调用独立 CLI
Claude Code Plugin	从 Claude marketplace 安装相同的三个 Skill	Skill 命名空间为 mcp-google-map，并调用独立 CLI
独立 CLI	脚本、自动化和其他兼容 Skill 的 Agent	一条无状态命令返回 JSON
MCP stdio	Claude Desktop、Cursor、VS Code 及其他本地 MCP 客户端	客户端启动本地 MCP 进程
Streamable HTTP	多会话、容器化、局域网或远程访问	可自托管的服务公开 /mcp

所有选项都需要 Node.js 22+ 和 Google Maps Platform API 密钥。实时调用可能产生费用。请启用所选工具所需的 API；常见的地点和路线工作流需要 Places API (New)、Routes API，通常还需要 Geocoding API。

从 Codex 开始——无需 MCP

codex plugin marketplace add cablate/mcp-google-map --ref main
codex plugin add mcp-google-map@cablate

在 Codex 运行环境中设置 GOOGLE_MAPS_API_KEY，然后开始新对话。无需调用 Google API，即可验证本地配置：

npx -y @cablate/mcp-google-map doctor

成功表示 node、package 和 api-key 检查均通过，且跳过 live-api。只有在准备向 Geocoding、Places 和 Routes 发送可能产生费用的检查时，才使用 doctor --live。

试着询问：

制定一份实用的京都两日行程。将相近的地点分组，查询出行时间，并说明任何关于营业时间的假设。

Codex 会为一般位置研究选择 google-maps，为行程规划选择 google-maps-travel-planning，或为商家可见度分析选择 google-maps-local-seo。该插件不会注册或启动 MCP 服务。可参阅无需 MCP 的操作指南，查看可复现示例。

在 Claude Code 中安装——无需 MCP

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

启动新的 Claude Code 会话，在其运行环境中设置 GOOGLE_MAPS_API_KEY，然后运行上文所示的相同 doctor 检查。Claude 会通过插件命名空间提供已安装的 Skill，例如 /mcp-google-map:google-maps-travel-planning。

每个 GitHub 发布版本还包含带版本号的 mcp-google-map-claude-plugin-v*.zip 和 SHA-256 校验和，可供直接分发。发布工作流会使用相同的 skills/ 源构建此压缩包，并在发布前使用 Claude Code 官方严格验证器进行验证。

使用独立 CLI

每个 MCP 工具也都有简短的 CLI 名称：

npx -y @cablate/mcp-google-map exec geocode '{"address":"Tokyo Tower"}'
npx -y @cablate/mcp-google-map exec search-places '{"query":"quiet cafes in Kyoto"}'
npx -y @cablate/mcp-google-map exec directions '{"origin":"Tokyo Station","destination":"Tokyo Skytree","mode":"transit"}'

每次调用都是无状态的。成功调用会在 stdout 上返回 { "success": true, "data": ... }；失败时以非零状态码退出，并向 stderr 写入结构化 JSON。

批量补充地址信息：

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

连接 MCP 客户端

stdio

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

为减少工具列表占用的上下文，可添加以逗号分隔的允许列表，例如 "GOOGLE_MAPS_ENABLED_TOOLS": "maps_geocode,maps_directions,maps_search_places"。省略该设置或使用 *，即可公开所有工具。

Streamable HTTP

npx @cablate/mcp-google-map --host 127.0.0.1 --port 3000 --apikey "YOUR_API_KEY"

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

仅当服务必须接受外部连接时，才绑定到 0.0.0.0。对于多租户部署，建议使用 X-Google-Maps-API-Key 请求头，以便按会话隔离密钥。

工具目录

分组	工具
地点与发现	maps_search_places、maps_search_nearby、maps_place_details、maps_explore_area、maps_compare_places、maps_search_along_route
位置与路线规划	maps_geocode、maps_reverse_geocode、maps_directions、maps_distance_matrix、maps_plan_route、maps_batch_geocode
上下文与可视化	maps_elevation、maps_timezone、maps_weather、maps_air_quality、maps_static_map
本地 SEO	maps_local_rank_tracker

全部 18 个工具均声明 readOnlyHint: true 和 destructiveHint: false。确切参数、响应结构和工作流示例请参阅工具参考。 </translated_markdown>

API 密钥和 Google Cloud 设置

该密钥必须属于已启用结算功能且限制与运行时兼容的 Google Cloud 项目。设置和诊断指南介绍了各项功能所需的 API，并说明了常见故障。

凭据优先级如下：

1. X-Google-Maps-API-Key HTTP 请求标头
2. --apikey 命令行选项
3. GOOGLE_MAPS_API_KEY 环境变量

建议使用环境变量或请求标头。命令行密钥可能会出现在 shell 历史记录和进程列表中。

信任与限制

• 地点和路线信息来自项目已启用的 Google Maps Platform API；天气服务的可用性受地区限制。
• API 响应成功并不能证明信息具备无障碍性、安全性、法律适用性或实时可用性。
• 本软件包会在返回时保留来源和披露元数据，但合规归属标注和存储仍由你的界面负责。
• HTTP 模式支持按会话隔离 API 密钥，并提供 DNS 重绑定保护。
• 本项目采用 MIT 许可证，可自托管。有关漏洞报告，请参阅 SECURITY.md；有关审查清单，请参阅 Security Assessment Clarifications。

开发

git clone https://github.com/cablate/mcp-google-map.git
cd mcp-google-map
npm ci
npm run build
npm run test:unit
npm test

实时 E2E 调用需要 GOOGLE_MAPS_API_KEY，并且可能产生费用：npm run test:e2e。

欢迎贡献。提交拉取请求前，请阅读 CONTRIBUTING.md。发布历史见 CHANGELOG.md。

致谢

感谢 @junyinnnn 帮助添加 Streamable HTTP 支持。

许可证

MIT