MCP Reference: mapstools.googleapis.com

這是 Maps Grounding Lite API 提供的 MCP 伺服器。伺服器提供工具，供開發人員在 Google 地圖平台之上建構 LLM 應用程式。

Model Context Protocol (MCP) 伺服器可做為代理伺服器，在外部服務與大型語言模型 (LLM) 或 AI 應用程式之間傳遞脈絡、資料或功能。MCP 伺服器可將 AI 應用程式連結至資料庫和 Web 服務等外部系統，並將系統回覆轉換成 AI 應用程式可理解的格式。

伺服器設定

您必須先啟用 MCP 伺服器並設定驗證，才能使用這項功能。如要進一步瞭解如何使用 Google 和 Google Cloud 遠端 MCP 伺服器，請參閱 Google Cloud MCP 伺服器總覽。

伺服器端點

MCP 服務端點是 MCP 伺服器的網路位址和通訊介面 (通常是網址)，AI 應用程式 (MCP 用戶端的主機) 會使用這個端點建立安全標準連線。這是 LLM 請求情境、呼叫工具或存取資源的聯絡點。Google MCP 端點可以是全域或區域。

Maps Grounding Lite API MCP 伺服器具有下列全域 MCP 端點：

  • https://mapstools.googleapis.com/mcp

MCP 工具

MCP 工具是 MCP 伺服器向 LLM 或 AI 應用程式公開的函式或可執行功能，可在現實世界中執行動作。

工具

mapstools.googleapis.com MCP 伺服器提供下列工具：

MCP 工具
search_places

當使用者要求尋找地點、商家、地址、位置、興趣點或任何其他 Google 地圖相關搜尋時，請呼叫這項工具。

輸入規定 (重要)：

  1. text_query (字串 - 必填)：主要搜尋查詢。這項資訊必須清楚定義使用者要尋找的內容。

    • 示例：'restaurants in New York'、'coffee shops near Golden Gate Park'、'SF MoMA'、'1600 Amphitheatre Pkwy, Mountain View, CA, USA'、'pets friendly parks in Manhattan, New York'、'date night restaurants in Chicago'、'accessible public libraries in Los Angeles'。
    • 如要取得特定地點的詳細資料：請加入要求的屬性 (例如 'Google Store Mountain View opening hours'、'SF MoMa phone number'、'Shoreline Park Mountain View address')。

  2. location_bias (物件 - 選用)：使用這個物件，優先顯示特定地理區域附近的結果。

    • 格式： {"location_bias": {"circle": {"center": {"latitude": [value], "longitude": [value]}, "radius_meters": [value (optional)]}}}
    • 使用方式：
      • 如要將半徑設為 5 公里： {"location_bias": {"circle": {"center": {"latitude": 34.052235, "longitude": -118.243683}, "radius_meters": 5000}}}
      • 強烈偏向聚焦點： {"location_bias": {"circle": {"center": {"latitude": 34.052235, "longitude": -118.243683}}}} (省略 radius_meters)。

  3. language_code (字串 - 選用)：顯示搜尋結果摘要的語言。

    • 格式：兩個字母的語言代碼 (ISO 639-1)，後面可選擇加上底線和兩個字母的國家/地區代碼 (ISO 3166-1 alpha-2)，例如 en、ja、en_US、zh_CN、es_MX。如未提供語言代碼，結果會以英文顯示。

  4. region_code (字串 - 選填)：使用者的 Unicode CLDR 區域代碼。這個參數用於顯示地點詳細資料，例如特定區域的地點名稱 (如有)。根據適用法律，這項參數可能會影響結果。

    • 格式：由兩個英文字母組成的國家/地區代碼 (ISO 3166-1 alpha-2)，例如 US、CA。

工具呼叫的指示：

  • 位置資訊 (重要)：搜尋內容必須包含充足的位置資訊。如果地點不明確 (例如只有「披薩店」)，您必須在 text_query 中指定地點 (例如「紐約的披薩店」)，或使用 location_bias 參數。如需消歧義，請加入城市、州/省和區域/國家/地區名稱。

  • 請盡量提供最具體且符合情境的 text_query。

  • 只有在明確提供座標，或從使用者已知情境推斷位置資訊是適當且有助於提升結果品質時，才使用 location_bias。

  • 如有 attribution 欄位資訊，系統必須使用該資訊將基礎輸出內容歸因於來源。
