BigQuery

Servidor MCP BigQuery

O que é isso? 🤔

Este é um servidor que permite que seus LLMs (como o Claude) conversem diretamente com seus dados do BigQuery — somente leitura, sem capacidade de alterar seu warehouse. Pense nele como um tradutor amigável que fica entre seu assistente de IA e seu banco de dados, garantindo que eles possam conversar com segurança e eficiência.

Exemplo Rápido

You: "What were our top 10 customers last month?"
Claude: *queries your BigQuery database and gives you the answer in plain English*

Chega de escrever consultas SQL manualmente — basta conversar naturalmente com seus dados!

Como Funciona? 🛠️

Este servidor usa o Model Context Protocol (MCP), que é como um tradutor universal para comunicação entre IA e banco de dados. O MCP é suportado pelo Claude Desktop, Claude Code e um número crescente de outros clientes de IA.

Aqui está tudo o que você precisa fazer:

1. Configure a autenticação (veja abaixo)
2. Adicione os detalhes do seu projeto ao arquivo de configuração do seu cliente MCP
3. Comece a conversar naturalmente com seus dados do BigQuery!

O Que Ele Pode Fazer? 📊

• Somente leitura por design — apenas instruções SELECT são permitidas. Cada consulta é validada pelo planejador de dry-run do próprio BigQuery antes da execução, portanto INSERT, UPDATE, DELETE, DROP, TRUNCATE, EXPORT DATA e MERGE são todos rejeitados. O agente de IA não pode alterar seu warehouse, ponto final.
• Execute consultas SQL apenas fazendo perguntas em linguagem natural
• Acesse tabelas e visões materializadas em seus datasets
• Explore esquemas de datasets com rotulagem clara dos tipos de recursos (tabelas vs visões)
• Analise dados dentro de limites seguros configuráveis (definidos via config.json ou --maximum-bytes-billed)
• Proteja dados sensíveis — defina restrições de acesso em nível de campo para impedir que agentes de IA leiam PII, PHI, dados financeiros e segredos. O agente recebe orientações claras sobre como reformular consultas usando agregados ou cláusulas EXCEPT, permanecendo útil sem expor registros individuais.
• Descoberta automática de campos sensíveis — escaneie automaticamente todo o seu data warehouse do BigQuery em busca de colunas que correspondam a padrões sensíveis (nomes, e-mails, SSNs, registros médicos, chaves de API, etc.) e adicione-as à lista de restrições. Novas tabelas e colunas são protegidas automaticamente a cada escaneamento — sem necessidade de manutenção manual.
• Totalmente configurável — tudo é controlado por config.json. Adicione seus próprios padrões de detecção para corresponder às convenções de nomenclatura da sua organização (por exemplo, %guardian_name%, %beneficiary%), ajuste a frequência de escaneamento, defina limites de cobrança e configure restrições de campo por tabela. O scanner capta seus padrões personalizados na próxima execução e protege automaticamente todas as colunas correspondentes em todos os datasets.

Qual Configuração é Ideal para Você?

	Modo Simples	Modo Protegido
Use quando	Projetos pessoais, dados não sensíveis	PHI, PII, dados financeiros, ambientes regulados por HIPAA
Instalação	npx — sem necessidade de configuração local	npx ou build local com um config.json
Restrições de campo	Nenhuma	Defina preventedFields para bloquear colunas sensíveis
Auto-scanner	Não disponível	Descobre colunas sensíveis em todos os datasets automaticamente
Configuração	Configuração Rápida abaixo	Configuração do Modo Protegido abaixo

Por que a implantação local é importante para dados sensíveis: A inferência de LLM acontece na nuvem. Quando um agente de IA consulta o BigQuery, os resultados são enviados aos servidores do provedor de LLM (Anthropic, OpenAI, etc.) para processamento — eles saem da sua rede. O IAM do BigQuery controla quem pode alcançar seus dados; as restrições de campo controlam o que o agente de IA expõe nas respostas do LLM. São limites de proteção diferentes. Configurar preventedFields garante que PHI e PII nunca entrem no contexto da conversa do LLM, independentemente de quantas consultas o agente execute autonomamente.

