Google Maps 資料 / MCP 伺服器

在您的 AI 工作流程中使用 Google Maps 資料。

透過 Claude Code、Cursor、VS Code 或 Codex 尋找商家、閱讀公開評論、瀏覽地點相簿。三個遠端工具,同一把 API 金鑰。

適用於您的 MCP 用戶端

遠端 Streamable HTTP · 私密 API 金鑰 · 免費與付費 API 方案

三個工具 / 一次連線

從商家發掘到地點詳情。

每個工具直接傳回結果。選擇任務所需的操作,並明確指定所需頁數。

尋找商家

search_google_maps

搜尋某個類別和地點。接收最多 20 家商家,包含可用的清單、聯絡方式、評分和評論數欄位。

q · page · extra

探索 Search API

閱讀公開評論

get_google_maps_reviews

使用地點的 feature ID 請求最多 10 則評論。可選相關性、最新、最高評分或最低評分。

fid · page · sort_by

探索 Reviews API

瀏覽相簿媒體

get_google_maps_photos

取得某個地點最多 20 筆照片和影片中繼資料記錄。讀取傳回的媒體 URL 和分頁旗標。

fid · page

探索 Photos API

Reviews 和 Photos 接受來自搜尋結果 place.dataId 的 Maps feature ID。Search 使用第 1–10 頁;媒體工具傳回 next,供您的 AI 助理判斷是否需要下一頁。

MCP 連線

一個端點,您的 API 工作區。

您的用戶端負責初始化和工具探索,然後在每個請求中攜帶您的 API 金鑰。

遠端 MCP 連線
POST https://gmapscrawl.com/api/mcp
Authorization: Bearer <YOUR_API_KEY>
Content-Type: application/json
Accept: application/json, text/event-stream

用戶端設定

選擇您使用的用戶端。

建立 API 金鑰,然後複製對應用戶端的設定。將金鑰保存在其環境或受保護的 input 設定中。

將此伺服器新增到 .mcp.json。確保 GMSCRAPER_API_KEY 在啟動 Claude Code 的環境中可用。

{
  "mcpServers": {
    "google-maps-data": {
      "type": "http",
      "url": "https://gmapscrawl.com/api/mcp",
      "headers": {
        "Authorization": "Bearer ${GMSCRAPER_API_KEY}"
      }
    }
  }
}

儲存設定後,重新連線並確認出現這三個工具。按照分步設定指南操作。

您的第一個工作流程

連線、測試一頁、讀取結果。

先用測試金鑰和模擬資料開始。準備好使用 API 額度後再切換到正式金鑰。

01

準備您的工作區

選擇 API 產品並建立帶 scrapes:write 的測試金鑰。您的 API 方案必須允許 MCP;線上擷取工具和瀏覽器擴充功能有獨立額度。

建立金鑰
02

探索並呼叫一個工具

連接您的用戶端,檢視 search_google_maps,並請求一頁資料。為新任務產生新的請求 ID,重試同一請求時保留該 ID。

檢視用戶端設定
03

使用傳回的商家

讀取 structuredContent.businesses 和 total。將測試結果標記為模擬資料,保留缺失值,並在所請求的頁面處停止。

瞭解這些欄位
呼叫 search_google_maps

每次新搜尋都替換請求 ID。此範例不會在頁面上執行請求。

{
  "q": "coffee shops in Seattle",
  "page": 1,
  "hl": "en",
  "extra": false,
  "client_request_id": "replace-with-a-fresh-uuid"
}

傳回的內容

結構化記錄,在同一個工具回應中。

businesses
最多 20 家傳回商家;欄位可能缺失。
params + total
正規化後的查詢以及本頁數量。
simulated + usage metadata
測試回應標識為模擬資料,消耗 0 個正式請求單位。
isError
在回報工具成功之前,先檢查錯誤。

結果直接傳回,無需任務輪詢。將 JSON 轉成表格或報告時,請保留來源觀測日期。

範例提示詞

一個有用的問題,一個明確的停止點。

連線後使用這些提示詞。需要時提供真實的 feature ID,並讓您的 AI 助理將測試結果標記為模擬資料。

建立聚焦的商家名單

“對西雅圖的咖啡店使用一次 search_google_maps,第 1 頁,extra 為 false。傳回商家的名稱、網站、電話號碼、評分和評論數。缺失欄位留空並顯示觀測日期。處理完本頁後停止。”

預期結果

一張最多 20 家傳回商家的表格,保留來源時間戳記和缺失值。

總結一頁評論

“對於我選定的商家,將其 place.dataId 作為 fid。用 sort_by 2 請求 get_google_maps_reviews 的第 1 頁。只總結這些傳回評論中的主題並註明日期。不要取得額外頁面。”

