Como Conectar o Claude Code ao BigQuery via MCP: O Guia de Setup Definitivo

Se você trabalha com dados, provavelmente já viveu esta situação. Surge uma dúvida simples de negócio, mas até chegar na resposta você precisa abrir o banco, localizar tabela, lembrar nome de coluna, montar SQL, testar, ajustar filtro, corrigir erro e só então começar a analisar o que realmente importa.

É justamente nesse ponto que a integração entre Claude Code e BigQuery começa a fazer sentido.

A proposta aqui não é substituir o analista, nem vender a ideia de que a IA resolve tudo sozinha. O ganho real está em reduzir atrito nas etapas iniciais da análise de dados. Em vez de gastar energia com tarefas repetitivas de exploração, entendimento de schema e montagem de consultas, você passa a interagir com a base de uma forma mais fluida, dentro do próprio ambiente de trabalho.

Neste artigo, vou te mostrar como conectar o Claude Code ao Google BigQuery via MCP, que é a ponte usada para permitir essa comunicação. A ideia é organizar o processo do vídeo de um jeito mais claro, para que você entenda não só o que fazer, mas também por que cada etapa importa na prática.

Se a conexão estiver bem feita, o Claude Code consegue consultar a estrutura do banco, entender melhor suas tabelas e ajudar a transformar perguntas de negócio em consultas mais naturais. E quando isso é combinado com contexto bem definido no projeto, a experiência melhora bastante.

Em outras palavras, este não é só um artigo sobre instalar uma conexão. É um artigo sobre montar uma base mínima para fazer análise de dados com mais contexto, menos retrabalho e mais consistência.

O que é MCP e por que ele importa na conexão entre Claude Code e BigQuery

MCP significa Model Context Protocol. Segundo a Anthropic, ele é um padrão aberto para conectar aplicações de IA a sistemas externos, como bancos de dados, arquivos, APIs e ferramentas. No caso do Claude Code, isso permite conectar o modelo a fontes de dados externas e trabalhar com muito mais contexto real.

Na prática, isso muda bastante a forma como você interage com os dados.

Sem essa conexão, a IA até pode ajudar a escrever SQL, mas tudo fica mais abstrato. Você precisa explicar melhor o cenário, copiar estrutura de tabela, informar nomes de campos e revisar muito mais o que foi gerado. Com o MCP ativo, o Claude passa a operar com mais contexto do ambiente real.

É importante entender uma coisa. O valor dessa integração não está só em fazer perguntas em linguagem natural. O valor está em aproximar a pergunta de negócio do dado real, dentro de um fluxo de trabalho mais natural para quem já usa VS Code, terminal e ferramentas de dados no dia a dia.

Prefere aprender vendo na prática?

Se você preferir acompanhar tudo visualmente, com terminal, autenticação e testes acontecendo em tempo real, este conteúdo também está no vídeo do canal. O artigo funciona como apoio editorial. O vídeo ajuda a enxergar melhor a ordem das ações e os pontos em que normalmente aparecem dúvidas.

https://www.youtube.com/watch?v=4kHK8aebCOg

Como usar Claude Code para análise de dados no BigQuery

Essa abordagem tende a fazer mais sentido em alguns cenários específicos.

Ela é especialmente útil para quem já trabalha com BigQuery e quer acelerar etapas como exploração inicial da base, geração de consultas, entendimento de tabelas, revisão de caminhos analíticos e testes rápidos de hipóteses. Também ajuda bastante quem quer centralizar mais do trabalho dentro do VS Code, sem depender de ficar pulando entre interfaces o tempo todo.

Na prática, costuma ser interessante para:

• analistas de dados que fazem muitas consultas exploratórias

• profissionais de BI que querem ganhar agilidade na fase inicial da análise

• times que já usam BigQuery como base principal

• pessoas que querem começar a estruturar um fluxo de IA com mais contexto real

• quem pretende evoluir depois para dashboards, automações ou fluxos mais sofisticados

O ganho analítico aqui é bem objetivo. Você reduz o tempo entre a dúvida e a primeira consulta útil. Também passa a depender menos de memória operacional, como lembrar nomes de colunas, datasets ou tabelas o tempo todo. Em bases maiores, isso faz diferença de verdade.

Não é uma solução mágica. Se o banco estiver desorganizado, se os nomes estiverem ruins ou se as regras de negócio não estiverem claras, isso continua pesando. Mas com uma base minimamente estruturada, o ganho de produtividade e a qualidade da exploração inicial podem melhorar bastante.