lookup_weather

擷取完整的天氣資料，包括目前天氣狀況、每小時和每日預報。

可用的特定資料：溫度 (目前、體感、最高/最低、熱指數)、風 (風速、陣風、風向)、天象 (日出/日落、月相)、降水 (類型、機率、量/QPF)、大氣狀況 (紫外線指數、濕度、雲量、雷雨機率) 和地理編碼位置地址。

位置和位置規則 (重要)：

使用 location 欄位指定要求天氣資料的位置。這個欄位是「oneof」結構，也就是說，您「只能」為下列三個位置子欄位中的「其中一個」提供值，確保天氣資料查詢結果準確無誤。

  1. 地理座標 (lat_lng)

    • 如果已取得確切的經緯度座標，請使用這個選項。
    • Example: {"location": {"lat_lng": {"latitude": 34.0522, "longitude": -118.2437}}} // Los Angeles

  2. 地點 ID (place_id)

    • 明確的字串 ID (Google 地圖地點 ID)。
    • 您可以透過 search_places 工具擷取 place_id。
    • Example: {"location": {"place_id": "ChIJLU7jZClu5kcR4PcOOO6p3I0"}} // Eiffel Tower

  3. 地址字串 (地址)

    • 需要明確的任意形式字串，才能進行地理編碼。
    • 城市和區域：一律要包含區域/國家/地區 (例如「英國倫敦」，而非「倫敦」)。
    • 街道地址：請提供完整地址 (例如「1600 Pennsylvania Ave NW, Washington, DC」)。
    • 郵遞區號：必須附上國家/地區名稱 (例如「90210, USA」，而非「90210」)。
    • 例如：{"location": {"address": "1600 Pennsylvania Ave NW, Washington, DC"}}

使用模式：

  • 目前天氣：僅提供 location。請勿指定 date 和 hour。

  • 每小時天氣預報：提供 location、date 和 hour (0 到 23)。可用於指定時間 (例如「下午 5 點」)，或「接下來幾小時」或「今天稍晚」等字詞。如果使用者指定分鐘，則會四捨五入至最接近的小時。系統不支援超過 120 小時的每小時天氣預報。系統最多支援過去 24 小時的每小時天氣記錄。

  • 每日預報：提供 location 和 date。請勿指定 hour。用於一般日期要求 (例如「明天的天氣」、「週五的天氣」、「12 月 25 日的天氣」)。如果情境中沒有今天的日期，請向使用者確認。系統不支援超過 10 天的每日天氣預報 (包括今天)。不支援歷史天氣資訊。

參數限制：

  • 時區：所有 date 和 hour 輸入內容都必須以地點的當地時區為準，而非使用者的時區。
  • 日期格式：輸入內容必須以 {year, month, day} 個整數分隔。
  • 單位：預設為 METRIC。如果使用者暗示或明確要求使用美國標準，請將 units_system 設為 IMPERIAL (華氏/英里)。

  • 如有 attribution 欄位資訊，系統必須使用該資訊將基礎輸出內容歸因於來源。
compute_routes

計算指定起點和目的地之間的路線。支援的交通方式：開車 (預設)、步行。

輸入規定 (重要)：必須提供來源和目的地。請使用下列其中一種方法，在各自的欄位中提供這些資訊：

  • address: (字串，例如「Eiffel Tower, Paris」)。注意：輸入的地址越精細或具體，結果就越準確。

  • lat_lng: (物件，{"latitude": number, "longitude": number})

  • place_id: (字串，例如「ChIJOwE_Id1w5EAR4Q27FkL6T_0」) 注意：這個 ID 可從 search_places 工具取得。允許使用任何輸入類型組合 (例如：以地址做為起點，以 lat_lng 做為目的地)。如果缺少來源或目的地，請務必先向使用者確認，再嘗試呼叫工具。

工具呼叫範例：{"origin":{"address":"Eiffel Tower"},"destination":{"place_id":"ChIJt_5xIthw5EARoJ71mGq7t74"},"travel_mode":"DRIVE"}

  • 如有 attribution 欄位資訊，系統必須使用該資訊將基礎輸出內容歸因於來源。
resolve_names

將特定地點查詢 (地標名稱或確切地址) 的批次清單解析為標準的 Google 地圖地點 ID。

