HasData Google Search MCP Server

Google Search MCP Server (SERP)

Um servidor Model Context Protocol (MCP) hospedado que oferece ao Claude, Cursor, Windsurf e qualquer outro cliente MCP oito ferramentas somente leitura de busca do Google. Obtenha o SERP ao vivo com seu AI Overview e People Also Ask, execute uma consulta no Google AI Mode e leia resultados de notícias, compras, detalhes de produtos e vídeos curtos, tudo como JSON estruturado, sem projeto no Google Cloud e sem configuração de mecanismo de busca.

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

"SERP" e "Google Search" são o mesmo produto aqui. Este servidor retorna páginas de resultados do mecanismo de busca do Google, analisadas.

Conteúdo

• O que você precisa
• Início rápido
• Exemplos de prompts
• Ferramentas
• Erros e caminhos de falha
• Preços, nível gratuito e limites
• Seleção de ferramentas
• Como se compara
• FAQ
• Links 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 HasData do painel, gratuita para criar sem cartão, e o teste cobre cerca de 100 a 200 chamadas dependendo da ferramenta. Nada mais. Este é um servidor remoto, então o caminho mais simples é uma URL e um cabeçalho, sem projeto no Google Cloud ou Programmable Search Engine para configurar. Um cliente somente stdio pode usar o inicializador @hasdata/google-search-mcp (npm) ou hasdata-google-search-mcp (PyPI) em vez disso.

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-search "https://mcp.hasdata.com/api/mcp?apis=google_serp" \
  --header "x-api-key: HASDATA_API_KEY"

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

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

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

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

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

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

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

Exemplos de prompts

Pesquise no Google por best running shoes e me dê os dez primeiros resultados orgânicos mais o AI Overview.

Uma chamada, 10 créditos. A resposta SERP traz o AI Overview inline junto com os resultados orgânicos.

Para a mesma consulta, pegue cada pergunta do People Also Ask e extraia a resposta do AI Overview com as fontes.

Uma chamada por pergunta, 5 créditos cada. Cada entrada relatedQuestions contém um aiOverview.pageToken, e a ferramenta AI Overview transforma esse token nos blocos de resposta e suas referências.

Pergunte ao Google AI Mode what is the Model Context Protocol e me dê a resposta com as citações.

Uma chamada, 10 créditos. O AI Mode retorna a resposta gerada como blocos de texto com uma lista de referências.

Pesquise no Google Shopping por nike air max, depois puxe o cartão completo do produto para o melhor resultado: cada loja que o vende, a faixa de preço e o detalhamento das avaliações.

Duas chamadas. Shopping custa 10 créditos e retorna um token por produto, e a ferramenta de produto imersivo gasta 5 para expandir esse token em lojas, variações e avaliações.

Obtenha as últimas notícias do Google para artificial intelligence, e separadamente os resultados de vídeos curtos para cooking pasta.

Duas chamadas, 10 créditos cada.

O fluxo de trabalho se apoia em duas cadeias. Uma resposta SERP devolve um aiOverview inline e um pageToken em cada pergunta do People Also Ask, então extrair as respostas generativas do Google é gratuito com a busca ou um acompanhamento de 5 créditos por pergunta. Um resultado de compras também devolve um token por produto, então o salto de uma listagem para seu cartão completo de várias lojas é uma única chamada.

Ferramentas

Oito ferramentas, todas somente leitura. As amostras abaixo são reduzidas de chamadas reais, e os resultados nelas mudam conforme o Google muda, então leia-as como formatos. Cada nome de ferramenta linka para sua referência de endpoint.

As amostras são o payload, não a resposta inteira. Um resultado tools/call carrega um bloco de texto, e esse texto é em si 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.

Google SERP

hasdata_google_serp_serp_getSearchResults

A página completa de resultados para uma consulta.