O que você precisa ter pronto antes de configurar o Claude Code com BigQuery

Antes de partir para os comandos, vale garantir que o ambiente tenha o básico funcionando. Essa preparação evita muito retrabalho.

Google Cloud SDK instalado

O Google Cloud SDK é o que permite usar comandos como gcloud --version e gcloud auth login. Sem ele, você não consegue autenticar corretamente a conta que vai acessar o projeto no BigQuery.

Node.js instalado

O Node.js também faz parte do ambiente necessário para esse tipo de setup. No fluxo mostrado no vídeo, ele é validado logo no começo para garantir que o ambiente está pronto para seguir.

VS Code e Claude Code configurados

Como todo o processo acontece no fluxo do editor e do terminal, faz sentido já estar com o VS Code pronto e o Claude Code acessível no ambiente em que você pretende trabalhar.

Projeto no BigQuery com acesso liberado

Além das ferramentas locais, você precisa de um projeto no BigQuery com permissão adequada. Isso parece óbvio, mas é um dos pontos que mais causam erro no começo. Às vezes a ferramenta está instalada, o login foi feito, mas a conta usada não tem acesso ao projeto certo, ou não tem permissão suficiente para consultar os dados.

Quando isso acontece, a pessoa acha que o MCP falhou, quando na verdade o problema está na autenticação ou na permissão. O próprio Google destaca que o BigQuery usa IAM para controlar acesso a recursos e permissões.

Como validar o ambiente antes de conectar o Claude Code ao BigQuery

Antes de qualquer configuração mais específica, vale confirmar se o ambiente básico está funcionando. Essa validação inicial é simples, mas evita que você avance com algo quebrado.

No terminal do VS Code, rode:

gcloud --version

node -v

Se os dois comandos retornarem corretamente, você já sabe que o Cloud SDK e o Node.js estão acessíveis no ambiente.

Esse passo é importante porque muitos erros de setup começam antes da conexão em si. Se o terminal não reconhece gcloud, por exemplo, não adianta tentar autenticar. Se o Node não está instalado ou não está no PATH, o fluxo também pode falhar mais adiante.

Parece detalhe, mas não é. Em setup técnico, validar o básico economiza tempo.

Como fazer a autenticação da conta Google no setup do BigQuery

Com o ambiente validado, o próximo passo é autenticar a conta Google que tem acesso ao projeto do BigQuery.

O comando usado é:

gcloud auth login

Ao executar esse comando, o navegador abre para você concluir o login. Aqui existe um ponto muito importante, e que costuma passar despercebido por quem está fazendo o setup pela primeira vez.

Você precisa autenticar com a mesma conta que realmente tem acesso ao projeto e aos datasets que pretende usar.

Isso porque, mesmo com tudo instalado corretamente, a experiência pode dar errado se a conta estiver incorreta. O Claude pode até conseguir iniciar a conexão, mas depois não encontra o projeto, não lê a estrutura certa ou falha ao tentar consultar as tabelas.

Se algo parecer estranho mais adiante, este é um dos primeiros pontos que eu revisaria.

Como adicionar o MCP do BigQuery no Claude Code

Com o ambiente validado e a conta autenticada, chega o momento de adicionar a conexão do BigQuery no Claude Code.

No terminal, o comando mostrado no fluxo é:

cloud mcp add bigquery

Ao rodar esse comando, o processo pode pedir confirmações na tela. No vídeo, essas aprovações aparecem durante a configuração, e é preciso seguir o fluxo indicado no terminal para concluir corretamente.

Depois disso, vale validar se a conexão foi registrada. Para isso, use:

cloud mcp list

A ideia aqui é confirmar que o servidor relacionado ao BigQuery está conectado e pronto para uso. Esse é o ponto em que a integração deixa de ser só intenção e passa a existir no ambiente. A partir daqui, já faz sentido começar os primeiros testes, mas ainda tem uma camada importante que muita gente ignora: contexto.

Por que só conectar o BigQuery não basta para ter boas respostas

Esse é um ponto importante. Muita gente faz a conexão e já espera que a IA entenda perfeitamente o projeto, as tabelas, as regras de negócio e a lógica da operação. Na prática, não funciona assim. Conectar o banco é uma parte do processo. Dar contexto é outra.

Se você não orientar minimamente o ambiente, o Claude Code pode até gerar consultas, mas tende a pedir mais informações do que deveria, ou trabalhar com interpretações muito genéricas da base. É justamente por isso que o claud.md e as Skills entram como peças importantes.

