google-maps

Google Maps

使用软件包独立的 exec CLI 回答现实世界中的地点问题。此工作流无需启动或配置 MCP 服务。

调用 CLI 前

• 在会话中首次调用时，或执行失败后，读取 ../_shared/setup-and-diagnostics.md 并运行不产生费用的本地预检。
• 用户必须提供 GOOGLE_MAPS_API_KEY。除非用户明确接受 Shell 历史记录和进程列表暴露风险，否则切勿打印该密钥或将其写入命令。
• 展示地点评论、照片或 AI 摘要前，读取 ../_shared/content-attribution.md。

工作流

1. 确定具体的地点需求和缺失的输入。无需询问可通过地理编码或地点搜索解决的详情。
2. 需要精确参数、响应字段或多工具调用方案时，读取 references/tools-api.md。
3. 优先使用坐标而非有歧义的地址，并优先使用 place_id 而非重复搜索名称。
4. 仅串联完成需求所需的调用。复用返回的标识符和坐标。
5. 将非零退出状态或 { "success": false } 视为失败，而非地理数据。
6. 总结有用结果，而非返回原始 JSON。必要时保留来源和署名元数据。

工具选择

需求	首选工具
将地址或地标转换为坐标	maps_geocode
将坐标转换为地址	maps_reverse_geocode
搜索附近地点	maps_search_nearby，然后使用 maps_place_details
自然语言地点搜索	maps_search_places，然后使用 maps_place_details
比较候选地点	maps_compare_places，或搜索 → 详情 → 距离矩阵
路线或出行方式比较	maps_directions、maps_distance_matrix
规划不含更广泛行程的多站路线	maps_plan_route
搜索沿途地点	maps_search_along_route
获取街区信息	maps_explore_area，并配合有针对性的附近搜索
海拔、时区、天气或空气质量	对应的环境工具；必要时先进行地理编码
可视化地图	确定地点或路线后使用 maps_static_map

调用方式

npx -y @cablate/mcp-google-map exec <tool> '<json_params>'

CLI 同时接受 maps_geocode 这类 MCP 风格名称和 geocode 这类简短名称。每次调用均为无状态，并在 stdout 上返回 JSON。

使用边界

• 对于多日行程、旅行日程或出行日优化，请改用 google-maps-travel-planning。
• 对于 Google Business Profile 的曝光度、网格排名、关键词覆盖率或竞争对手审核，请改用 google-maps-local-seo。
• maps_weather 在日本、中国、韩国、古巴、伊朗、朝鲜和叙利亚不可用；请在这些地区使用最新的网络来源。
• 不支持公共交通途经点优化；公共交通路线请使用 optimize: false。
• 仅凭地理距离和海拔无法确定安全性、无障碍程度、洪水风险或适用性。相关时请说明这些限制。

参考资料

• references/tools-api.md：需要精确参数、响应格式和通用串联调用方案时阅读。
• ../_shared/setup-and-diagnostics.md：首次运行检查和错误分类时阅读。
• ../_shared/content-attribution.md：展示受 Google Maps 规范约束的内容前阅读。