Início Rápido 🚀

Pré-requisitos

• Node.js 14 ou superior
• Projeto do Google Cloud com BigQuery habilitado
• Google Cloud CLI instalado ou um arquivo de chave de conta de serviço
• Qualquer cliente compatível com MCP (Claude Desktop, Claude Code, etc.)

Configuração Rápida

1. Autentique-se com o Google Cloud:

   gcloud auth application-default login
   

2. Adicione à configuração do seu cliente MCP (por exemplo, claude_desktop_config.json para Claude Desktop, .mcp.json para Claude Code):

   {
     "mcpServers": {
       "bigquery": {
         "command": "npx",
         "args": [
           "-y",
           "@ergut/mcp-bigquery-server",
           "--project-id",
           "your-project-id"
         ]
       }
     }
   }
   

3. Comece a conversar! Abra seu cliente MCP e faça perguntas sobre seus dados.

Configuração do Modo Protegido

Para dados sensíveis com restrições em nível de campo:

1. Autentique-se com o Google Cloud (escolha um método):

   • Usando o Google Cloud CLI (ótimo para desenvolvimento):

     gcloud auth application-default login
     

   • Usando uma conta de serviço (recomendado para produção):

     # Save your service account key file and use --key-file parameter
     # Remember to keep your service account key file secure and never commit it to version control
     

2. Adicione à configuração do seu cliente MCP (por exemplo, claude_desktop_config.json para Claude Desktop, .mcp.json para Claude Code):

   • Com Application Default Credentials:

     {
       "mcpServers": {
         "bigquery": {
           "command": "npx",
           "args": [
             "-y",
             "@ergut/mcp-bigquery-server",
             "--project-id",
             "your-project-id",
             "--location",
             "us-central1",
             "--config-file",
             "/path/to/config.json"
           ]
         }
       }
     }
     

   • Com um arquivo de chave de conta de serviço:

     {
       "mcpServers": {
         "bigquery": {
           "command": "npx",
           "args": [
             "-y",
             "@ergut/mcp-bigquery-server",
             "--project-id",
             "your-project-id",
             "--location",
             "us-central1",
             "--key-file",
             "/path/to/service-account-key.json",
             "--config-file",
             "/path/to/config.json"
           ]
         }
       }
     }
     

3. Comece a conversar! Abra seu cliente MCP e comece a fazer perguntas sobre seus dados.

Configuração

O servidor suporta um arquivo config.json opcional para configuração avançada. Sem um arquivo de configuração (ou seja, sem a flag --config-file), o servidor executa no Modo Simples com padrões seguros (limite de consulta de 1GB, sem restrições de campo). Para habilitar a proteção, passe --config-file /path/to/config.json ao iniciar o servidor.

Estrutura do config.json

{
  "maximumBytesBilled": "1000000000",
  "preventedFields": {
    "healthcare.patients": ["first_name", "last_name", "ssn", "date_of_birth", "email"],
    "billing.transactions": ["credit_card_number", "bank_account"]
  },
  "sensitiveFieldPatterns": [
    "%first_name%", "%last_name%", "%email%",
    "%ssn%", "%date_of_birth%", "%password%"
  ],
  "sensitiveFieldScanFrequencyDays": 1
}

Configuração	Padrão	Descrição
maximumBytesBilled	"1000000000" (1GB)	Máximo de bytes cobrados por consulta
preventedFields	{}	Mapeamento tabela-para-colunas de campos restritos
sensitiveFieldPatterns	Conjunto integrado	Padrões SQL LIKE para descoberta automática
sensitiveFieldScanFrequencyDays	1	Dias entre escaneamentos automáticos (0 para desativar)

Argumentos de Linha de Comando

