MCP Tools Reference: mapstools.googleapis.com

Referência das ferramentas do MCP:

Este documento descreve os endpoints da API REST voltados para o público externo usados para invocar as ferramentas do Protocolo de Contexto de Modelo (MCP) remoto do Google. Essa API atua como um proxy seguro entre um cliente HTTP externo (como curl ou um serviço da Web) e o servidor MCP interno.

Receber especificações da ferramenta MCP

Para receber as especificações de todas as ferramentas em um servidor MCP, use o método "tools/list". O exemplo a seguir demonstra como usar curl para listar todas as ferramentas e especificações disponíveis no servidor MCP.

Solicitação 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
}'

Ferramenta: search_places

Chame essa ferramenta quando a solicitação do usuário for encontrar lugares, empresas, endereços, locais, pontos de interesse ou qualquer outra pesquisa relacionada ao Google Maps.

Requisitos de entrada (CRÍTICO):

  1. text_query (string - OBRIGATÓRIO): a consulta de pesquisa principal. Isso precisa definir claramente o que o usuário está procurando.

    • Exemplos:'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'.
    • Para detalhes de um lugar específico:inclua o atributo solicitado (por exemplo, 'Google Store Mountain View opening hours', 'SF MoMa phone number', 'Shoreline Park Mountain View address').

  2. location_bias (objeto - OPCIONAL): use para priorizar resultados próximos a uma área geográfica específica.

    • Formato: {"location_bias": {"circle": {"center": {"latitude": [value], "longitude": [value]}, "radius_meters": [value (optional)]}}}
    • Uso:
      • Para favorecer um raio de 5 km:{"location_bias": {"circle": {"center": {"latitude": 34.052235, "longitude": -118.243683}, "radius_meters": 5000}}}
      • Para favorecer fortemente o ponto central:{"location_bias": {"circle": {"center": {"latitude": 34.052235, "longitude": -118.243683}}}} (omitindo radius_meters).

  3. language_code (string - OPCIONAL): o idioma em que o resumo dos resultados da pesquisa será mostrado.

    • Formato:um código de idioma de duas letras (ISO 639-1), opcionalmente seguido por um sublinhado e um código de país de duas letras (ISO 3166-1 alfa-2), por exemplo, en, ja, en_US, zh_CN, es_MX. Se o código de idioma não for fornecido, os resultados serão em inglês.

  4. region_code (string - OPCIONAL): o código regional CLDR Unicode do usuário. Esse parâmetro é usado para mostrar os detalhes do lugar, como o nome específico da região, se disponível. O parâmetro pode afetar os resultados com base na legislação aplicável.

    • Formato:um código de país com duas letras (ISO 3166-1 alfa-2), por exemplo, US, CA.

Instruções para chamada de função:

  • Informações de local (CRÍTICO): a pesquisa precisa conter informações de local suficientes. Se o local for ambíguo (por exemplo, apenas "pizzarias"), você precisa especificar no text_query (por exemplo, "pizzarias em Nova York") ou use o parâmetro location_bias. Inclua o nome da cidade, do estado/província e da região/país, se necessário, para evitar ambiguidade.

  • Sempre forneça o text_query mais específico e contextual possível.

  • Use location_bias somente se as coordenadas forem fornecidas explicitamente ou se for apropriado e necessário inferir um local do contexto conhecido de um usuário para ter resultados melhores.

Os exemplos a seguir demonstram como usar curl para invocar a ferramenta search_places do MCP.

Solicitação 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: {
      // please fill these details according to tools MCP specification
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

Ferramenta: lookup_weather

Fornece condições atuais e previsões por hora e diárias para qualquer local. Use essa ferramenta para todas as consultas relacionadas ao clima.

Dados específicos disponíveis:temperatura (atual, sensação térmica, máxima/mínima, índice de calor), vento (velocidade, rajadas, direção), eventos celestes (nascer/pôr do sol, fase da lua), precipitação (tipo, probabilidade, quantidade/QPF), condições atmosféricas (índice UV, umidade, cobertura de nuvens, probabilidade de tempestade) e endereço do local geocodificado.

Requisitos de entrada (CRÍTICO):

  • Condições atuais:exigem apenas um local (por exemplo, cidade ou endereço). Não especifique uma data ou hora.

  • Previsões de hora em hora:exigem um local e uma hora (0 a 23). Use se o usuário perguntar sobre a previsão do tempo em um horário específico ou usar termos como "próximas horas" ou "mais tarde hoje".

  • Previsões diárias:exigem um local e uma data completa.

Tratamento de datas (CRÍTICO): as datas e horas fornecidas pelo usuário PRECISAM ser informadas no fuso horário local do local solicitado. As datas PRECISAM ser divididas em parâmetros inteiros separados: ano, mês e dia. O formato obrigatório para esses parâmetros é: {"year": , "month": , "day": }

Os exemplos a seguir demonstram como usar curl para invocar a ferramenta lookup_weather do MCP.

Solicitação 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": lookup_weather,
    arguments: {
      // please fill these details according to tools MCP specification
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

Ferramenta: compute_routes

Calcula um trajeto entre uma origem e um destino especificados. Modos de viagem aceitos:CARRO (padrão), A PÉ.

Requisitos de entrada (CRÍTICO): exige origem e destino. Cada um deles precisa ser fornecido usando um dos seguintes métodos, aninhado no respectivo campo:

  • address: (string, por exemplo, 'Torre Eiffel, Paris'). Observação: quanto mais granular ou específico for o endereço de entrada, melhores serão os resultados.

  • lat_lng:: (objeto, {"latitude": número, "longitude": número})

  • place_id:: (string, por exemplo, 'ChIJOwE_Id1w5EAR4Q27FkL6T_0') Observação: esse ID pode ser obtido na ferramenta search_places. Qualquer combinação de tipos de entrada é permitida (por exemplo, origem por endereço, destino por lat_lng). Se a origem ou o destino estiverem faltando, você PRECISA pedir esclarecimentos ao usuário antes de tentar chamar a ferramenta.

Exemplo de chamada de função: {"origin":{"address":"Eiffel Tower"},"destination":{"place_id":"ChIJt_5xIthw5EARoJ71mGq7t74"},"travel_mode":"DRIVE"}

Os exemplos a seguir demonstram como usar curl para invocar a ferramenta MCP compute_routes.

Solicitação 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: {
      // please fill these details according to tools MCP specification
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'