Como melhorar a qualidade das análises com Claude Code, claud.md e Skills

Quando se fala em análise de dados com IA, muita gente pensa primeiro no prompt. Mas o que realmente melhora a qualidade da experiência não é só a pergunta. É a combinação entre conexão, contexto e instrução.

Como usar o arquivo claud.md para melhorar o contexto do Claude Code

O claud.md funciona como um arquivo de contexto do projeto. Em vez de repetir em toda conversa qual é o projeto, quais tabelas são principais, quais regras de negócio precisam ser respeitadas e como a análise deve ser conduzida, você pode centralizar isso em um lugar mais organizado.

Na prática, esse arquivo pode incluir informações como:

• ID do projeto no BigQuery

• descrição das tabelas principais

• significado de colunas importantes

• filtros que sempre devem ser considerados

• regras de negócio que a IA não deve ignorar

• instruções sobre o tipo de resposta esperado

Isso faz muita diferença.

Imagine, por exemplo, uma base de pedidos em que receita só deve considerar pedidos entregues. Se isso não estiver claro, a IA pode montar uma consulta tecnicamente válida, mas errada do ponto de vista do negócio. O claud.md ajuda a reduzir esse tipo de problema.

Outro ganho é a consistência. Em vez de começar do zero toda vez, você cria uma base de orientação que acompanha o projeto e melhora o comportamento do Claude ao longo do uso.

Como as Skills ajudam a melhorar as análises com Claude Code

Além do contexto do projeto, o outro ponto que eleva bastante a qualidade da experiência são as Skills.

As Skills funcionam como instruções mais especializadas para guiar a forma como o Claude executa determinadas tarefas. Em um cenário de dados, isso pode significar, por exemplo, orientar o modelo a sempre estruturar melhor a resposta, gerar SQL antes de responder, organizar o resultado em tabela ou seguir um padrão mais analítico.

Isso é útil porque reduz respostas soltas ou pouco consistentes. Em vez de depender só da pergunta feita naquele momento, você passa a contar também com um comportamento mais orientado. Na prática, é como se o Claude recebesse uma direção mais clara sobre como trabalhar. O que realmente melhora a análise no dia a dia

O ponto central é este:

• o MCP faz a ponte com a ferramenta

• o claud.md dá contexto do projeto

• as Skills orientam a forma de atuação

Quando essas três partes estão alinhadas, a qualidade do uso melhora bastante. Você reduz consultas mal direcionadas, evita retrabalho e aumenta a chance de a resposta já vir mais próxima do que o negócio realmente precisa.

Como testar a primeira consulta no Claude Code com BigQuery

Depois de conectar o ambiente e organizar o contexto, você já pode partir para uma primeira consulta.

Aqui, o ideal é começar com algo simples e objetivo. Uma pergunta muito aberta logo de cara pode gerar ruído, principalmente se a base tiver várias tabelas ou se o projeto ainda estiver com pouco contexto documentado.

Perguntas como estas já ajudam bastante:

• quais foram os produtos mais vendidos no último mês

• quais canais tiveram maior receita no período

• qual vendedor teve melhor desempenho na última semana

• quais categorias cresceram mais em faturamento

O ponto mais interessante desse fluxo é justamente o encadeamento. Quando tudo está funcionando, o Claude tende a entender a intenção da pergunta, consultar a estrutura necessária, gerar SQL, executar a consulta via MCP e devolver os dados já organizados para leitura inicial. Isso reduz bastante o tempo entre a dúvida e o primeiro insight.

O que fazer quando o Claude Code não encontra o projeto ou o dataset

Esse é um dos problemas mais comuns no começo, e também um dos mais frustrantes.

Você faz o setup, roda os comandos, a conexão aparentemente existe, mas na hora da consulta o Claude pede o Project ID, o Dataset ID ou simplesmente não aponta para a estrutura certa. Na maior parte das vezes, isso não significa que tudo falhou. O que falta é contexto mais explícito.

Uma saída imediata é informar diretamente no prompt qual projeto deve ser usado. Outra prática melhor é registrar isso no claud.md, para evitar repetição e dar mais consistência ao ambiente.

Se esse erro aparecer, eu revisaria estes pontos primeiro:

• Conta autenticada errada: Às vezes o gcloud auth login foi feito com uma conta Google que não é a mesma do projeto.

• Permissões insuficientes no BigQuery: A conta está correta, mas não tem permissão suficiente para consultar os dados necessários.

• Falta de contexto no projeto: A conexão existe, mas o Claude não sabe com clareza qual projeto, dataset ou tabela priorizar.

