HasData Google Maps MCP Server

Servidor MCP do Google Maps

Um servidor de Model Context Protocol (MCP) hospedado que dá ao Claude, Cursor, Windsurf e qualquer outro cliente MCP seis ferramentas somente leitura do Google Maps. Pesquise lugares, leia um lugar por completo, obtenha suas avaliações, fotos e posts, e percorra o histórico de um único avaliador, tudo como JSON estruturado, sem projeto no Google Cloud e sem precisar ativar cobrança.

https://mcp.hasdata.com/api/mcp?apis=google_maps

Conteúdo

• O que você precisa
• Início rápido
• Exemplos de prompts
• Ferramentas
• Erros e caminhos de falha
• Preços, camada gratuita e limites
• Seleção de ferramentas
• Como se compara
• Perguntas frequentes
• Links do HasData
• Desenvolvimento
• Contribuição
• Licença

O que você precisa

Um cliente MCP que fale HTTP transmissível com cabeçalhos personalizados. Uma chave de API do HasData do painel, gratuita para criar sem cartão, e o teste cobre cerca de 200 chamadas na taxa de 5 créditos. Nada mais. Este é um servidor remoto, então o caminho mais simples é uma URL e um cabeçalho, sem contêiner para executar e sem projeto no Google Cloud ou chave de API em nenhum lugar do fluxo. Um cliente somente stdio pode usar o inicializador @hasdata/google-maps-mcp (npm) ou hasdata-google-maps-mcp (PyPI).

Início rápido

A URL do servidor é a mesma para todos os clientes. Nós a executamos na prática no Claude Code e no Claude Desktop. Os outros blocos seguem o formato documentado de cada cliente para um servidor remoto.

Clientes com suporte a OAuth podem adicionar a mesma URL como um conector e entrar sem colocar uma chave em um arquivo de configuração.

claude mcp add --transport http google-maps "https://mcp.hasdata.com/api/mcp?apis=google_maps" \
  --header "x-api-key: HASDATA_API_KEY"

{
  "mcpServers": {
    "google-maps": {
      "command": "npx",
      "args": ["-y", "@hasdata/google-maps-mcp"],
      "env": { "HASDATA_API_KEY": "YOUR_KEY" }
    }
  }
}

{
  "mcpServers": {
    "google-maps": {
      "command": "uvx",
      "args": ["hasdata-google-maps-mcp"],
      "env": { "HASDATA_API_KEY": "YOUR_KEY" }
    }
  }
}

{
  "mcpServers": {
    "google-maps": {
      "url": "https://mcp.hasdata.com/api/mcp?apis=google_maps",
      "headers": { "x-api-key": "HASDATA_API_KEY" }
    }
  }
}

{
  "mcpServers": {
    "google-maps": {
      "serverUrl": "https://mcp.hasdata.com/api/mcp?apis=google_maps",
      "headers": { "x-api-key": "HASDATA_API_KEY" }
    }
  }
}

{
  "mcpServers": {
    "google-maps": {
      "url": "https://mcp.hasdata.com/api/mcp?apis=google_maps",
      "type": "streamableHttp",
      "headers": { "x-api-key": "HASDATA_API_KEY" },
      "disabled": false
    }
  }
}

{
  "servers": {
    "google-maps": {
      "type": "http",
      "url": "https://mcp.hasdata.com/api/mcp?apis=google_maps",
      "headers": { "x-api-key": "HASDATA_API_KEY" }
    }
  }
}

{
  "mcpServers": {
    "google-maps": {
      "httpUrl": "https://mcp.hasdata.com/api/mcp?apis=google_maps",
      "headers": { "x-api-key": "HASDATA_API_KEY" }
    }
  }
}

Exemplos de prompts

Cada um destes é uma chamada de ferramenta, a menos que a contagem diga o contrário.

Pesquise no Google Maps por café perto do centro de Seattle e me dê os dez primeiros com sua avaliação, número de avaliações e site.

