MCP Reference: mapstools.googleapis.com

這是 Maps Experience Agent Tools 提供的 MCP 伺服器。伺服器提供工具，可讓開發人員在 Google Maps Platform 上建構 LLM 應用程式。

Model Context Protocol (MCP) 伺服器是 Proxy，可為大型語言模型 (LLM) 或 AI 應用程式提供脈絡、資料或功能。MCP 伺服器可將 AI 應用程式連結至資料庫和網路服務等外部系統，並將系統回覆轉換成 AI 應用程式可理解的格式。

伺服器設定

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

伺服器端點

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

Maps Experience Agent Tools 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 區域代碼。這個參數用於顯示 Place Details，例如特定區域的地點名稱 (如有)。這項參數可能會根據適用法律影響結果。

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

工具呼叫操作說明：

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

  • 請務必盡可能提供最明確且符合情境的 text_query。

  • 只有在明確提供座標，或從使用者已知情境推論位置是適當且必要時，才使用 location_bias，以取得更準確的結果。

  • 建立基準的輸出內容必須註明來源，並盡可能使用 attribution 欄位中的資訊。
lookup_weather

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

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

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

您可以使用 location 欄位指定要查詢天氣資料的地點。這個欄位是「oneof」結構，也就是說，您「必須」只為下列三個位置子欄位中的「一個」提供值，才能確保天氣資料查詢準確。

  1. 地理座標 (lat_lng)

    • 當您取得確切的經緯度座標時，請使用這個方法。
    • 範例：{"location": {"lat_lng": {"latitude": 34.0522, "longitude": -118.2437}}} // 洛杉磯

  2. 地點 ID (place_id)

    • 明確的字串 ID (Google 地圖地點 ID)。
    • place_id 可透過 search_places 工具擷取。
    • 示例：{"location": {"place_id": "ChIJLU7jZClu5kcR4PcOOO6p3I0"}} // 艾菲爾鐵塔

  3. 地址字串 (address)

    • 自由形式的字串，需要明確指定地理編碼。
    • 城市和地區：一律包含地區/國家/地區 (例如「英國倫敦」，而非「倫敦」)。
    • 街道地址：提供完整地址 (例如「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

計算起點和目的地之間的路線，可選擇是否經過中途停靠點。傳回每條路線的距離和時間長度。

輸入內容規定 (重要)：

  1. origin 和 destination (物件 - 必填)：必須使用下列其中一項提供：

    • address (字串，例如 'Eiffel Tower, Paris')。系統會直接解析具名地點、地標和商家，因此請勿先呼叫 search_places，只為了對路線控點進行地理編碼。請加入使用者提及的任何城市、地區或國家/地區。
    • lat_lng (物件，{"latitude": number, "longitude": number})。
    • place_id (字串，例如 'ChIJOwE_Id1w5EAR4Q27FkL6T_0')，例如來自 search_places。

  2. intermediate_waypoints (物件陣列 - 選用)：從起點到目的地之間，最多可依序經過 10 個停靠點。格式與 origin 相同。不支援TRANSIT。只納入使用者要求的停靠站。

  3. travel_mode (列舉 - 選用)： DRIVE (預設)、WALK、BICYCLE 或 TRANSIT。

  4. 時間 (選用，最多設定一個)：RFC 3339 時間戳記，包含世界標準時間時差，例如 '2026-09-19T08:00:00-07:00'。預設為立即出發。TRANSIT 的時間最多可設為過去 7 天或未來 100 天。如果是其他模式，時間最多可設為未來 365 天，且不得設為過去。

    • departure_time：當使用者說出出發時間時使用 (例如「明天早上 8 點」)。
    • arrival_time：當使用者指定抵達時間時使用 (例如「上午 9 點前抵達」)。

  5. routing_preference (列舉 - 選用)：

    • ROUTING_PREFERENCE_TRAFFIC_UNAWARE (預設)：忽略即時路況、事故和封路資訊。延遲時間最短。
    • ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL：在可用時使用即時路況。不支援WALK或BICYCLE。只有在使用者詢問路況、塞車情形或根據路況調整的預計到達時間時，才設定這個值。費用和延遲時間較高。

  6. location_bias (物件 - 選用)： {"latitude": number, "longitude": number}，用於區分路線控點地址中的地點名稱。如果名稱不明確 (例如「Springfield」)，且使用者未提供區域，請保留 address 中提供的名稱，並將 location_bias 設為預期區域，而不是猜測區域。

  7. compute_alternative_routes (布林值 - 選用)：只有在使用者要求路線選項或替代路線時，才設為 true。預設值為 false，只會傳回建議路線。

  8. include_polyline (布林值 - 選用)：只有在需要路線幾何圖形 (encoded_polyline) 時，才設為 true。預設為 false。

工具呼叫操作說明：

  • 如果缺少出發地或目的地，請務必先要求使用者提供明確資訊，再呼叫工具。
  • 如果是「A 距離 B 有多遠？」這類問題，請將 B 設為 origin，A 設為 destination。

工具呼叫範例：{"origin":{"address":"Eiffel Tower"},"destination":{"place_id":"ChIJt_5xIthw5EARoJ71mGq7t74"},"intermediate_waypoints":[{"address":"Louvre Museum"}],"travel_mode":"DRIVE","departure_time":"2026-09-19T08:00:00+02:00"}

回覆指示：

  • 要求替代路線時，系統會依推薦程度由高至低排序。
  • 如果 routes 為空白，請告知使用者找不到路線。請勿猜測路徑。
  • 僅陳述工具傳回的事實。請勿捏造即時路線、大眾運輸路線、車站、月台或轉乘資訊。
  • 有基準的輸出內容必須使用各路徑的 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://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
}'