• Arquivo claud.md pouco útil: Se o arquivo está vazio, genérico ou mal organizado, ele ajuda pouco.

Em outras palavras, quando o Claude não encontra o projeto ou o dataset, o problema nem sempre está no MCP. Muitas vezes está no entorno da conexão.

Erros comuns no setup de Claude Code com BigQuery

Ao olhar para esse tipo de configuração, existem alguns erros que se repetem bastante.

O primeiro é tentar avançar sem validar o ambiente. Isso costuma gerar confusão porque a pessoa já vai direto para autenticação ou conexão, sem confirmar se gcloud e node estão funcionando.

O segundo é usar a conta errada na autenticação. Esse talvez seja o erro mais clássico de todos.

O terceiro é esperar que a conexão sozinha resolva o problema de contexto. Não resolve. Sem regras claras, sem tabelas descritas e sem um mínimo de orientação no projeto, a experiência tende a ficar muito mais inconsistente.

O quarto é não revisar o que foi retornado. Mesmo quando o Claude gera uma boa consulta, continua sendo importante validar o raciocínio, especialmente em análises mais sensíveis.

No fim, a IA acelera bastante a execução. Mas ela não elimina a necessidade de pensamento analítico e revisão.

Por que Claude Code com BigQuery pode ser uma opção mais segura para análise de dados

Quando se fala em segurança, o melhor caminho é evitar promessas absolutas.

O ponto aqui não é dizer que essa abordagem é automaticamente segura em qualquer cenário. O mais correto é dizer que, em muitos casos, ela pode ser mais controlada e mais segura do que fluxos manuais, como exportar CSV, copiar trechos de tabelas ou colar dados em ferramentas de IA sem governança.

A diferença está no desenho da operação.

Em vez de espalhar dados manualmente entre ferramentas, você trabalha com uma conexão ao ambiente já configurado, usando autenticação e permissões do ecossistema onde os dados já vivem. Na prática, isso tende a reduzir a exposição manual de informações e criar um fluxo mais governável para análise de dados.

Esse modelo ganha força principalmente quando o ambiente está bem configurado. Isso passa por alguns pontos básicos:

• conta autenticada correta

• permissões bem definidas no Google Cloud

• aplicação do princípio do menor privilégio

• cuidado com o tipo de dado consultado

• controle sobre quem pode acessar a máquina, o projeto e os datasets

• atenção à forma como o contexto do projeto é organizado

Outro ponto importante é que o BigQuery permite trabalhar com controle de acesso mais granular. Isso ajuda a estruturar um ambiente em que cada usuário acessa apenas o que realmente precisa, com permissões revisadas de acordo com a função. Em contextos corporativos, isso costuma ser muito mais adequado do que depender de processos improvisados de copiar e colar dados entre ferramentas.

Além disso, o ecossistema do Google Cloud oferece recursos de logs e auditoria, o que melhora rastreabilidade e governança. Isso não significa que todo ambiente estará perfeitamente auditado por padrão, mas já oferece uma base mais robusta de controle do que fluxos manuais espalhados em arquivos, exports e uploads pontuais.

Então, Claude Code com BigQuery pode sim ser uma opção mais segura para análise de dados, principalmente quando comparado a abordagens mais manuais. Mas essa segurança depende diretamente de como o ambiente foi configurado, de quem tem acesso e do nível de maturidade da governança adotada.

Se você estiver lidando com dados sensíveis ou com um ambiente corporativo mais crítico, vale ir além do login pessoal e revisar com mais cuidado acessos, políticas internas e modelos mais controlados de autenticação.

Limitações dessa abordagem com IA para análise de dados

Vale também ajustar a expectativa. Conectar Claude Code ao BigQuery via MCP não significa que toda análise passa a ser automática, nem que a qualidade da resposta ficará sempre alta por padrão. O que essa abordagem faz é reduzir fricção e ganhar velocidade nas etapas iniciais e intermediárias do trabalho.

Os limites continuam existindo. Se a base estiver mal organizada, a IA vai sofrer. Se as regras de negócio estiverem implícitas e nunca documentadas, o risco de interpretação ruim continua existindo. Se a pergunta for vaga demais, a resposta pode sair genérica.

Por isso, o melhor jeito de encarar esse setup é como uma camada de produtividade. Ele te ajuda a trabalhar melhor com os dados, mas não substitui organização, modelagem e raciocínio analítico.

Vale a pena usar Claude Code com BigQuery no dia a dia?