輸入規定 (重要)：

  1. queries (物件陣列 - 必填)：要解析的位置查詢清單。最多可指定 20 項查詢。

    • 每個查詢物件都必須具備：
      • text (字串 - 必填)：代表要解析的特定地點名稱或地址的文字查詢。
        • 示例：'Googleplex, Mountain View, CA'、'1600 Amphitheatre Pkwy, Mountain View, CA'、'Eiffel Tower, Paris'。

  2. location_bias (物件 - 選用)：使用這個物件，優先顯示特定地理區域附近的結果。

    • 格式： {"viewport": {"low": {"latitude": [value], "longitude": [value]}, "high": {"latitude": [value], "longitude": [value]}}}

  3. region_code (字串 - 選用)：使用者的 Unicode CLDR 區域代碼 (兩字母國家/地區代碼，例如 US、CA)，用於調整結果。

工具呼叫的指示：

  • 具體性 (重要)：查詢必須代表特定地點名稱或地址。不支援一般搜尋 (例如 'restaurants') 或連鎖店名稱 (例如 'Starbucks')。
  • 如果您打算叫用的下游工具已直接接受原始地址或地名字串，請勿呼叫這項工具。

儲存至 Google 地圖：

  • 回覆中包含 save_to_maps_url 欄位：單一 Google 地圖連結，內含所有成功解析的地點。
  • 如果使用者想在 Google 地圖中儲存、分享或開啟已解析的地點清單，請向使用者顯示這個連結。請勿自行建構這個連結。

錯誤處理 (重大)：

  • 這項工具可進行批次處理。要求可能會傳回「混合結果」(例如，部分查詢成功解析，其他查詢則失敗)。
  • 輸出 results 清單保證會與輸入 queries 索引建立 1:1 的對應關係。如果查詢失敗，results 清單中對應的索引會產生空白的 Result 訊息 (未設定 entity)。
  • 您必須檢查回應中的 failed_requests 對應欄位，找出失敗的特定查詢索引。failed_requests 的鍵代表要求中失敗查詢的索引 (以 0 為基準)。請勿因為部分失敗而假設整個批次呼叫失敗。
resolve_maps_urls

將 Google 地圖網址清單解析為標準 Google 地圖地點 ID。

何時呼叫這項工具 (重要)：

  • 當使用者提供一或多個 Google 地圖分享連結或網址 (例如「https://maps.app.goo.gl/...」或「https://www.google.com/maps/place/...」) 時，請使用這項工具。「https://www.google.com/maps/place/...」或「https://maps.google.com/...」，您需要擷取底層的標準地點 ID。
  • 單一批次要求最多可指定 20 個要解決的網址。

輸入規定 (重要)：

  • urls (字串陣列 - 必填)：要解析的 Google 地圖網址清單。每個網址都必須是有效的單一地點 Google 地圖網址。

儲存至 Google 地圖：

  • 回覆中包含 save_to_maps_url 欄位：單一 Google 地圖連結，內含所有成功解析的地點。
  • 如果使用者想在 Google 地圖中儲存、分享或開啟已解析的地點清單 (例如收集對話中分享的地點)，請向使用者提供這個連結。請勿自行建構這個連結。

錯誤處理 (重大)：

  • 這項工具可進行批次處理。要求可能會傳回「混合結果」(例如部分網址成功解析，其他網址則失敗)。
  • 輸出 entities 清單保證會與輸入 urls 索引建立 1:1 的對應關係。如果網址解析失敗，entities 清單中對應的索引會產生空白的 Entity 訊息 (未設定任何欄位)。
  • 您必須檢查回應中的 failed_requests 對應欄位，找出索引失敗的特定網址。failed_requests 的鍵代表要求中失敗網址的索引 (以 0 為基準)。請勿因為部分失敗而假設整個批次呼叫失敗。

取得 MCP 工具規格

如要取得 MCP 伺服器中所有工具的 MCP 工具規格，請使用 tools/list 方法。以下範例說明如何使用 curl 列出 MCP 伺服器中目前可用的所有工具及其規格。

Curl 要求 
curl --location 'https://mapstools.googleapis.com/mcp' \
--header 'content-type: application/json' \
--header 'accept: application/json, text/event-stream' \
--data '{
    "method": "tools/list",
    "jsonrpc": "2.0",
    "id": 1
}'