# @cablate/mcp-google-map 中文文档

规范地址：https://npmcn.com/package/%40cablate/mcp-google-map/

版本：0\.0\.69
npm 元数据更新时间：2026-09-26T20:34:56.989Z
中文译文更新时间：2026-11-08T22:55:45.919Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40cablate/mcp-google-map
原文对照：https://npmcn.com/package/%40cablate/mcp-google-map/?lang=original
项目主页：https://github.com/cablate/mcp-google-map#readme
源码仓库：https://github.com/cablate/mcp-google-map

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：174 kB，22 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=18\.0\.0
- 运行依赖：9 个
- 首次发布：2025-02-22T10:59:05.378Z
- 最新版本发布：2026-09-26T20:34:56.825Z
- 近 30 天下载量：4300（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：67（近 12 个月 48 个）

## 中文简介

18个用于AI代理的Google地图工具——地理代码,搜索,方向,天气,空气质量,地级跟踪,地图图像通过MCP服务器或独立的CLI

## 安装

```sh
npm install @cablate/mcp-google-map
```

也可以使用：`pnpm add @cablate/mcp-google-map`、`yarn add @cablate/mcp-google-map`、`bun add @cablate/mcp-google-map`

## README

# 給 AI 代理使用的 Google Maps

**不用再為每一個 AI 應用重做地點搜尋、路線與位置工作流程。**

`@cablate/mcp-google-map` 將 Google Maps Platform 整理成 18 個唯讀代理工具與三個用途明確的 Skills。代理可以搜尋真實地點、驗證路線、比較選項、建立可執行的旅行計畫，或分析在地搜尋能見度；既可透過 MCP，也可直接使用獨立 CLI。

整合方式由你決定：不想設定 MCP 時安裝 Codex 或 Claude Code Plugin；桌面 MCP client 使用 stdio；共享或遠端部署則使用 Streamable HTTP。