Na minha visão, sim, principalmente para quem já trabalha com BigQuery e quer ganhar fluidez.

O grande ganho não está em ter IA no processo por si só. Está em encurtar a distância entre uma dúvida de negócio e uma consulta útil. Quando você combina conexão, contexto e instruções bem definidas, a interação com a base fica mais natural e muito menos travada.

Esse tipo de fluxo também abre caminho para outras evoluções. Depois que a estrutura está pronta, faz muito mais sentido partir para coisas como geração de dashboards, criação de aplicações simples, automações analíticas e experiências mais avançadas com dados.

Próximo passo depois do setup com Claude Code e BigQuery

Depois de conectar o Claude Code ao BigQuery, o próximo movimento natural é transformar essa base em algo visual.

É exatamente isso que entra no próximo conteúdo. A ideia é aproveitar a conexão já feita para gerar um dashboard com Claude Code, BigQuery e Apps Script, usando a IA para criar a estrutura do painel e publicar uma interface funcional.

Ou seja, este artigo resolve a etapa de conexão. O próximo resolve a etapa de visualização.

Perguntas Frequentes (FAQ)

O Claude Code é gratuito? E o BigQuery?

O Claude Code (a ferramenta de linha de comando) faz parte do ecossistema da Anthropic e, atualmente, consome créditos da sua API ou do seu plano profissional. Já o BigQuery possui um Always Free Tier (limite gratuito) de 1TB de consultas por mês e 10GB de armazenamento. Fique atento: se o Claude gerar uma query pesada em um dataset gigante, isso consumirá sua cota do Google Cloud.

Posso usar essa conexão no Windows, Mac e Linux?

Sim. Como o setup depende de Node.js e Google Cloud SDK, ele é multiplataforma. No vídeo, mostramos o processo no VS Code, que padroniza a experiência independente do seu sistema operacional. Se você usa Windows, recomendo fortemente utilizar o terminal PowerShell ou o WSL2 para evitar conflitos de permissão de pasta.

Qual a diferença entre usar o Claude Code com MCP e o Cursor ou ChatGPT?

Enquanto o ChatGPT exige que você suba arquivos (CSV/Excel) e o Cursor foca muito em escrita de código, o Claude Code com MCP é focado em interação com o ecossistema. Ele não apenas "escreve" o SQL; ele executa, lê o resultado, interpreta e ajusta a consulta em tempo real sem você sair do terminal. É o fluxo mais próximo de ter um analista sênior sentado ao seu lado.

O Claude aprende com meus dados privados do BigQuery?

Não. Essa é uma dúvida de segurança fundamental. Quando você usa o MCP localmente, o Claude Code envia apenas o contexto da consulta e os resultados retornados para processar o insight. Os dados não são usados para treinar o modelo global da Anthropic. No entanto, sempre siga as políticas de governança de dados da sua empresa.

O arquivo claud.md é obrigatório?

Obrigatório, no sentido técnico, não. Mas na prática ele ajuda muito. Sem esse arquivo, o Claude tende a operar com menos contexto e a pedir mais explicações ao longo do uso.

Como eu atualizo o servidor MCP do BigQuery se sair uma versão nova?

Diferente de softwares comuns, para atualizar conectores MCP você geralmente roda o comando de adição novamente ou atualiza o pacote via NPM, caso tenha instalado manualmente. No terminal do Claude, você pode rodar cloud mcp add bigquery novamente para garantir que está na última versão estável.

Consigo conectar outros bancos de dados (Postgres, SQL Server, MySQL) além do BigQuery?

Sim! O protocolo MCP é universal. Existem servidores MCP para quase todos os bancos modernos. O processo de "ponte" é o mesmo, mudando apenas o conector e a forma de autenticação (que no caso do BigQuery é facilitada pelo Google SDK).

🌟 Seja Membro do TheBILab - É Gratuito

Tenha acesso a uma área exclusiva com minicursos, eBooks e materiais sobre dados, IA e automação. Receba no seu e-mail, toda semana, os melhores conteúdos para se manter atualizado.➡️ Quero Ser Membro

🎥 Aprenda na prática com nossos vídeos no YouTube

Assista tutoriais, estudos de caso e aulas rápidas sobre como criar dashboards, usar IA e aplicar dados no dia a dia. ➡️ Acessar Canal

🤝 Soluções para empresas que querem ir além com dados e IA

O TheBILab oferece palestras, mentorias e serviços em Análise de Dados, IA, Web Analytics, Automação e muito mais.➡️ Fale com a Gente