Snow Leopard BigQuery MCP

Interaja com bancos de dados do Google BigQuery usando consultas em linguagem natural e exploração de esquemas.

Documentação

Snow Leopard BigQuery MCP

Um servidor Model Context Protocol (MCP) para Google BigQuery que permite que agentes de IA interajam com bancos de dados BigQuery por meio de consultas em linguagem natural e exploração de esquemas.

Este projeto foi desenvolvido pela Snow Leopard AI como uma ferramenta de benchmarking para nossa plataforma, e estamos disponibilizando-o publicamente para que a comunidade possa usar e desenvolver.

O que é MCP?

O Model Context Protocol (MCP) é um padrão aberto que permite que aplicações de IA se conectem com segurança a fontes de dados e ferramentas externas. Este servidor BigQuery MCP atua como uma ponte entre agentes de IA e seus conjuntos de dados do BigQuery.

Recursos do Servidor Snow Leopard BigQuery MCP

Recursos

URI do Recurso	Descrição
`bigquery://tables`	Lista todas as tabelas disponíveis para o agente
`bigquery://tables/{table}/schema`	Obtém o esquema de uma tabela específica

Ferramentas

Ferramenta	Descrição
`list_tables(table: str)` (opcional)	Lista tabelas disponíveis
`get_schema(table: str)` (opcional)	Obtém o esquema de uma determinada tabela
`query(sql: str)`	Executa SQL do BigQuery e retorna resultados

Início Rápido: Claude Desktop

Pré-requisitos

Antes de começar, certifique-se de ter:

Claude Desktop: Baixe aqui
Projeto Google Cloud com BigQuery habilitado: Guia de configuração
Google Cloud CLI (gcloud): Guia de instalação
Gerenciador de Pacotes UV: Guia de instalação

1. Configurar o Google Cloud

Primeiro, precisamos autenticar com o Google.

gcloud auth application-default login

Isso abre seu navegador para autenticar sua máquina local com o Google Cloud.

2. Configurar o Claude Desktop

Edite seu arquivo claude_desktop_config.json para adicionar o servidor BigQuery MCP.

Aplicação: Claude > Configurações > Desenvolvedor > Editar Configuração
Mac: ~/Library/Application\ Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\\Claude\\claude_desktop_config.json

Você precisará definir seu projeto como um projeto do Google Cloud com permissões para enviar jobs do BigQuery. Se você não tiver um projeto no qual possa executar jobs do BigQuery, crie e teste um seguindo o Guia de Início Rápido do BigQuery do Google. Crie um projeto e siga as instruções para consultar um conjunto de dados público.

{
  "mcpServers": {
    "bigquery": {
      "command": "uvx",
      "args": [
        "sl-bigquery-mcp", 
        "--dataset",
        "bigquery-public-data.usa_names",
        "--project",
        "🚨 <projectName> 🚨"
      ]
    }
  }
}

3. Feche o Claude Desktop e inicie-o pelo terminal

Dependendo de como você instalou o uv, o executável uvx pode não estar no PATH do Claude Desktop se ele for iniciado pela interface gráfica. Para garantir que o uvx esteja acessível pelo Claude Desktop, vamos executá-lo no terminal.

open -a claude

Após salvar a configuração, reinicie o Claude Desktop. Agora você deve conseguir fazer perguntas ao Claude sobre seus dados do BigQuery!

Exemplo de Consulta

What are the top 10 most popular names in 2020?

Opções de Configuração

Para ver uma lista completa de parâmetros:

uvx sl-bigquery-mcp --help

Usage: sl-bigquery-mcp [OPTIONS]

╭─ Options ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --mode                       [stdio|sse|streamable-http]  MCP transport protocol [default: stdio]                                                     │
│ --dataset                    TEXT                         Dataset(s) for mcp resources. Will create resources for all tables.                         │
│ --table                      TEXT                         Table(s) for mcp resources. Can be specified as project.dataset.table or dataset.table      │
│ --enable-list-tables-tool    --no-enable-list-tables-tool Registers list_resources tool [default: enable-list-tables-tool]                            │
│ --enable-schema-tool         --no-enable-schema-tool      Registers get_schema tool [default: enable-schema-tool]                                     │
│ --project                    TEXT                         BigQuery project [env var: BQ_PROJECT] [default: None]                                      │
│ --api-method                 [INSERT|QUERY]               BigQuery client api_method [default: QUERY]                                                 │
│ --port                       INTEGER                      [default: 8000]                                                                             │
╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

Solução de Problemas / FAQ

Ocorreu um erro MCP

Primeiro, verifique os logs do aplicativo Claude Desktop (no mesmo diretório do arquivo de configuração) para obter erros/logs mais detalhados

Na Inicialização

Isso geralmente significa que o Claude está tendo problemas para iniciar o servidor MCP. Frequentemente, isso se deve ao uvx não estar acessível pelo aplicativo. Nesse caso, use o caminho completo para o seu executável uvx em vez de apenas uvx em claude_desktop_config.json.

Para encontrar seu executável uv, execute

which uvx

Caso contrário, isso pode ser causado por argumentos incorretos, incompatibilidades de versão de dependências ou bugs. Se você encontrar os dois últimos casos, registre uma issue descrevendo o problema.

No Uso de Recursos/Ferramentas

Isso pode ser uma configuração incorreta do servidor MCP, problemas de autenticação, o LLM recebendo muitos dados ou, é claro, bugs do produto. Após verificar os logs, considere usar o MCP Inspector para depurar seu problema. E, claro, registre quaisquer bugs que encontrar em nosso quadro de issues.

Desenvolvimento e Testes Locais

Configurar Ambiente de Desenvolvimento

Clone o repositório
Configure o ambiente virtual e instale as dependências
Verifique a instalação

git clone https://github.com/SnowLeopard-AI/bigquery-mcp.git
cd bigquery-mcp

uv sync
source .venv/bin/activate

sl-bigquery-mcp --help

Autenticar com o Google Cloud

O comando a seguir abrirá um navegador para você fazer login na sua conta do Google Cloud. Você deve ter um projeto do Google Cloud com BigQuery habilitado. Se não tiver, consulte o guia de configuração do BigQuery do Google.

gcloud auth application-default login
gcloud config set project <projectName>
gcloud auth application-default set-quota-project <projectName>

Executando Testes

Execute os testes para garantir que seu ambiente de desenvolvimento esteja configurado corretamente.

pytest tests

Nota: os testes executam consultas reais do BigQuery em conjuntos de dados públicos e exigem autenticação.

MCP Inspector Local

Para testes práticos e desenvolvimento, use a ferramenta MCP Inspector:

npx @modelcontextprotocol/inspector uv run sl-bigquery-mcp --dataset bigquery-public-data.usa_names

Contribuindo

Aceitamos contribuições! Coordene conosco no discord para garantir que suas alterações possam entrar rapidamente no repositório. Comunicar antes de codificar sempre economiza tempo.

Para a logística de contribuir com um projeto de código aberto, consulte o repositório de primeiras contribuições.

Suporte

Issues: GitHub Issues
Documentação: Documentação do BigQuery
Protocolo MCP: Model Context Protocol
Contato: Servidor Discord