Uma chamada, 5 créditos. A pesquisa retorna os lugares com placeId e dataId já anexados, e os acompanhamentos abaixo não precisam de etapa de busca.

Obtenha os detalhes completos de ChIJAb0KE0RrkFQRuI4X0By5Mcw: horários, opções de serviço, nível de preço e o link do cardápio.

Uma chamada, 5 créditos.

Leia as avaliações mais recentes daquele lugar, ordenadas das mais novas para as mais antigas, e me diga quais tópicos aparecem com mais frequência.

Uma chamada, 5 créditos. A resposta traz os agrupamentos de tópicos do próprio Google com uma contagem de menções cada, e a classificação está nos dados.

Pegue o autor da melhor avaliação e liste todos os outros lugares que ele avaliou, com a nota que ele deixou.

Uma chamada, 5 créditos. Uma avaliação carrega o contributorId do autor, que é exatamente o que a ferramenta de contribuidor aceita.

Obtenha o feed de fotos daquele lugar e os posts recentes do negócio.

Duas chamadas. Fotos custam 5 créditos, posts custam 10.

Duas coisas tornam essas cadeias baratas. A pesquisa devolve placeId e dataId em cada resultado, e as chamadas de detalhes, avaliações, fotos e posts não precisam de etapa separada de resolução. E uma avaliação carrega o contributorId do autor, o que transforma "quem deixou esta avaliação" em um salto de uma chamada para todo o histórico dessa pessoa.

Ferramentas

Seis ferramentas, todas somente leitura. As amostras abaixo foram reduzidas de chamadas reais, e os números nelas mudam conforme os lugares ganham avaliações. Leia-as como formatos. O nome de cada ferramenta leva à referência do endpoint.

As amostras são o payload, não a resposta inteira. Um resultado tools/call carrega um bloco de texto, e esse texto é ele próprio JSON contendo url, status, text e json, com os dados extraídos sob json. De uma resposta JSON-RPC bruta, o caminho é result.content[0].text, analisado, depois .json. Um cliente de chat desembrulha isso para você, e código que fala diretamente com o endpoint não faz isso.

Quatro das ferramentas aceitam um lugar por placeId ou dataId. A pesquisa retorna ambos em cada resultado. O fluxo usual é uma pesquisa seguida de chamadas de detalhes, avaliações, fotos ou posts que reutilizam o id que você manteve.

Pesquisar no Google Maps

hasdata_google_maps_search_performMapSearch

Lugares para uma consulta, classificados como o Google Maps os classifica.

Cada resultado carrega position, title, placeId, dataId, address, gpsCoordinates, rating, reviews, type, types, price, website, thumbnail, openState, workingHours, serviceOptions e, onde o Google mostra um, um link menu.

A localização vive em ll, não na consulta. Coloque o centro do mapa e o zoom lá, porque "café" sozinho retorna onde quer que o Google decida que você está. O dígito do zoom amplia ou estreita a área da qual os resultados são extraídos.

{
  "localResults": [
    {
      "position": 1,
      "title": "Howdy Y'all Coffee (Central Library)",
      "placeId": "ChIJAb0KE0RrkFQRuI4X0By5Mcw",
      "dataId": "0x54906b44130abd01:0xcc31b91cd0178eb8",
      "address": "1000 4th Ave Fl 3, Seattle, WA 98104",
      "rating": 4.9,
      "reviews": 117,
      "type": "Coffee shop",
      "website": "https://howdyyallcoffee.com/",
      "workingHours": {
        "timezone": "America/Los_Angeles",
        "days": [ { "day": "Friday", "time": "10 AM–4 PM" } ]
      }
    }
  ]
}

Obter detalhes do lugar

hasdata_google_maps_place_getPlaceDetails

Um lugar por completo por placeId.

Retorna um único objeto placeResults com os mesmos campos que um resultado de pesquisa carrega, além de um array images. É a maneira de obter o registro completo de um lugar sem executar uma pesquisa que você não precisa.

Obter avaliações do lugar