Retorna searchInformation, organicResults, aiOverview, relatedQuestions, relatedSearches, perspectives, immersiveProducts e pagination, com os blocos que o Google mostrar para a consulta. Entradas orgânicas carregam position, title, link, displayedLink, source, snippet, snippetHighlitedWords, date e images.

O AI Overview chega de duas maneiras. Normalmente aiOverview é inline, com textBlocks e references que você pode ler imediatamente. Às vezes o Google o protege atrás de um token, e então aiOverview carrega um pageToken e um hasdataLink em vez dos blocos. Cada entrada relatedQuestions também é esse segundo caso. Ela contém um question e um aiOverview com o mesmo pageToken e hasdataLink, que a ferramenta AI Overview abaixo expande. Então as respostas do People Also Ask são AI Overviews que você busca um token por vez. O aiOverview de nível superior é inline na maioria das consultas e um token em algumas, então leia-o das duas maneiras.

{
  "organicResults": [
    {
      "position": 1,
      "title": "The 15 Best Running Shoes of 2026",
      "link": "https://www.runnersworld.com/gear/a19663621/best-running-shoes/",
      "source": "Runner's World",
      "snippet": "The Brooks Ghost is our No. 1 shoe when we recommend new trainers…"
    }
  ],
  "aiOverview": {
    "textBlocks": [ { "type": "paragraph", "snippet": "The best running shoes depend on your goal…" } ],
    "references": [ { "index": 0, "title": "7 Best Running Shoes in 2026 - RunRepeat", "link": "https://runrepeat.com/guides/best-running-shoes" } ]
  },
  "relatedQuestions": [
    { "question": "What are the top 5 best running shoes?", "aiOverview": { "pageToken": "eyJpZCI6…", "hasdataLink": "https://api.hasdata.com/scrape/google/ai-overview?pageToken=eyJpZCI6…" } }
  ],
  "pagination": { "next": "…" }
}

Google AI Overview

hasdata_google_serp_ai_overview_getAiOverviewResponse

Expande um token de AI Overview em sua resposta.

Retorna aiOverview com textBlocks e references. É assim que você lê o AI Overview quando o SERP entregou um token em vez dos blocos, e como você transforma cada pergunta do People Also Ask em uma resposta citada.

Tokens são válidos por cerca de 4 minutos. Um token expirado não volta vazio, ele falha como um erro de ferramenta, isError: true com o texto HasData API error: 400 Bad Request. Trate-o da mesma forma que trataria uma chave errada, e execute novamente o SERP para obter um token novo.

{
  "aiOverview": {
    "textBlocks": [ { "type": "paragraph", "snippet": "The top five running shoes feature versatile options for daily training and racing…" } ],
    "references": [ { "index": 0, "title": "…", "link": "https://…" } ]
  }
}

Google AI Mode

hasdata_google_serp_ai_mode_getAiModeResponse

A resposta do AI Mode do Google para uma consulta, o resultado de busca conversacional.

Retorna textBlocks e references, a resposta gerada e as fontes que ela cita.

Google SERP Light

hasdata_google_serp_serp_light_getSearchResults

Uma busca mais barata que retorna o núcleo da página.

Retorna organicResults, aiOverview, relatedSearches, filters, appliedLocation, searchInformation e pagination. Custa metade dos créditos do SERP completo, para quando você quer resultados orgânicos e o AI Overview sem os blocos extras.

Google News

hasdata_google_serp_news_getGoogleNews

Os resultados do Google News para uma consulta ou uma seção de notícias.

Retorna newsResults, menuLinks, relatedTopics e relatedPublications. Cada entrada de notícia carrega position, title, link, source com um name e icon, thumbnail e date.

Google Shopping

hasdata_google_serp_shopping_getSearchResults

Resultados de compras para uma consulta.

Retorna shoppingResults, filters, refineSearchFilters, searchInformation e pagination. Cada resultado carrega position, title, productId, price, extractedPrice, rating, reviews, source, category, thumbnail e um immersiveProductPageToken.

