Skip to main content
Glama
jp-caldas

bigquery-google-trends-mcp

by jp-caldas
OverviewSchemaRelated ServersScoreDiscussions
Python
Remote

mcp-google-trends

English

Features

  • Top terms — daily most searched terms by country

  • Rising terms — fastest-growing search terms with percentage gain

  • Term comparison — track a term's interest score over time

Prerequisites

  • Python 3.12+

  • uv

  • A Google Cloud project with BigQuery API enabled

  • gcloud CLI installed and authenticated

Setup

# 1. Clone the repo
git clone https://github.com/jp-caldas/bigquery-google-trends-mcp.git
cd bigquery-google-trends-mcp

# 2. Copy env vars and edit with your GCP project ID
cp .env.example .env
# Edit .env: set GOOGLE_CLOUD_PROJECT=your-gcp-project-id

# 3. Install dependencies
uv sync

# 4. Authenticate with Google Cloud
gcloud auth application-default login

# 5. Verify BigQuery access
uv run mcp-google-trends

Usage

Run the MCP server

uv run mcp-google-trends

Starts a stdio-based MCP server listening for tool calls from an LLM client.

Connect with Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "google-trends": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/bigquery-google-trends-mcp", "mcp-google-trends"],
      "env": {
        "GOOGLE_CLOUD_PROJECT": "your-gcp-project-id"
      }
    }
  }
}

Available tools

Tool

Description

Parameters

buscar_termos_em_alta_tool

Top search terms for a country since a date

pais (str), data_limite (str YYYY-MM-DD)

buscar_termos_emergentes_tool

Fastest-rising terms with % gain

pais (str), data_limite (str YYYY-MM-DD)

comparar_termo_tool

Track a term's score over time

termo, pais, data_inicio, data_fim

Example prompts for Claude

"What are the top trending terms in Brazil this week?"

"Show me the fastest rising terms in the US since last month."

"Compare the interest for 'Python' in Brazil between 2024-01 and 2024-06."

Interactive debugging

npx @modelcontextprotocol/inspector uv run mcp-google-trends

Related MCP server: Google Trends MCP Server

Português

Funcionalidades

  • Termos em alta — termos mais buscados por país

  • Termos emergentes — termos com maior crescimento percentual

  • Comparação de termos — acompanhe o score de um termo ao longo do tempo

Pré-requisitos

  • Python 3.12+

  • uv

  • Um projeto Google Cloud com BigQuery API ativada

  • gcloud CLI instalado e autenticado

Configuração

# 1. Clone o repositório
git clone https://github.com/jp-caldas/bigquery-google-trends-mcp.git
cd bigquery-google-trends-mcp

# 2. Copie as variáveis de ambiente e edite com seu GCP project ID
cp .env.example .env
# Edite .env: defina GOOGLE_CLOUD_PROJECT=seu-projeto-gcp

# 3. Instale as dependências
uv sync

# 4. Autentique no Google Cloud
gcloud auth application-default login

# 5. Verifique o acesso ao BigQuery
uv run mcp-google-trends

Uso

Iniciar o servidor MCP

uv run mcp-google-trends

Inicia um servidor MCP via stdio, ouvindo chamadas de ferramentas do cliente LLM.

Conectar com Claude Desktop

Adicione ao claude_desktop_config.json:

{
  "mcpServers": {
    "google-trends": {
      "command": "uv",
      "args": ["run", "--directory", "C:/caminho/para/bigquery-google-trends-mcp", "mcp-google-trends"],
      "env": {
        "GOOGLE_CLOUD_PROJECT": "seu-projeto-gcp"
      }
    }
  }
}

Ferramentas disponíveis

Ferramenta

Descrição

Parâmetros

buscar_termos_em_alta_tool

Termos mais buscados em um país desde uma data

pais (str), data_limite (str YYYY-MM-DD)

buscar_termos_emergentes_tool

Termos com maior crescimento percentual

pais (str), data_limite (str YYYY-MM-DD)

comparar_termo_tool

Acompanhe o score de um termo ao longo do tempo

termo, pais, data_inicio, data_fim

Exemplos de prompts para o Claude

"Quais são os termos em alta no Brasil esta semana?"

"Mostre os termos emergentes nos EUA desde o mês passado."

"Compare o interesse por 'Python' no Brasil entre janeiro e junho de 2024."

Depuração interativa

npx @modelcontextprotocol/inspector uv run mcp-google-trends

Development / Desenvolvimento

# All checks at once
make check

# Or step by step
make lint        # ruff
make typecheck   # mypy
make test        # pytest + coverage

# Build Docker image
make build-docker

# Clean cache
make clean

CI: every push to main runs ruff → mypy → pytest automatically via GitHub Actions.

Project structure / Estrutura do projeto

src/mcp_google_trends/
├── __main__.py          # Entrypoint
├── server.py            # FastMCP server + lifespan
├── tools.py             # Business logic + SQL queries
├── bigquery_client.py   # BigQuery client wrapper
├── models.py            # Pydantic models
├── config.py            # Environment config validation
└── exceptions.py        # Custom exceptions
tests/
├── conftest.py          # BigQuery mocks
├── test_tools.py        # Tool unit tests
└── test_server.py       # Server integration tests
data/
├── sample_top_terms.json
└── sample_rising_terms.json

Tech stack / Tecnologias

Library

Purpose / Propósito

mcp[cli]

MCP server framework (FastMCP)

google-cloud-bigquery

BigQuery client

pydantic

Data validation and models

pytest + pytest-cov

Testing + coverage

ruff

Linting

mypy

Static type checking

License / Licença

MIT

This server cannot be installed

F
license - not found
-
quality - not tested
C
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
–Release cycle
–Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/jp-caldas/bigquery-google-trends-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server