Dados do Google Maps / Servidor MCP

Dados do Google Maps, dentro do seu fluxo de trabalho de IA.

Encontre empresas, leia avaliações públicas e explore galerias de lugares com Claude Code, Cursor, VS Code ou Codex. Três ferramentas remotas. A mesma chave de API.

Funciona com seu cliente MCP

Streamable HTTP remoto · Chave de API privada · Planos de API gratuitos e pagos

Três ferramentas / Uma conexão

Da descoberta de empresas ao detalhe do lugar.

Cada ferramenta retorna seu resultado diretamente. Escolha a operação que sua tarefa precisa e mantenha as páginas solicitadas explícitas.

Encontrar empresas

search_google_maps

Pesquise uma categoria e localização. Receba até 20 empresas com campos disponíveis de ficha, contato, avaliação e contagem de avaliações.

q · page · extra

Explorar a Search API

Ler avaliações públicas

get_google_maps_reviews

Use o feature ID de um lugar para solicitar até 10 avaliações. Escolha relevância, mais recentes, maior nota ou menor nota.

fid · page · sort_by

Explorar a Reviews API

Navegar pela mídia da galeria

get_google_maps_photos

Recupere até 20 registros de metadados de fotos e vídeos de um lugar. Leia as URLs de mídia retornadas e a flag de paginação.

fid · page

Explorar a Photos API

Avaliações e fotos aceitam o feature ID do Maps do place.dataId de um resultado de pesquisa. A pesquisa usa páginas 1–10; as ferramentas de mídia retornam next para que seu agente decida se outra página é necessária.

Conexão MCP

Um endpoint. Seu workspace de API.

Seu cliente cuida da inicialização e da descoberta de ferramentas, depois envia sua chave de API com cada requisição.

Conexão MCP remota
POST https://gmapscrawl.com/api/mcp
Authorization: Bearer <YOUR_API_KEY>
Content-Type: application/json
Accept: application/json, text/event-stream

Configuração do cliente

Escolha o cliente em que você trabalha.

Crie uma chave de API, depois copie a configuração do seu cliente. Mantenha a chave em seu ambiente ou configuração de input protegida.

Adicione este servidor ao .mcp.json. Disponibilize GMSCRAPER_API_KEY no ambiente que inicia o Claude Code.

{
  "mcpServers": {
    "google-maps-data": {
      "type": "http",
      "url": "https://gmapscrawl.com/api/mcp",
      "headers": {
        "Authorization": "Bearer ${GMSCRAPER_API_KEY}"
      }
    }
  }
}

Após salvar a configuração, reconecte e confirme que as três ferramentas aparecem. Siga o guia de configuração passo a passo.

Seu primeiro fluxo de trabalho

Conecte. Teste uma página. Leia o resultado.

Comece com uma chave de teste e dados simulados. Mude para uma chave live quando estiver pronto para usar sua cota de API.

01

Prepare seu workspace

Selecione o produto API e crie uma chave de teste com scrapes:write. Seu plano de API deve permitir MCP; Online e Extensão têm cotas separadas.

Criar uma chave
02

Descubra e chame uma ferramenta

Conecte seu cliente, inspecione search_google_maps e peça uma página. Gere um novo ID de requisição para novo trabalho e preserve-o ao repetir a mesma requisição.

Ver configuração do cliente
03

Use as empresas retornadas

Leia structuredContent.businesses e total. Rotule resultados de teste como simulados, preserve valores ausentes e pare após a página solicitada.

Entenda os campos
Chamar search_google_maps

Substitua o ID de requisição para cada nova pesquisa. Este exemplo não executa uma requisição a partir da página.

{
  "q": "coffee shops in Seattle",
  "page": 1,
  "hl": "en",
  "extra": false,
  "client_request_id": "replace-with-a-fresh-uuid"
}

O que volta

Registros estruturados, na mesma resposta da ferramenta.

businesses
Até 20 empresas retornadas; campos podem estar ausentes.
params + total
A consulta normalizada e a contagem nesta página.
simulated + usage metadata
Respostas de teste identificam dados de fixture e usam zero unidades de requisição live.
isError
Inspecione o erro antes de relatar que uma ferramenta teve sucesso.

Os resultados retornam diretamente; nenhum polling de job é necessário. Mantenha as datas de observação da fonte ao transformar o JSON em uma tabela ou relatório.

Prompts de exemplo

Uma pergunta útil. Um ponto de parada claro.

Use estes prompts após conectar. Forneça um feature ID real quando necessário, e peça ao seu agente que rotule resultados de teste como simulados.

Crie uma lista de empresas focada

“Use search_google_maps uma vez para cafeterias em Seattle, página 1, extra false. Retorne nomes, sites, telefones, avaliações e contagens de avaliações das empresas retornadas. Mantenha campos ausentes em branco e mostre as datas de observação. Pare após esta página.”

Resultado esperado

Uma tabela de até 20 empresas retornadas, com timestamps de origem e valores ausentes preservados.

Resuma uma página de avaliações