• --project-id: (Obrigatório) O ID do seu projeto do Google Cloud
• --location: (Opcional) Localização do BigQuery, padrão 'US'
• --key-file: (Opcional) Caminho para o arquivo JSON da chave da conta de serviço
• --config-file: (Opcional) Caminho para um arquivo de configuração. Se omitido, o servidor executa no Modo Simples sem proteção — não há padrão implícito de ./config.json
• --maximum-bytes-billed: (Opcional) Substitui o máximo de bytes cobrados por consultas, sobrepondo o valor do config.json

Exemplo usando conta de serviço:

npx @ergut/mcp-bigquery-server --project-id your-project-id --location europe-west1 --key-file /path/to/key.json --config-file /path/to/config.json --maximum-bytes-billed 2000000000

Protegendo Dados Sensíveis 🔒

Data warehouses frequentemente contêm informações altamente sensíveis — registros de pacientes, números de seguro social, dados financeiros, detalhes de contato pessoal e segredos de autenticação. Quando um agente de IA tem acesso direto para consultar seu warehouse, não há um humano no processo para impedi-lo de ler colunas sensíveis. Um SELECT * FROM patients poderia expor milhares de registros PII/PHI, e os resultados são então enviados ao provedor de LLM para processamento — eles saem da sua rede.

Este servidor dá aos administradores controle granular sobre quais colunas um agente de IA pode acessar. Você define preventedFields em config.json e o servidor bloqueia consultas que exporiam essas colunas nas respostas do LLM. Um scanner automatizado descobre colunas sensíveis em todos os seus datasets, mantendo a cobertura atualizada conforme seu warehouse cresce.

Advertência honesta: As restrições de campo são proteções cooperativas para agentes de IA — não um firewall SQL rígido contra atacantes adversários. Consulte PROTECTION.md para o modelo completo de ameaças.

O servidor suporta três modos de proteção, definidos via protectionMode em config.json:

Modo	Descrição
off	Sem proteção — todas as tabelas e campos acessíveis (padrão quando nenhum arquivo de configuração é fornecido)
allowedTables	Lista de permissão de tabelas — apenas as tabelas listadas podem ser consultadas, com restrições de campo opcionais dentro delas
autoProtect	Escaneia automaticamente seus datasets em busca de colunas sensíveis e aplica preventedFields

Consulte PROTECTION.md para configuração completa, exemplos, referência de padrões de consulta, configuração do scanner e permissões IAM necessárias.

Build Local (Opcional) 🔧

Execute um build local em vez de npx — útil para contribuir, testar alterações ou executar uma versão fixada. Suporta os Modos Simples e Protegido.

# Clone and install
git clone https://github.com/ergut/mcp-bigquery-server
cd mcp-bigquery-server
npm install

# Build
npm run build

Em seguida, aponte a configuração do seu cliente MCP para o build local:

{
  "mcpServers": {
    "bigquery": {
      "command": "node",
      "args": [
        "/path/to/your/clone/mcp-bigquery-server/dist/index.js",
        "--project-id",
        "your-project-id",
        "--location",
        "us-central1"
      ]
    }
  }
}

Para o Modo Protegido, adicione "--config-file", "/path/to/config.json" ao array args (e opcionalmente "--key-file", "/path/to/service-account-key.json" para autenticação com conta de serviço).

Limitações Atuais ⚠️

• Os exemplos de configuração JSON seguem o formato padrão de servidor MCP. Qualquer cliente compatível com MCP (Claude Desktop, Claude Code, etc.) pode usá-lo — consulte a documentação do seu cliente para a localização exata do arquivo de configuração
• Os limites de processamento são configuráveis por consulta (definidos em config.json ou via --maximum-bytes-billed)
• Embora tabelas e visões sejam suportadas, alguns tipos complexos de visão podem ter limitações
• Um arquivo config.json é opcional; sem ele, o servidor usa padrões seguros

Suporte e Recursos 💬

• 🐛 Relatar problemas
• 💡 Solicitações de recursos
• 📖 Documentação

Licença 📝

Licença MIT — Consulte o arquivo LICENSE para detalhes.

Autor ✍️

Salih Ergüt

Patrocínio

Este projeto é orgulhosamente patrocinado por:

Histórico de Versões 📋

Consulte CHANGELOG.md para atualizações e histórico de versões.