MCP Tools Reference: mapstools.googleapis.com

工具：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 字段（如有）将接地输出归因于来源。

以下代码示例展示了如何使用 curl 调用 compute_routes MCP 工具。

Curl 请求 
curl --location 'https://mapstools.googleapis.com/mcp' \
--header 'content-type: application/json' \
--header 'accept: application/json, text/event-stream' \
--data '{
  "method": "tools/call",
  "params": {
    "name": "compute_routes",
    "arguments": {
      // Provide these details according to the MCP tool specification.
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

输入架构

ComputeRoutesRequest。

ComputeRoutesRequest

JSON 表示法 
{
  "origin": {
    object (Waypoint)
  },
  "destination": {
    object (Waypoint)
  },
  "travelMode": enum (RouteTravelMode),
  "intermediateWaypoints": [
    {
      object (Waypoint)
    }
  ],
  "routingPreference": enum (RoutingPreference),
  "locationBias": {
    object (LatLng)
  },
  "includePolyline": boolean,
  "computeAlternativeRoutes": boolean,

  // Union field timing can be only one of the following:
  "departureTime": string,
  "arrivalTime": string
  // End of list of possible types for union field timing.
}
字段
origin

object (Waypoint)

必需。起点航点。
destination

object (Waypoint)

必需。目的地航点。
travelMode

enum (RouteTravelMode)

可选。指定交通方式。
intermediateWaypoints[]

object (Waypoint)

可选。出发地和目的地之间要按顺序经过的中间停靠点。最多支持 10 个中间航点。当 travel_mode 为 TRANSIT 时，不支持中间航点。
routingPreference

enum (RoutingPreference)

可选。确定如何使用路况数据来计算路线。当 travel_mode 为 WALK 或 BICYCLE 时，不支持 ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL。对于TRANSIT，它可启用实时公交数据，例如延误和取消。
locationBias

object (LatLng)

可选。搜索结果偏向的位置，例如，用于消除航点文本查询的歧义。
includePolyline

boolean

可选。是否在响应路线中包含编码多段线。默认为 false。如果设置为 true，则返回 Route.encoded_polyline。
computeAlternativeRoutes

boolean

可选。是否计算除推荐路线之外的备选路线。默认值为 false，在这种情况下，系统只会返回推荐路线。如果设置为 true，系统会返回最多所有可用路线，但并非每个请求都有备选路线。
联合字段 timing。指定何时从起点出发或何时到达最终航点。如果未指定，则默认为当前时间出发。对于 TRANSIT，时间必须最多是过去 7 天，最长是未来 100 天。对于其他出行方式，时间不得早于当前时间，且不得晚于当前时间 365 天。timing 只能是下列其中一项：
departureTime

string (Timestamp format)

可选。表示应根据出发时间计算路线。

采用 RFC 3339 标准，生成的输出将始终进行 Z 规范化（即转换为 UTC 零时区格式并在末尾附加 Z），并使用 0、3、6 或 9 个小数位。不进行“Z”归一化处理的偏差时间也是可以接受的。示例："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。
arrivalTime

string (Timestamp format)

可选。表示应根据到达时间计算路线。

采用 RFC 3339 标准，生成的输出将始终进行 Z 规范化（即转换为 UTC 零时区格式并在末尾附加 Z），并使用 0、3、6 或 9 个小数位。不进行“Z”归一化处理的偏差时间也是可以接受的。示例："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。

时间戳

JSON 表示法 
{
  "seconds": string,
  "nanos": integer
}
字段
seconds

string (int64 format)

表示世界协调时间 (UTC) 的秒数（从 Unix 纪元 1970-01-01T00:00:00Z 开始算起）。必须介于 -62135596800 到 253402300799 之间（含边界值，对应于 0001-01-01T00:00:00Z 到 9999-12-31T23:59:59Z）。
nanos

integer

秒数的非负小数部分（以纳秒为单位）。此字段是时长的纳秒部分，而不是秒的替代。对于含小数部分的负秒数，仍必须包含按时间递升的非负纳秒值。必须在 0 到 999,999,999 之间（含边界值）。

航点

JSON 表示法 
{

  // Union field location_type can be only one of the following:
  "latLng": {
    object (LatLng)
  },
  "placeId": string,
  "address": string
  // End of list of possible types for union field location_type.
}
字段
联合字段 location_type。表示位置的不同方式。location_type 只能是下列其中一项：
latLng

object (LatLng)

使用地理坐标指定的点。
placeId

string

与航点关联的地点 ID。
address

string

人类可读地址或 Plus Code。如需了解详情，请参阅 https://plus.codes。

LatLng

JSON 表示法 
{
  "latitude": number,
  "longitude": number
}
字段
latitude

number

纬度（以度为单位）。它必须在 [-90.0, +90.0] 范围内。
longitude

number

经度（以度为单位）。它必须在 [-180.0, +180.0] 范围内。

RouteTravelMode

一组用于指定出行方式的值。

枚举
ROUTE_TRAVEL_MODE_UNSPECIFIED 未指定出行方式。默认为 DRIVE。
DRIVE 乘轿车出行。
WALK 步行出行。注意：WALK路线功能目前处于 Beta 版阶段，有时可能无法提供清晰的人行道或步行路线。对于应用中显示的所有步行路线，您都必须向用户显示此警告。
BICYCLE 骑自行车出行。
TRANSIT 乘坐公共交通工具出行。

RoutingPreference

一组值，用于指定计算路线时要考虑的因素。

枚举
ROUTING_PREFERENCE_UNSPECIFIED 未指定路由偏好设置。默认为 ROUTING_PREFERENCE_TRAFFIC_UNAWARE。
ROUTING_PREFERENCE_TRAFFIC_UNAWARE 计算路线时不考虑实时路况信息。适用于路况信息不重要或不适用的情况。使用此值可实现最低延迟。
ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL

在有路况数据的情况下，计算路线时会考虑实时路况。对于TRANSIT，系统会使用实时公交数据（例如延误和取消信息，如有）。

此值会触发 Pro 层级，并产生更高的结算费用和延迟时间。此功能仅面向列入许可清单的客户提供。如果未列入许可清单，请求将回退到 ROUTING_PREFERENCE_TRAFFIC_UNAWARE。

输出架构

ComputeRoutesResponse。

ComputeRoutesResponse

JSON 表示法 
{
  "routes": [
    {
      object (Route)
    }
  ]
}
字段
routes[]

object (Route)

包含所请求的出发地和目的地之间的路线，按推荐程度从高到低排序。除非 ComputeRoutesRequest.compute_alternative_routes 设置为 true，否则系统只会返回一条路线。

路由

JSON 表示法 
{
  "distanceMeters": integer,
  "duration": string,
  "attribution": {
    object (Attribution)
  },
  "encodedPolyline": string,
  "retrievalToken": string
}
字段
distanceMeters

integer

路线的行程距离（以米为单位）。
duration

string (Duration format)

沿路线导航所需的时间。

该时长以秒为单位，最多包含九个小数位，以“s”结尾。示例："3.5s"。
attribution

object (Attribution)

与路线一起显示的必需属性。
encodedPolyline

string

路线的编码多段线。请参阅 https://developers.google.com/maps/documentation/utilities/polylinealgorithm
retrievalToken

string

一个令牌，可用于在下游工具（例如 SearchAlongRoute）中检索此特定路线。有效期为 10 分钟。

时长

JSON 表示法 
{
  "seconds": string,
  "nanos": integer
}
字段
seconds

string (int64 format)

时间跨度的带符号秒数。必须介于 -315,576,000,000 到 +315,576,000,000 之间（含边界值）。注意：这些边界的计算公式为：60 秒/分钟 * 60 分钟/小时 * 24 小时/天 * 365.25 天/年 * 10000 年
nanos

integer

时间跨度的秒数的有符号小数部分（以纳秒为单位）。小于 1 秒的时长用 0 seconds 字段和正或负 nanos 字段表示。对于一秒或更长的时长，nanos 字段的非零值必须与 seconds 字段具有相同的符号。必须介于 -999,999,999 到 +999,999,999 之间（含边界值）。

归因

JSON 表示法 
{
  "title": string,
  "url": string
}
字段
title

string

要为提供方显示的标题。
url

string

要链接到的归因网址。

工具注释

工具注解会发送到 MCP 客户端，用于描述给定工具的基本风险。大多数客户端会将这些提示视为不可信，但可用于决定何时向用户发送确认提示。

除了标题字符串之外，还定义了以下布尔值提示：

  • readOnlyHint：如果为 true，则该工具不会修改其环境。默认值：false。
  • destructiveHint：如果为 true，则该工具可以执行破坏性操作。如果为 false，则该工具只能执行添加操作。默认值：true。
  • idempotentHint：如果为 true，则使用相同参数重复调用该工具不会对其环境产生额外影响。默认值：false。
  • openWorldHint：如果为 true，则该工具可以与外部实体的“开放世界”进行交互。如果为 false，则该工具只能与内部实体交互。例如，网页搜索工具是开放世界，而记忆工具不是开放世界。

破坏性提示：❌ | 幂等性提示：❌ | 只读提示：✅ | 开放世界提示：❌