HasData Google Trends MCP Server

Servidor MCP do Google Trends

Um servidor hospedado do Model Context Protocol (MCP) que dá ao Claude, Cursor, Windsurf e qualquer outro cliente MCP uma ferramenta do Google Trends. Obtenha interesse ao longo do tempo, interesse por região e as consultas e tópicos relacionados em alta e principais para qualquer termo, tudo como JSON estruturado, sem biblioteca de scraping para manter e sem conta do Google.

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

Conteúdo

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

O que você precisa

Um cliente MCP e 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. Este é um servidor remoto, então o caminho mais simples é uma URL e um cabeçalho x-api-key, sem contêiner para executar e sem conta do Google em nenhum lugar do fluxo. Um cliente que só fala stdio o acessa por meio de um lançador leve, publicado como @hasdata/google-trends-mcp no npm e hasdata-google-trends-mcp no PyPI, mostrado abaixo.

Início rápido

A URL do servidor é a mesma para todos os clientes. Nós o 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-trends "https://mcp.hasdata.com/api/mcp?apis=google_trends" \
  --header "x-api-key: HASDATA_API_KEY"

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

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

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

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

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

Exemplos de prompts

Prompts, não código. Cole um e o agente escolhe a ferramenta por conta própria. Cada um é anotado com as chamadas que faz, porque cada chamada bem-sucedida custa 5 créditos.

Faça um gráfico do interesse em "cold brew coffee" nos EUA nos últimos 12 meses e me diga em quais semanas atingiu o pico.

Uma chamada, 5 créditos. A série semanal volta em uma única solicitação.

Para "cold brew coffee" nos EUA, me dê as consultas relacionadas em alta e sinalize as marcadas como Breakout.

Uma chamada, 5 créditos.

Compare o interesse em "cold brew" com "iced coffee" no mundo todo ao longo de cinco anos e diga qual está crescendo.

Uma chamada, 5 créditos. A ferramenta aceita vários termos em uma única solicitação de série temporal.

Mostre-me o interesse em "sunscreen" por estado dos EUA nos últimos 90 dias para que eu possa ver onde a demanda é maior.

Uma chamada, 5 créditos. Esta é a visão de interesse por região na granularidade de estado.

Uma comparação entre termos cabe em uma única chamada de timeseries. Divisões por região, consultas relacionadas e tópicos relacionados são cada uma uma dataType própria, então um prompt que quer um gráfico mais suas consultas em alta são duas chamadas.

Ferramentas

Uma ferramenta, somente leitura. A amostra abaixo é extraída de uma chamada real, e os números mudam conforme a tendência muda. Leia-a como uma forma. O nome da ferramenta leva à referência do endpoint, que traz a lista completa de parâmetros.

A amostra é o payload, não a resposta inteira. Um resultado de 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.

Obter dados do Google Trends

hasdata_google_trends_search_getTrendsData

Interesse ao longo do tempo, por região, ou as consultas e tópicos relacionados para um termo.

A chave da resposta depende de dataType. timeseries retorna interestOverTime.timelineData, geoMap retorna interesse por região, e os tipos relacionados retornam relatedQueries ou relatedTopics, cada um dividido em rising e top. Leia a chave que corresponde ao tipo que você solicitou.

timeseries (o padrão) retorna um valor de 0 a 100 para cada ponto, tanto como string quanto pré-analisado em extractedValue. O ponto mais recente frequentemente carrega isPartial: true, significando que a semana ainda está sendo preenchida. Descarte-o antes de calcular uma tendência, ou a última barra parecerá uma queda que não é real.

{
  "interestOverTime": {
    "timelineData": [
      { "date": "Apr 12 – 18, 2026", "timestamp": "1775952000", "isPartial": false,
        "values": [{ "query": "cold brew coffee", "value": "100", "extractedValue": 100, "hasData": true }] },
      { "date": "Aug 23 – 29, 2026", "timestamp": "1787443200", "isPartial": true,
        "values": [{ "query": "cold brew coffee", "value": "44", "extractedValue": 44, "hasData": true }] }
    ]
  }
}

relatedQueries divide em rising e top. Uma entrada em alta aparece como uma porcentagem como +300%, ou Breakout para um salto grande demais para pontuar, e extractedValue dá o número por trás dele. Um Breakout volta com um sentinela extractedValue bem acima de qualquer porcentagem real, então ordene pelo rótulo da string, não pelo número bruto.

{
  "relatedQueries": {
    "rising": [
      { "query": "organic cold brew coffee", "value": "+300%", "extractedValue": 300, "link": "https://trends.google.com/trends/explore?q=organic+cold+brew+coffee&date=today+12-m&geo=US" }
    ],
    "top": [
      { "query": "how to cold brew coffee", "value": "100", "extractedValue": 100, "link": "https://trends.google.com/trends/explore?q=how+to+cold+brew+coffee&date=today+12-m&geo=US" }
    ]
  }
}

A referência do endpoint lista todos os geo, cat e formatos de data que a ferramenta aceita.

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 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. tools/list aceita qualquer chave não vazia e retorna a ferramenta, então o cliente completa o handshake e mostra verde. A primeira chamada de ferramenta então volta com isError: true e o texto HasData API error: 401 Unauthorized. Fique atento a essa string, porque nada antes no fluxo relata o problema.

Uma chave ausente é o único erro HTTP real. A autorização roda antes de qualquer ferramenta, e a própria conexão falha com 401. Cabeçalhos CORS estão presentes, e um cliente de navegador lê o status e não uma falha de rede opaca.

