MCP 服务器

bigquery-google-trends-mcp

MCP server that exposes Google Trends data via BigQuery, enabling LLMs to query top search terms, rising terms, and compare term interest over time for different countries.

README

mcp-google-trends

<a href="#english"><kbd>🇺🇸 English</kbd></a> <a href="#português"><kbd>🇧🇷 Português</kbd></a>

MCP server que expõe dados do Google Trends via BigQuery

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

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