“Para a empresa que selecionei, use seu place.dataId como fid. Solicite a página 1 de get_google_maps_reviews com sort_by 2. Resuma os temas apenas nestas avaliações retornadas e cite suas datas. Não busque páginas adicionais.”

Resultado esperado

Um resumo delimitado de até 10 avaliações, sem tratar uma página como a experiência de todos os clientes.

Inspecione uma galeria

“Use get_google_maps_photos para este feature ID fornecido, apenas página 1. Liste os campos photoUrl retornados e o videoUrl opcional e informe se next é true. Não baixe arquivos nem busque a próxima página.”

Resultado esperado

Até 20 registros de galeria e o estado de paginação retornado, prontos para seu próprio aplicativo inspecionar.

REST + MCP

Uma cota de API nas duas interfaces.

MCP está disponível nos planos de API gratuitos e pagos. Cada página de fonte live bem-sucedida usa uma unidade de requisição de API, incluindo uma página vazia.

01

Teste sem uso live

Chaves de teste retornam fixtures simulados com zero unidades de requisição. Elas verificam sua integração em vez de produzir leads de empresas reais.

Gerenciar chaves de API
02

Mantenha as requisições delimitadas

Peça apenas as páginas e localizações que sua tarefa precisa. Use um novo ID de requisição para novo trabalho; repita requisições incertas com a mesma entrada e ID.

Ler orientações de uso
03

Adicione instruções reutilizáveis

O Agent Skill de Google Maps Data adiciona orientação de fluxo de trabalho, referências de operações e um fallback REST às mesmas ferramentas.

Explorar o Agent Skill

Explorar o hub de API → Os planos Online e da Extensão têm suas próprias cotas.

Ajuda de conexão

Chegue à próxima requisição bem-sucedida.

Use o estado da conexão e o erro retornado para escolher o próximo passo.

O cliente conecta mas nenhuma ferramenta aparece
Confirme que o endpoint é /api/mcp e que seu cliente suporta Streamable HTTP remoto com um cabeçalho Authorization privado. Recarregue a conexão e verifique se o processo consegue ler a chave configurada.
401 ou 403
Verifique a expiração da chave, IPs permitidos, acesso ativo ao workspace, o escopo scrapes:write e um plano de API que permita MCP. Cookies de login do navegador não autenticam o endpoint.
invalid_request
Leia o esquema da ferramenta selecionada. Forneça um client_request_id único de 16–128 caracteres; avaliações e fotos também precisam do FID de place.dataId, e não de um nome de empresa ou outro identificador de lugar.
rate_limited ou quota_exceeded
Respeite retry_after para limites de taxa. Pare quando a cota de API estiver esgotada e verifique seu uso de API; criar outra chave não adiciona cota.
capability_unavailable ou uma falha da fonte
Verifique o status do serviço e o erro retornado. A disponibilidade é determinada pelo servidor. Mantenha dados ausentes ou indisponíveis explícitos no seu resultado.
Timeout ou isError: true
Inspecione o erro da ferramenta mesmo quando a conexão HTTP teve sucesso. Para falhas passíveis de nova tentativa, mantenha a mesma entrada e ID de requisição dentro do prazo da sua tarefa. Siga as orientações de erro terminal antes de iniciar uma nova tentativa.

Status do serviço Orientações de erros e novas tentativas

Perguntas frequentes

O que o servidor MCP do Google Maps pode fazer?

Ele expõe search_google_maps, get_google_maps_reviews e get_google_maps_photos. A pesquisa retorna até 20 empresas; as avaliações retornam até 10 registros e as fotos até 20 registros de galeria por página. As ferramentas retornam dados estruturados diretamente.

Quais clientes posso conectar?

Use uma versão do Claude Code, Cursor, VS Code, Codex ou outro cliente MCP que suporte Streamable HTTP remoto e um cabeçalho Authorization privado. As quatro configurações de cliente acima usam o mesmo endpoint e a chave do workspace de API.

Como me autentico?

Crie uma chave de API com scrapes:write no seu workspace de API e configure-a privadamente como cabeçalho Bearer. Cookies do navegador não autenticam MCP. Mantenha as chaves fora de prompts, URLs e código-fonte commitado.

Como avaliações e fotos encontram o lugar certo?

Passe o feature ID do Maps como fid. Você pode usar place.dataId de uma empresa retornada. Avaliações também aceitam sort_by: 1 para relevância, 2 para mais recentes, 3 para maior nota ou 4 para menor nota. Leia next antes de considerar outra página de mídia.

MCP tem uma cota separada?

MCP compartilha a cota da API REST e está disponível nos planos de API gratuitos e pagos. Uma página live bem-sucedida usa uma unidade de requisição, incluindo uma página vazia. Credenciais de teste retornam dados simulados com zero unidades. As cotas Online e da Extensão são separadas.

Também preciso do Agent Skill?

O servidor MCP funciona sozinho. O Agent Skill de Google Maps Data opcional adiciona instruções reutilizáveis, referências de operações e um helper para fallback REST quando sua conexão MCP configurada está indisponível.

Dê o próximo passo

Traga dados do Google Maps para a sua próxima conversa.

Crie uma chave de API, conecte seu cliente preferido e teste uma pesquisa de empresas focada.