Um argumento que quebra o esquema da ferramenta é rejeitado antes de virar uma extração. O servidor responde com isError: true e o texto MCP error -32602: Input validation error, nomeando o campo ofensor. Nada é buscado e nada é cobrado.

Um termo com volume de busca muito baixo retorna um resultado bem-sucedido com os arrays de dados vazios, não um erro. O Google Trends não tem nada para mostrar para um termo raro, e requestMetadata.status ainda lê ok. Teste os pontos antes de criar gráficos com eles.

Um identificador que a plataforma rejeita retorna 400 com requestMetadata.status definido como error. Um valor desconhecido de geo ou cat é a maneira usual de ver isso.

Resultados que carregam dados também carregam um requestMetadata.id que vale citar no suporte.

Preços, plano gratuito e limites

Cada chamada do Google Trends custa 5 créditos por chamada bem-sucedida. O tamanho da resposta não muda o preço. Uma série semanal de cinco anos custa o mesmo que uma única semana.

O teste gratuito é de 1.000 créditos por 30 dias sem cartão, o que equivale a 200 chamadas do Google Trends. 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 plano gratuito indefinidamente.

Os planos pagos começam em US$ 49 por mês por 200.000 créditos, o que equivale a 40.000 chamadas. O preço unitário cai com o volume, de US$ 1,23 por 1.000 chamadas no plano inicial para US$ 0,50 no Business, US$ 0,42 no Growth e US$ 0,37 nos maiores planos de alto volume.

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 vão de 200 a 1.500. Trate o caso de estouro defensivamente em qualquer coisa não supervisionada.

Uma solicitação que volta com status diferente de 200 não é cobrada. Uma chamada bem-sucedida que não encontra nada ainda é uma chamada.

Seleção de ferramentas

O parâmetro de consulta apis decide quais ferramentas seu agente vê. Menos ferramentas significa menos contexto gasto em definições de ferramentas e menos chances de o modelo alcançar a errada.

?apis=google_trends              the one tool in this repo
?apis=google_trends,google_serp  add Google search
?apis=google_trends,youtube      trends plus YouTube

O parâmetro aceita nomes de provedores como google_trends e nomes individuais de APIs. Nomes com erro de digitação são ignorados. Se todos os nomes estiverem errados, a solicitação falha com 400, e o corpo lista tanto o que não foi reconhecido quanto todos os valores válidos. Remova o parâmetro e o mesmo endpoint expõe todas as 57 ferramentas do HasData.

Como se compara

O Google não publica uma API pública de Trends. As duas rotas comuns são a biblioteca não oficial pytrends, que faz engenharia reversa dos mesmos endpoints internos e quebra quando o Google os altera ou limita a taxa do chamador, e criar seu próprio scraper. Este servidor faz esse trabalho por trás de um esquema estável.

FAQ

Existe uma API oficial do Google Trends?

Não. O Google nunca disponibilizou uma API pública de Trends. Todas as opções leem os mesmos endpoints internos que o site trends.google.com utiliza. Este é mantido pela HasData e retorna o resultado como JSON estruturado.

O que é um servidor MCP do Google Trends?

Um servidor que expõe o Google Trends como uma ferramenta 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. Este expõe uma única ferramenta e roda remotamente, então o cliente se conecta a uma URL e não inicia nenhum processo local.

Os números significam volume absoluto de buscas?

Não, e o próprio Google Trends também não. Os valores são interesse relativo escalado de 0 a 100 dentro da consulta, janela e região que você solicitou. Use-os para forma e comparação, não como uma contagem de buscas.

Por que o último ponto de dados é menor que os demais?

O bucket mais recente geralmente ainda está sendo preenchido e retorna com isPartial: true. Descarte-o antes de calcular uma tendência.

Posso comparar vários termos de uma vez?

Sim, em timeseries e geoMap. Passe os termos separados por vírgula em q. Os tipos de consulta relacionada e tópico relacionado aceitam um único termo.

Posso usar isso junto com outras APIs da HasData?

Sim. O parâmetro apis aceita uma lista, e ?apis=google_trends,google_serp dá ao seu agente Trends mais busca do Google. Remova o parâmetro e você obtém tudo.

Conformidade e dados pessoais

A HasData acessa apenas dados publicamente disponíveis. Os termos de uma plataforma podem restringir acesso automatizado, e você é responsável pela sua própria conformidade.

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.

Os testes em test/ verificam o contrato da ferramenta, a parte que pode quebrar sem um commit aqui. Eles verificam que ?apis=google_trends retorna exatamente uma ferramenta, que ela ainda declara seu parâmetro obrigatório, que o nome não mudou e que a chave em uso é realmente aceita. Essa última verificação chama a ferramenta de verdade e custa 5 créditos, que é o preço de um canário que pode falhar pelo motivo certo.

# macOS and Linux
HASDATA_API_KEY=your_key_here npm test

# Windows PowerShell
$env:HASDATA_API_KEY="your_key_here"; npm test

A mesma suíte roda em CI a cada push e uma vez por semana em agendamento, porque a lista de ferramentas upstream pode mudar sem que ninguém toque neste repositório. Uma falha significa que a lista de ferramentas mudou, a chave parou de funcionar ou o endpoint ficou inacessível, e a mensagem de asserção indica qual.

Contribuindo

Correções na tabela de parâmetros e na amostra de resposta são a contribuição mais útil, porque são as partes que mais divergem. 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.