MCP Reference: mapstools.googleapis.com

这是 Maps Experience Agent Tools 提供的 MCP 服务器。该服务器为开发者提供了在 Google Maps Platform 之上构建 LLM 应用的工具。

Model Context Protocol (MCP) 服务器充当外部服务（为大语言模型 [LLM] 或 AI 应用提供上下文、数据或功能）与 LLM 或 AI 应用之间的代理。MCP 服务器将 AI 应用连接到数据库和 Web 服务等外部系统，并将这些系统的响应转换为 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 地区代码。此参数用于显示地点详情，例如特定于区域的地点名称（如果有）。根据适用法律，该参数可能会影响结果。

    • 格式：双字母国家/地区代码 (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)

    • 明确的字符串标识符（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 时间戳格式，并带有 UTC 偏移量，例如 '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"}

Instructions for Response:

  • 请求备选路线时，路线会按推荐程度从高到低排序。
  • 如果 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 索引一一对应。失败的查询将在 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 索引一一对应。网址解析失败会导致 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
}'