MCP Tools Reference: mapstools.googleapis.com

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

以下代码示例展示了如何使用 curl 调用 search_places 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": "search_places",
    "arguments": {
      // Provide these details according to the MCP tool specification.
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

输入架构

SearchText 的请求消息。

SearchTextRequest

JSON 表示法 
{
  "textQuery": string,
  "languageCode": string,
  "regionCode": string,
  "pageSize": integer,
  "includeExtendedDetails": boolean,

  // Union field _location_bias can be only one of the following:
  "locationBias": {
    object (LocationBias)
  }
  // End of list of possible types for union field _location_bias.
}
字段
textQuery

string

必需。文本查询。
languageCode

string

可选。请求返回摘要时使用的语言。如果语言代码未指定或无法识别，系统会返回摘要，并优先使用英语。

例如，“en”表示英语。

当前支持的语言列表：https://developers.google.com/maps/faq#languagesupport。
regionCode

string

可选。请求来源位置的 Unicode 国家/地区代码 (CLDR)。此参数用于显示地点详情，例如特定于区域的地点名称（如果有）。该参数可能会根据适用法律影响结果。

例如，"US" 表示美国。

如需了解详情，请参阅 https://www.unicode.org/cldr/charts/latest/supplemental/territory_language_information.html。

请注意，目前不支持 3 位数的地区代码。
pageSize

integer

可选。要返回的地点数量上限，最多 5 个。服务返回的值可能小于此值。该默认值为 5。
includeExtendedDetails

boolean

可选。在响应中包含扩展的地点详情。

当用户请求需要丰富的定性数据洞见、实时动态或专门的实体属性时，请将此字段设置为 true：- 定性评价、客户情绪和反馈。- 具体产品/服务，例如菜单项、菜品、特色美食、饮料或商家亮点。- 氛围、室内装饰、美学、环境或情调等定性描述。- 实时数据和专业设施规格、访客政策/提示、等待时间。

对于标准发现搜索（例如菜系、商店类型）、位置/地址查询、联系信息、营业时间和标准元数据/酒店设施，请保留 false（默认）。

启用此字段会导致延迟时间增加。

联合字段 _location_bias。

_location_bias 只能是下列其中一项：
locationBias

object (LocationBias)

一个可选区域，用于使搜索结果偏向该区域。如果 text_query 中有明确的位置，系统会使用该位置（而非此字段）来调整搜索结果。

LocationBias

JSON 表示法 
{
  "circle": {
    object (Circle)
  }
}
字段
circle

object (Circle)

可选。由中心点和半径定义的圆形。radius_meters 是可选设置，如果未设置，结果将偏向中心点。

圆形

JSON 表示法 
{
  "center": {
    object (LatLng)
  },

  // Union field _radius_meters can be only one of the following:
  "radiusMeters": number
  // End of list of possible types for union field _radius_meters.
}
字段
center

object (LatLng)

必需。圆形的中心点。

联合字段 _radius_meters。

_radius_meters 只能是下列其中一项：
radiusMeters

number

圆形的半径（以米为单位）。半径必须在 50,000 米以内。

LatLng

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

number

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

number

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

输出架构

SearchText 的响应消息。

SearchTextResponse

JSON 表示法 
{
  "places": [
    {
      object (PlaceView)
    }
  ],
  "summary": string,
  "contentToken": string
}
字段
places[]

object (PlaceView)

仅限输出。摘要中提及的地点列表。
summary

string

仅限输出。搜索结果的自然语言摘要。摘要可能包含从零开始的引用，例如“[0]”“[1]”“[2]”等。这些引用会映射到 places 字段中的相应地点。
contentToken

string

仅限输出。一个加密令牌，用于封装搜索上下文，并可传递给 Google 地图可视化渲染服务、SDK 或地图智能体 UI 工具包 (A2UI)，以便为返回的搜索结果显示交互式界面组件。

PlaceView

JSON 表示法 
{
  "place": string,
  "id": string,
  "googleMapsLinks": {
    object (GoogleMapsLinks)
  },
  "attribution": {
    object (Attribution)
  },

  // Union field _location can be only one of the following:
  "location": {
    object (LatLng)
  }
  // End of list of possible types for union field _location.
}
字段
place

string

底层地点的资源名称，格式为“places/{id}”。
id

string

底层地点的地点 ID。
googleMapsLinks

object (GoogleMapsLinks)

用于触发不同 Google 地图操作的链接。
attribution

object (Attribution)

与地点一起显示的必需提供方说明。

联合字段 _location。

_location 只能是下列其中一项：
location

object (LatLng)

此地点的位置。

LatLng

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

number

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

number

经度（以度为单位）。它必须在 [-180.0, +180.0] 范围内。
JSON 表示法 
{
  "directionsUrl": string,
  "placeUrl": string,
  "writeAReviewUrl": string,
  "reviewsUrl": string,
  "photosUrl": string
}
字段
directionsUrl

string

指向前往该地点的路线的链接。该链接仅填充目的地位置，并使用默认出行方式 DRIVE。
placeUrl

string

用于显示此地点的链接。
writeAReviewUrl

string

一个链接，用于在 Google 地图上为此地点撰写评价。
reviewsUrl

string

用于在 Google 地图上显示此地点评价的链接。
photosUrl

string

一个链接，用于在 Google 地图上显示此地点的照片。

归因

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

string

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

string

要链接到的归因网址。

工具注释

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

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

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

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