[English](https://npmcn.com/package/%40cablate/mcp-google-map/README.md) · **繁體中文**

![提供給 AI 代理的 Google Maps 工具與工作流程](https://npmcn.com/package/%40cablate/mcp-google-map/assets/banner.webp)

[![npm 版本](https://img.shields.io/npm/v/@cablate/mcp-google-map)](https://www.npmjs.com/package/@cablate/mcp-google-map) [![npm 下載數](https://img.shields.io/npm/dm/@cablate/mcp-google-map)](https://www.npmjs.com/package/@cablate/mcp-google-map) [![CI 狀態](https://github.com/cablate/mcp-google-map/actions/workflows/ci.yml/badge.svg)](https://github.com/cablate/mcp-google-map/actions/workflows/ci.yml) [![MIT 授權](https://img.shields.io/github/license/cablate/mcp-google-map)](https://npmcn.com/package/%40cablate/mcp-google-map/LICENSE)

## 為什麼要用？

把原始 Maps API 交給代理只是第一步。真正有用的答案通常依賴一連串呼叫：確認地點、保留同一個地點的識別資訊、搜尋周邊、檢查營業資料、計算旅行時間，再清楚說明哪些內容真的驗證過。本專案把這些工作整理成一致的介面。

-   **從單次查詢走到可用成果。** 原子工具處理地址解析、地點詳情、導航、天氣、空氣品質與地圖；組合工具可探索區域、比較候選地點、最佳化停靠順序與分析在地排名。
-   **同一套能力可用或不用 MCP。** 獨立 `exec` CLI 適合 Agent Skills 與自動化；MCP server 則透過 stdio 或 HTTP 暴露相同的 18 個工具。
-   **不只提供函式名稱，也提供代理工作方法。** 三個 Skills 分別處理一般地圖研究、具證據的旅行規劃與 Local SEO。Codex 只有在請求符合時才載入完整指令。
-   **部署方式與憑證仍由你控制。** 可在本機執行或自行架設；API key 保留在環境變數或 request header，HTTP 部署亦支援每個 session 隔離。
-   **可以先小規模導入。** 透過 `GOOGLE_MAPS_ENABLED_TOOLS` 只註冊需要的工具，也可直接使用完整工具集。

![使用已檢查地點與路線進行旅行規劃的範例](https://npmcn.com/package/%40cablate/mcp-google-map/assets/demo-grid-zh.png)

## 代理能完成什麼？

| 成果 | 本專案提供的能力 |
| --- | --- |
| 搜尋並評估真實地點 | 自然語言與附近搜尋、地點詳情、評分、營業時間、評論與距離比較 |
| 建立地理上可執行的行程 | 候選地點探索、沿途停靠點、旅行時間檢查、多站最佳化、天氣與靜態地圖 |
| 研究一個區域 | 多類別區域探索，加上距離、海拔、時區、天氣與空氣品質查詢 |
| 規劃外勤或配送 | 路線矩陣，以及最多 25 個停靠點的順序最佳化 |
| 分析在地搜尋能見度 | 地理網格排名、競爭者探索、ARP、ATRP 與 SoLV 指標 |
| 補全位置資料 | 單筆或批次地址解析、反向地址解析與結構化 JSON 輸出 |

這些是資料與規劃工具，不保證安全、無障礙、即時營業狀態或排名成果。應用程式若顯示 Places 評論、照片或 AI 摘要，必須遵守[內容署名與保存指引](https://npmcn.com/package/%40cablate/mcp-google-map/skills/_shared/content-attribution.md)。

## 選擇整合方式

| 使用方式 | 適合情境 | 實際執行內容 |
| --- | --- | --- |
| **Codex Plugin** | 不設定 MCP，直接讓 Codex 回答地圖、旅行或 Local SEO 問題 | 符合請求的 Skill 按需載入並呼叫獨立 CLI |
| **Claude Code Plugin** | 從 Claude marketplace 安裝相同的三個 Skills | Skills 以 `mcp-google-map` namespace 載入並呼叫獨立 CLI |
| **獨立 CLI** | 腳本、自動化與其他支援 Skill 的代理 | 單次無狀態命令回傳 JSON |
| **MCP stdio** | Claude Desktop、Cursor、VS Code 與其他本機 MCP clients | Client 啟動本機 MCP 程序 |
| **Streamable HTTP** | 多 session、容器、區域網路或遠端存取 | 自架 server 暴露 `/mcp` |

所有方式都需要 Node.js 18+ 與 Google Maps Platform API key，實際 API 呼叫可能產生費用。請啟用所選工具需要的 API；常見地點與路線流程會使用 **Places API (New)**、**Routes API**，通常也需要 **Geocoding API**。

## 從 Codex 開始，不需要 MCP

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

在 Codex 的執行環境設定 `GOOGLE_MAPS_API_KEY`，再開啟新對話。先檢查本機環境，不會送出 Google API 請求：

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

成功時，`node`、`package` 與 `api-key` 檢查會通過，`live-api` 會略過。只有在你確定要送出可能計費的 Geocoding、Places 與 Routes 測試時，才使用 `doctor --live`。

可以直接問：

> 規劃一個實際可行的京都兩日行程。把鄰近地點排在一起、檢查交通時間，並說明營業時間有哪些假設。

Codex 會依請求選擇一般地圖研究、旅行規劃或 Local SEO Skill。Plugin 不會註冊或啟動 MCP server。可參考[非 MCP 完整示範](https://npmcn.com/package/%40cablate/mcp-google-map/examples/agent-skill-demo.md)重現整個流程。

## 安裝到 Claude Code，不需要 MCP

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

開啟新的 Claude Code session，在執行環境設定 `GOOGLE_MAPS_API_KEY`，再執行前述 `doctor` 檢查。Claude 會以 plugin namespace 顯示 Skills，例如 `/mcp-google-map:google-maps-travel-planning`。

每個 GitHub release 也會附上版本化的 `mcp-google-map-claude-plugin-v*.zip` 與 SHA-256 checksum，供直接散布。Release workflow 從同一份 `skills/` 來源產生壓縮檔，並在發布前使用 Claude Code 官方 strict validator 驗證。

## 使用獨立 CLI

每一個 MCP 工具都有簡短的 CLI 名稱：

```bash
npx -y @cablate/mcp-google-map exec geocode '{"address":"台北101"}'
npx -y @cablate/mcp-google-map exec search-places '{"query":"京都安靜的咖啡廳"}'
npx -y @cablate/mcp-google-map exec directions '{"origin":"台北車站","destination":"台北101","mode":"transit"}'
```

每次呼叫皆為無狀態。成功時在 stdout 回傳 `{ "success": true, "data": ... }`；失敗時以非零狀態結束，並在 stderr 輸出結構化 JSON。

批次補全地址可使用：

```bash
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 client

### stdio

```json
{
  "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

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

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

只有 server 確實需要接受外部連線時才綁定 `0.0.0.0`。多租戶部署建議使用 `X-Google-Maps-API-Key` request header，讓不同 session 的 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` |
| Local SEO | `maps_local_rank_tracker` |

全部 18 個工具都宣告 `readOnlyHint: true` 與 `destructiveHint: false`。完整參數、回應格式與工作流程範例見[工具參考](https://npmcn.com/package/%40cablate/mcp-google-map/skills/google-maps/references/tools-api.md)。

## API key 與 Google Cloud 設定

API key 所屬的 Google Cloud project 必須已啟用 billing，且 key restrictions 要與執行環境相容。[設定與診斷指南](https://npmcn.com/package/%40cablate/mcp-google-map/skills/_shared/setup-and-diagnostics.md)列出每項能力需要的 API，以及常見錯誤的處理方式。

憑證優先順序如下：

1.  `X-Google-Maps-API-Key` HTTP request header
2.  `--apikey` 命令列參數
3.  `GOOGLE_MAPS_API_KEY` 環境變數

建議使用環境變數或 request header。命令列中的秘密可能出現在 shell 歷史或程序清單。

## 信任與限制

-   地點與路線事實來自你為專案啟用的 Google Maps Platform APIs；天氣服務有區域限制。
-   API 成功回應不等於已證明無障礙、安全、法律適用性或即時可用性。
-   套件會保留 API 回傳的來源與揭露 metadata，但你的介面仍有責任符合署名與保存規範。
-   HTTP 模式支援每個 session 的 API key 隔離與 DNS rebinding 防護。
-   本專案採 MIT 授權且可自行架設。漏洞回報請見 [SECURITY.md](https://npmcn.com/package/%40cablate/mcp-google-map/SECURITY.md)；企業審查可參考 [Security Assessment Clarifications](https://npmcn.com/package/%40cablate/mcp-google-map/SECURITY_ASSESSMENT.md)。

## 開發

```bash
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`。

歡迎參與貢獻。送出 pull request 前請先閱讀 [CONTRIBUTING.md](https://npmcn.com/package/%40cablate/mcp-google-map/CONTRIBUTING.md)；版本紀錄見 [CHANGELOG.md](https://npmcn.com/package/%40cablate/mcp-google-map/CHANGELOG.md)。

## 特別感謝

感謝 [@junyinnnn](https://github.com/junyinnnn) 協助加入 Streamable HTTP 支援。

## 授權

[MIT](https://npmcn.com/package/%40cablate/mcp-google-map/LICENSE)

## 常见问题

### @cablate/mcp-google-map 是什么？

18个用于AI代理的Google地图工具——地理代码,搜索,方向,天气,空气质量,地级跟踪,地图图像通过MCP服务器或独立的CLI

### 如何安装 @cablate/mcp-google-map？

在项目目录运行 npm install @cablate/mcp-google-map，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 mcp-google-map，可以用 npx mcp-google-map 直接运行。

### @cablate/mcp-google-map 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @cablate/mcp-google-map 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @cablate/mcp-google-map 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=18\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @cablate/mcp-google-map 可以商用吗？

@cablate/mcp-google-map 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @cablate/mcp-google-map 的下载量有多少？

根据 npm 官方下载统计，@cablate/mcp-google-map 在 2026/10/09 – 2026/11/07 这 30 天内被下载 4,300 次，日均约 143 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @cablate/mcp-google-map 还在维护吗？

最新版本 0\.0\.69 发布于 2026/09/27（1 个月前）；至今共发布 67 个版本，其中过去 12 个月发布了 48 个；首次发布于 2025/02/22。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。