BigQuery

Acesse e armazene em cache metadados do Google Cloud BigQuery.

GitHubExperimente este MCPPatrocinado

Documentação

BigQuery MCP Server

Python Version Framework

Este é um servidor MCP (Model Context Protocol) baseado em Python que recupera informações de datasets, tabelas e esquemas do Google Cloud BigQuery, armazena em cache localmente e as serve via MCP. Seu objetivo principal é permitir que sistemas de IA generativa entendam rapidamente a estrutura do BigQuery e executem consultas com segurança.

Principais Recursos

  • Gerenciamento de Metadados: Recupera e armazena em cache informações sobre datasets, tabelas e colunas do BigQuery
  • Pesquisa por Palavras-chave: Suporta pesquisa por palavras-chave nos metadados em cache
  • Execução Segura de Consultas: Fornece capacidades de execução SQL com inserção automática de cláusula LIMIT e controle de custos
  • Exportação de Arquivos: Executa consultas e salva resultados em arquivos locais nos formatos CSV ou JSONL
  • Conformidade com MCP: Oferece ferramentas através do Model Context Protocol

Ferramentas do Servidor MCP

Ferramentas disponíveis:

  1. get_datasets - Recupera uma lista de todos os datasets
  2. get_tables - Recupera todas as tabelas dentro de um dataset especificado (requer dataset_id, opcionalmente aceita project_id)
  3. search_metadata - Pesquisa metadados de datasets, tabelas e colunas
  4. execute_query - Executa consultas SQL do BigQuery com segurança, com inserção automática de cláusula LIMIT e controle de custos
  5. check_query_scan_amount - Recupera a quantidade de varredura (scan) para consultas SQL do BigQuery
  6. save_query_result - Executa consultas SQL do BigQuery e salva resultados em arquivos locais (formato CSV ou JSONL)

Detalhes das Ferramentas

save_query_result

A ferramenta save_query_result fornece execução avançada de consultas com capacidades de exportação de arquivos:

Parâmetros:

  • sql (obrigatório): Consulta SQL a ser executada
  • output_path (obrigatório): Caminho do arquivo local para salvar os resultados
  • format (opcional): Formato de saída - "csv" (padrão) ou "jsonl"
  • project_id (opcional): ID do projeto GCP de destino
  • include_header (opcional): Incluir linha de cabeçalho na saída CSV (padrão: true)

Principais Recursos:

  • Sem LIMIT Automático: Ao contrário de execute_query, esta ferramenta não adiciona automaticamente cláusulas LIMIT às suas consultas SQL
  • Controle de Custos: Mantém limites de quantidade de varredura (padrão: 1GB) e verificações de segurança para evitar consultas caras
  • Segurança: Validação de caminho previne ataques de travessia de diretório
  • Formatos Flexíveis: Suporta formatos de saída CSV e JSONL
  • Suporte a Grandes Datasets: Lida com grandes resultados de consultas de forma eficiente dentro dos limites de varredura

Exemplo de Uso:

-- Export all rows without LIMIT restriction (subject to scan amount limits)
SELECT customer_id, order_date, total_amount 
FROM `project.dataset.orders` 
WHERE order_date >= '2024-01-01'

Nota Importante: Embora esta ferramenta não adicione cláusulas LIMIT, ela ainda impõe limites de quantidade de varredura para proteção de custos. Consultas que varreriam mais do que o limite configurado (padrão: 1GB) serão rejeitadas.

Instalação e Configuração do Ambiente

Pré-requisitos

  • Python 3.11 ou posterior
  • Conta do Google Cloud Platform
  • Projeto GCP com a API do BigQuery habilitada

Instalação

uv

uv add bq_mcp_server

pip

pip install bq_mcp_server

Instalando Dependências

Este projeto usa uv para gerenciamento de pacotes:

# Install uv if not already installed
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install dependencies
uv sync

Configurando Opções

Para uma lista de valores de configuração, consulte:

docs/settings.md

Configuração do MCP

Claude Code

claude mcp add bq_mcp_server -- uvx --from git+https://github.com/takada-at/bq_mcp_server bq_mcp_server --project-ids <your project ids>

JSON

{
    "mcpServers": {
        "bq_mcp_server": {
            "command": "uvx",
            "args": [
                "--from",
                "git+https://github.com/takada-at/bq_mcp_server",
                "bq_mcp_server",
                "--project-ids",
                "<your project ids>"
            ]
        }
    }
}

Executando Testes

Executando Todos os Testes

pytest

Executando Arquivos de Teste Específicos

pytest tests/test_logic.py

Executando Funções de Teste Específicas

pytest -k test_function_name

Verificando Cobertura de Testes

pytest --cov=bq_mcp_server

Desenvolvimento Local

Iniciando o Servidor MCP

uv run bq_mcp_server

Iniciando o Servidor de API REST FastAPI

uvicorn bq_mcp_server.adapters.web:app --reload

Comandos de Desenvolvimento

Formatação de Código e Linting

# Code formatting
ruff format

# Linting checks
ruff check

# Automatic fixes
ruff check --fix

Gerenciamento de Dependências

# Adding new dependencies
uv add <package>

# Adding development dependencies
uv add --dev <package>

# Updating dependencies
uv sync