預期結果

一份基於最多 10 則評論的有限總結,不會把一頁資料當作所有客戶的體驗。

檢視一個相簿

“對這個提供的 feature ID 使用 get_google_maps_photos,僅第 1 頁。列出傳回的 photoUrl 和可選 videoUrl 欄位,並回報 next 是否為 true。不要下載檔案或取得下一頁。”

預期結果

最多 20 筆相簿記錄以及傳回的分頁狀態,供您自己的應用程式檢查。

REST + MCP

兩種介面共用一套 API 額度。

免費和付費 API 方案均可使用 MCP。每個成功的正式來源頁(包括空白頁)消耗一個 API 請求單位。

01

測試不消耗正式用量

測試金鑰傳回模擬資料,消耗 0 個請求單位。它們用於驗證您的整合,而不是產生真實的潛在客戶。

管理 API 金鑰
02

讓請求保持有邊界

只請求任務所需的頁面和地點。新任務使用新的請求 ID;對不確定的請求用相同輸入和 ID 重試。

閱讀用量指引
03

新增可重複使用的說明

Google Maps Data Agent Skill 為同樣的工具增加工作流程指引、操作參考和 REST 備用方案。

探索 Agent Skill

探索 API 中心 → 線上擷取工具和瀏覽器擴充功能方案有各自的額度。

連線協助

走到下一個成功的請求。

根據連線狀態和傳回的錯誤選擇下一步。

用戶端已連線但沒有出現工具
確認端點為 /api/mcp,且您的用戶端支援帶私密 Authorization 請求標頭的遠端 Streamable HTTP。重新載入連線,並檢查其程序能否讀取設定的金鑰。
401 或 403
檢查金鑰到期時間、允許的 IP、有效的工作區存取權限、scrapes:write 權限範圍,以及允許使用 MCP 的 API 方案。瀏覽器登入 Cookie 無法驗證此端點。
invalid_request
閱讀所選工具的 schema。提供 16–128 個字元的唯一 client_request_id;評論和照片還需要來自 place.dataId 的 FID,而不是商家名稱或其他地點識別碼。
rate_limited 或 quota_exceeded
速率限制請遵守 retry_after。API 額度耗盡時請停止並檢查您的 API 用量;再建立金鑰不會增加額度。
capability_unavailable 或來源故障
檢查服務狀態和傳回的錯誤。可用性由伺服器決定。在結果中明確標記缺失或不可用的資料。
逾時或 isError: true
即使 HTTP 連線成功也要檢查工具錯誤。對可重試的失敗,在任務截止時間內使用相同輸入和請求 ID。開始新嘗試前請遵循終止性錯誤指引。

服務狀態 錯誤與重試指引

常見問題

Google Maps MCP 伺服器能做什麼?

它提供 search_google_maps、get_google_maps_reviews 和 get_google_maps_photos。Search 每頁最多傳回 20 家商家;評論最多傳回 10 筆記錄,照片最多傳回 20 筆相簿記錄。這些工具直接傳回結構化資料。

我可以連接哪些用戶端?

使用支援遠端 Streamable HTTP 和私密 Authorization 請求標頭的 Claude Code、Cursor、VS Code、Codex 或其他 MCP 用戶端版本。上方四種用戶端設定使用同一端點和 API 工作區金鑰。

如何驗證?

在您的 API 工作區建立帶 scrapes:write 的 API 金鑰,並將其以私密方式設定為 Bearer 請求標頭。瀏覽器 Cookie 無法驗證 MCP。請將金鑰放在提示詞、URL 和已提交的原始碼之外。

評論和照片如何找到正確的地點?

將 Maps feature ID 作為 fid 傳入。您可以使用傳回商家中的 place.dataId。評論還接受 sort_by:1 表示相關性,2 表示最新,3 表示最高評分,4 表示最低評分。在考慮下一頁媒體資料前先讀取 next。

MCP 有單獨的額度嗎?

MCP 與 REST API 共用額度,免費和付費 API 方案均可使用。一個成功的正式頁消耗一個請求單位,包括空白頁。測試憑證傳回模擬資料,消耗 0 個單位。線上擷取工具和瀏覽器擴充功能的額度是獨立的。

我還需要 Agent Skill 嗎?

MCP 伺服器可以獨立運作。可選的 Google Maps Data Agent Skill 會額外提供可重複使用說明、操作參考,以及在您設定的 MCP 連線不可用時用於 REST 備用方案的輔助工具。

踏出下一步

把 Google Maps 資料帶進您的下一次對話。

建立 API 金鑰,連接您喜歡的用戶端,並測試一次聚焦的商家搜尋。