immersiveProductPageToken é a entrada para a ferramenta de produto imersivo abaixo. É um token temporário, então expanda-o enquanto ele estiver fresco se quiser os dados do produto, e execute novamente a chamada de compras para obter um novo se um token antigo falhar.

{
  "shoppingResults": [
    {
      "position": 1,
      "title": "Men's Nike Alphafly 3",
      "productId": "13366226642799457284",
      "price": "$285.00",
      "extractedPrice": 285,
      "rating": 4.5,
      "reviews": 120,
      "source": "Nike",
      "immersiveProductPageToken": "eyJyZHMiOiJQQ18…"
    }
  ]
}

Produto imersivo

hasdata_google_serp_immersive_product_getImmersive_e29f691177

O cartão de produto completo por trás de um resultado de compras.

Retorna um objeto productResults com title, brand, rating, reviews, priceRange, um array stores de cada vendedor com seu preço e link, além de variants, reviewsImages, userReviews, topInsights, aboutTheProduct e discussionsAndForums. Esta é a única chamada que transforma uma única listagem no panorama completo entre lojas.

{
  "productResults": {
    "title": "Men's Nike Alphafly 3",
    "brand": "Nike",
    "rating": 4.4,
    "reviews": 1077,
    "priceRange": "$221-$295",
    "stores": [ { "name": "eBay", "link": "https://www.ebay.com/itm/…", "price": "$221" } ],
    "storesNextPageToken": "Mw=="
  }
}

Alimente storesNextPageToken de volta como o parâmetro nextPageToken para navegar pelas lojas.

Vídeos curtos do Google

hasdata_google_serp_short_videos_getShortVideosSearchResults

Os resultados de vídeos curtos que o Google mostra para uma consulta.

Retorna shortVideos, cada um com position, title, link, source, sourceLogo, profileName, duration, clip e thumbnail.

Erros e caminhos de falha

Seu cliente quase nunca vê um código de erro HTTP 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 da ferramenta, não como uma conexão falha. As ferramentas de listagem aceitam 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 relata o problema.

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

Um argumento que quebra o esquema é rejeitado antes de se tornar uma busca. 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.

Um token obsoleto de AI Overview falha como erro. Um token de resposta da SERP é válido por cerca de 4 minutos. Expandir um que você armazenou antes retorna com isError: true e o texto HasData API error: 400 Bad Request, no mesmo formato de uma chave errada. Capture-o e execute novamente a SERP para obter um token novo.

Um bloco que o Google não mostrou está ausente, não vazio. Uma consulta sem AI Overview, sem painel de compras ou sem "As pessoas também perguntam" retorna uma resposta sem essas chaves, em vez de com chaves vazias. Teste a chave antes de lê-la.

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, nível gratuito e limites

Os créditos são por ferramenta. A SERP completa, o AI Mode, Notícias, Compras e vídeos curtos custam 10 créditos por chamada. SERP Light, produto imersivo e a ferramenta de AI Overview custam 5. O AI Overview que vem embutido em uma resposta da SERP é gratuito, parte dessa chamada de 10 créditos, mas expandir um token com a ferramenta de AI Overview, incluindo cada token de "As pessoas também perguntam", é uma chamada separada de 5 créditos. O tamanho da resposta não muda o preço.

O teste gratuito é de 1.000 créditos por 30 dias sem cartão, o que equivale a 100 chamadas completas de SERP ou 200 das chamadas 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 no nível gratuito indefinidamente.

Os planos pagos começam em US$ 49 por mês para 200.000 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 solicitação por vez, Startup 15, Business 30, Growth 50, e os planos de alto volume variam de 200 a 1.500. A concorrência é o único limite. Não há um limite separado de solicitações por minuto. Lide com o caso de sobrecarga defensivamente em qualquer coisa não supervisionada, porque um agente que se espalha por consultas atingirá o teto antes de você.

Seleção de ferramentas

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