hasdata_google_maps_reviews_getMapReviews

O feed de avaliações de um lugar, página por página.

Retorna placeInfo, um array topics, um array reviews e pagination. Cada avaliação carrega reviewId, rating, snippet, date, isoDate, link, images, um objeto user e, onde o proprietário respondeu, um response.

topics é o agrupamento do próprio Google do que as avaliações mencionam, cada um com um keyword e uma contagem mentions, e os temas vêm pré-contados em vez de exigir que você leia cada avaliação. Alimente o id de um tópico de volta como topicId para ler apenas as avaliações que o mencionam.

O user de cada avaliação carrega um contributorId. Essa é a entrada que a ferramenta de contribuidor aceita, então "quem escreveu isto" está a uma chamada de distância de "tudo o que escreveram".

{
  "placeInfo": { "title": "Howdy Y'all Coffee (Central Library)", "rating": 4.9, "reviews": 117 },
  "topics": [
    { "keyword": "earl grey matcha", "mentions": 26, "id": "bew1w_KAk5U" },
    { "keyword": "friendly baristas", "mentions": 17, "id": "FOw-91tYieQ" }
  ],
  "reviews": [
    {
      "reviewId": "…",
      "rating": 5,
      "snippet": "…",
      "isoDate": "2026-07-06T19:49:00.657Z",
      "user": { "name": "Angela Li", "contributorId": "106033685843245983748" },
      "response": { "isoDate": "2026-07-07T04:44:34.000Z", "snippet": "Thank you!! 🥺☺️" }
    }
  ],
  "pagination": { "nextPageToken": "…" }
}

Obter avaliações de um contribuidor

hasdata_google_maps_contributor_reviews_getMapReviews

Todas as avaliações que uma pessoa escreveu, em todos os lugares que ela avaliou.

Retorna um objeto contributor com name, level, points e um detalhamento contributions, e um array reviews onde cada entrada carrega seu próprio placeInfo, e você vê sobre qual lugar cada avaliação é sem uma segunda busca. Esta é a ferramenta por trás do trabalho de credibilidade de avaliador e rede de avaliações que o feed de avaliações sozinho não consegue fazer. Ela lê o histórico público de avaliações de uma pessoa, então use os resultados dentro dos termos do Google e da lei que se aplica a você.

Obter fotos do lugar

hasdata_google_maps_photos_getMapPhotos

O feed de fotos de um lugar.

Retorna um array categories (All, Latest, Videos, Menu e específicos do lugar), um array photos onde cada entrada tem URLs image e thumbnail, e pagination.

Obter posts do lugar

hasdata_google_maps_posts_getMapPosts

Os posts e atualizações do próprio negócio em sua listagem do Google.

Retorna um array posts.

A maioria dos lugares não posta nada, então um array posts vazio é o caso comum. Leia o comprimento antes de assumir que um post está lá.

Erros e caminhos de falha

Seu cliente quase nunca vê um código de erro HTTP vindo de uma chamada de ferramenta. A camada MCP responde com 200 e coloca a falha dentro do resultado, com isError definido como true e o motivo como texto. O agente lê uma mensagem onde você poderia esperar uma linha de status.

Uma chave errada aparece como saída de ferramenta, não como uma conexão falha. Listar ferramentas aceita qualquer chave não vazia, e o cliente completa o handshake e mostra verde. A primeira chamada de ferramenta então retorna com isError: true e o texto HasData API error: 401 Unauthorized. Fique atento a essa string, porque nada antes no fluxo reporta o problema.

O único erro HTTP real é uma chave ausente. A autorização roda antes de qualquer ferramenta, e a própria conexão falha com 401.

Um argumento que quebra o schema é rejeitado antes de virar uma requisição. Uma busca sem q retorna com isError: true e o texto MCP error -32602: Input validation error, nomeando o campo. Nada é buscado e nada é cobrado.

Uma chamada de avaliação, foto ou post precisa de um lugar. Essas três aceitam placeId ou dataId, e enviar nenhum dos dois retorna 422 nomeando ambos os campos, porque o requisito é condicional e o schema não consegue expressá-lo como uma lista obrigatória simples. Passe um deles.

Um id de lugar que não resolve é um erro limpo, não dados vazios. Ele retorna isError: true com HasData API error: 400 Bad Request e requestMetadata.status definidos como error. Teste a flag em vez do tamanho do array.

posts vazio é dado real. A maioria das listagens não tem posts, então a chamada é bem-sucedida com status ok e um array vazio. O lugar simplesmente não tem nada postado.

Resultados que carregam dados também carregam um requestMetadata.id que vale citar no suporte, além de links html e json para o artefato armazenado daquela chamada exata.

Preços, camada gratuita e limites

Busca, detalhes de lugar, avaliações, avaliações de contribuidores e fotos custam 5 créditos por chamada bem-sucedida. Posts custam 10. O tamanho da resposta não muda o preço. Uma página cheia de avaliações custa o mesmo que uma página com uma só.

O teste gratuito é 1.000 créditos por 30 dias sem cartão, o que dá 200 chamadas na taxa de 5 créditos. Depois disso, uma conta ativa continua recebendo 100 créditos recarregados diariamente sempre que o saldo cair abaixo de 100, então um agente de baixo volume roda na camada gratuita indefinidamente.

Planos pagos começam em US$ 49 por mês para 200.000 créditos, o que dá 40.000 chamadas de cinco créditos. O preço por crédito cai com o volume, e os números atuais estão na página de preços.

Seu plano também define a concorrência. O teste gratuito permite 1 requisição por vez, Startup 15, Business 30, Growth 50, e os planos de alto volume vão de 200 a 1.500. Concorrência é o único limite. Não há um teto separado de requisições por minuto, e o teste não é limitado ou reduzido de nenhuma outra forma. Trate o caso de estouro defensivamente em qualquer coisa não supervisionada, porque um agente que se espalha por vários lugares vai atingir o teto antes de você.

Paginção custa uma chamada a cada vez. Avaliações vêm cerca de dez por página, então cem avaliações são aproximadamente dez chamadas e 50 créditos, enquanto fotos vêm vinte por página. O teste vai longe antes de você sentir o impacto.

Seleção de ferramentas

?apis=google_maps expõe exatamente essas seis ferramentas. O parâmetro aceita uma lista, e ?apis=google_maps,google_serp adiciona a busca do Google junto com as ferramentas de mapas. Remova o parâmetro e você obtém tudo o que a HasData expõe, que atualmente são 57 ferramentas.

Uma lista enxuta costuma ser o melhor padrão. Um modelo escolhendo entre seis ferramentas acerta com mais frequência do que um escolhendo entre cinquenta e sete, e as próprias descrições das ferramentas custam contexto a cada turno.

Como se compara

Quase todos os outros servidores MCP do Google Maps envolvem a plataforma oficial Google Maps Platform, e essa é a escolha real a se pesar.

Esses servidores chamam as APIs Places, Routes e Geocoding com suas próprias credenciais do Google Cloud. Para rodar um deles, você cria um projeto no Google Cloud, ativa o faturamento com um cartão, liga cada API e gerencia uma chave e suas cotas. Essa é a ferramenta certa quando você quer rotas, geocodificação e validação de endereço, que este servidor não faz.

Este servidor lê o que o Google Maps mostra a um visitante e retorna isso parseado. Não há projeto no Google Cloud, nem faturamento para ativar, nem cota por API para gerenciar. Ele também alcança dados que a API Places não entrega: o feed completo de avaliações em vez de uma pequena amostra fixa, o histórico completo de um único avaliador, o feed de fotos e os posts do negócio.

A decisão se resume a duas linhas. Se você precisa de direções ou transformar um endereço em coordenadas, este servidor não pode ajudar e a Platform pode. Se você precisa das avaliações além das primeiras, ou de quem é um avaliador em todos os lugares que ele avaliou, a Platform não pode ajudar e este pode.