Uma lista restrita geralmente é o padrão melhor. Um modelo escolhendo entre oito ferramentas acerta com mais frequência do que um escolhendo entre cinquenta e sete, e as descrições das ferramentas custam contexto a cada turno.

Como se compara

O Google não oferece mais uma API de busca geral. A rota oficial é a Custom Search JSON API, e ela responde a uma pergunta diferente desta.

A Custom Search JSON API busca um Mecanismo de Pesquisa Programável que você configura, sobre os sites que você lista ou o índice completo da web se você ativá-lo. Ela é limitada a 100 consultas gratuitas por dia e depois cobra por mil até um teto diário, e retorna um conjunto de resultados reduzido. Ela não retorna o AI Overview, "As pessoas também perguntam", o pacote local, compras, notícias ou vídeos curtos, porque esses são recursos da página de resultados ao vivo, não da API. É a ferramenta certa quando você quer buscar seu próprio site ou um conjunto fixo de sites e permanecer dentro dos termos oficiais do Google para isso.

Este servidor retorna a página de resultados do Google ao vivo como um visitante a vê, analisada. Não há nada para configurar, a consulta roda contra todo o Google em vez de um mecanismo curado, e o AI Overview, "As pessoas também perguntam", compras e o resto retornam como blocos estruturados.

Duas linhas decidem. Se você só precisa buscar seus próprios sites e quer a API oficial do Google para isso, a Custom Search JSON API é a adequada. Se você precisa da SERP real, do AI Overview dela, ou de qualquer um dos painéis que o Google mostra a um pesquisador, a API oficial não os retorna e este servidor retorna.

O que este servidor não faz. Sem rastreamento das páginas por trás dos resultados, sem histórico de classificação, e nada que escreva. Ele retorna a página de resultados analisada.

FAQ

O que é um servidor MCP de busca do Google?

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

SERP é o mesmo que busca do Google aqui?

Sim. Uma SERP é uma página de resultados de mecanismo de busca. Essas ferramentas retornam as páginas de resultados do Google, então "API SERP" e "API de busca do Google" significam a mesma coisa neste repositório.

Existe um servidor MCP oficial de busca do Google?

O Google não publica um servidor MCP nem uma API de busca geral. O produto oficial mais próximo é a Custom Search JSON API, que busca um Mecanismo de Pesquisa Programável que você configura. Vários servidores MCP da comunidade, incluindo este, retornam a página de resultados ao vivo em vez disso.

Como obtenho o AI Overview?

Execute uma chamada de SERP. O aiOverview geralmente vem embutido com seu textBlocks e references. Quando ele retorna como um pageToken em vez disso, e em cada pergunta de "As pessoas também perguntam", passe esse token para a ferramenta de AI Overview para obter a resposta. Os tokens expiram rapidamente, então expanda-os a partir de uma chamada recente.

Preciso de um projeto Google Cloud ou de um Mecanismo de Pesquisa Programável?

Não. A única credencial é sua chave HasData. Nada para criar no Google Cloud, e nenhuma cota por API para gerenciar.

A chave de API expira?

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

Os dados são ao vivo ou em cache?

Ao vivo. Cada chamada busca a página de resultados no momento da solicitaçã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.

Isso é afiliado ao Google?

Não. A HasData é um serviço independente e não é afiliada, endossada ou patrocinada pelo Google. Google é uma marca registrada de seu respectivo proprietário. 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 documenta oito ferramentas com parâmetros específicos, e a lista de ferramentas upstream pode mudar sem um commit aqui, o que deixaria este arquivo silenciosamente mentindo para você. O teste afirma que as ferramentas documentadas existem com os parâmetros declarados, e roda semanalmente no CI, bem como 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 busca real e custa 10 créditos, que é o preço de um canário que pode falhar pelo motivo certo. Listar ferramentas funciona com qualquer chave não vazia, então um teste que apenas lista ferramentas permanece 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 essas 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 são puladas em vez de ficarem vermelhas.

Licença

MIT. Veja LICENSE.