O que este servidor não faz. Sem rotas, sem geocodificação, sem validação de endereço, sem matriz de distâncias e nada que escreva. Ele lê o mapa.

FAQ

O que é um servidor MCP do Google Maps?

Um servidor que expõe dados do Google Maps como ferramentas que um cliente de IA pode chamar. O cliente envia uma chamada de ferramenta pelo Model Context Protocol, o servidor busca os dados e retorna JSON estruturado, e o modelo trabalha com o resultado e nunca vê uma página de HTML. Este expõe seis ferramentas somente leitura e roda remotamente. O cliente conecta a uma URL e não inicia nenhum processo local.

Existe um servidor MCP oficial do Google Maps?

O Google não publica um de propósito geral. Existe o Google Maps Platform, um conjunto de APIs pagas que você chama com seu próprio projeto Cloud, e vários servidores MCP da comunidade o envolvem. Este servidor é uma alternativa hospedada que não precisa de projeto Cloud.

Preciso de um projeto no Google Cloud ou de uma chave da API Maps?

Não. A única credencial é sua chave HasData. Não há projeto no Google Cloud para criar, nem faturamento para ativar, nem cota por API para gerenciar.

Qual é a diferença entre placeId e dataId?

São dois ids que o Google usa para o mesmo lugar. A busca retorna ambos em todo resultado, e as ferramentas de detalhe, avaliação, foto e post aceitam qualquer um dos dois. Guarde o que preferir do resultado da busca e reutilize.

Como obtenho todas as avaliações, não só a primeira página?

Leia pagination.nextPageToken de cada resposta e passe de volta como nextPageToken até que ele pare de vir. Cada página é uma chamada.

Preciso hospedar ou rodar algo?

Não. Este é um servidor MCP remoto em HTTP streamable. Nada para instalar, sem ambiente Python, sem processo para reiniciar.

Os dados são ao vivo ou em cache?

Ao vivo. Cada chamada busca no momento da requisição e carrega seu próprio requestMetadata.id. Duas chamadas idênticas são duas buscas separadas e não uma reprodução de uma cópia armazenada.

Posso usar um servidor para várias superfícies do Google?

Sim. O parâmetro apis aceita uma lista, e ?apis=google_maps,google_serp dá ao seu agente as ferramentas de mapas mais a busca do Google de uma vez.

A chave da API expira?

Não. A chave não expira. Gire-a no dashboard sempre que precisar.

Isso é afiliado ao Google?

Não. A HasData é um serviço independente e não é afiliada, endossada ou patrocinada pelo Google. Google e Google Maps são marcas registradas de seus respectivos proprietários. As ferramentas trabalham apenas com dados publicamente disponíveis, e você é responsável por usar os resultados em conformidade com os termos do Google e a lei que se aplica a você.

Links da HasData

Desenvolvimento

Este repositório é configuração e documentação para um servidor remoto. Não há etapa de build e nada para containerizar.

Ele carrega um teste de contrato. O README promete seis ferramentas com parâmetros específicos, e a lista de ferramentas upstream pode mudar sem um commit aqui, o que deixaria este arquivo mentindo silenciosamente para você. O teste afirma a promessa e roda semanalmente no CI, além de a cada push.

HASDATA_API_KEY=your_key_here npm test

No PowerShell:

$env:HASDATA_API_KEY = "your_key_here"; npm test

A última verificação faz uma chamada real e custa 5 créditos, que é o preço de um canário que pode falhar pelo motivo certo. Listar ferramentas é bem-sucedido com qualquer chave não vazia, e um teste que só lista ferramentas continua verde com uma chave revogada.

Contribuindo

Correções nas tabelas de ferramentas e nos exemplos de resposta são a contribuição mais útil, porque são as partes que se desatualizam. Inclua a chamada que você fez e a resposta que obteve. Pull requests de forks rodam a suíte sem chave, e as verificações ao vivo pulam em vez de ficarem vermelhas.

Licença

MIT. Veja LICENSE.