Conectar LLMs ao BigQuery com a MCP
Este guia mostra como usar a MCP Toolbox para bancos de dados e conectar seu projeto do BigQuery a vários ambientes de desenvolvimento integrado (IDEs) e ferramentas para desenvolvedores. Ele usa o Protocolo de Contexto de Modelo (MCP), um protocolo aberto para conectar modelos de linguagem grandes (LLMs) a fontes de dados como o BigQuery, permitindo que você execute consultas SQL e interaja com seu projeto diretamente das ferramentas atuais.
Se você usa a CLI do Gemini, pode usar as extensões do BigQuery. Para saber como, consulte Desenvolver com a CLI do Gemini. Se você planeja criar ferramentas personalizadas para a CLI do Gemini, continue lendo.
Este guia demonstra o processo de conexão para os seguintes IDEs:
- Cursor
- Windsurf (antigo Codeium)
- Visual Studio Code (Copilot)
- Cline (extensão do VS Code)
- Claude para computador
- Código do Claude
Antes de começar
No console do Cloud de Confiance , na página do seletor de projetos, selecione ou crie um projeto do Cloud de Confiance by S3NS .
Verifique se o faturamento está ativado para o projeto do Cloud de Confiance .
Configure os papéis e as permissões necessárias para concluir essa tarefa. Você vai precisar do papel Usuário do BigQuery (
roles/bigquery.user), do papel Leitor de dados do BigQuery (roles/bigquery.dataViewer) ou de permissões equivalentes do IAM para se conectar ao projeto.Configure as Credenciais padrão do aplicativo (ADC) para seu ambiente.
Instalar a MCP Toolbox
Não é necessário instalar a MCP Toolbox se você pretende usar apenas as extensões da CLI do Gemini para BigQuery, já que elas agrupam os recursos necessários do servidor. Para outros ambientes de desenvolvimento integrado e ferramentas, siga as etapas desta seção para instalar a MCP Toolbox.
A caixa de ferramentas funciona como um servidor Protocolo de Contexto de Modelo (MCP) de código aberto que fica entre seu ambiente de desenvolvimento integrado (IDE) e o BigQuery, fornecendo um plano de controle seguro e eficiente para suas ferramentas de IA.
Faça o download da versão mais recente da MCP Toolbox como um binário. Selecione o binário correspondente ao seu sistema operacional (SO) e à arquitetura da CPU. Use a versão V0.7.0 ou mais recente da caixa de ferramentas do MCP:
linux/amd64
curl -O https://storage.googleapis.com/genai-toolbox/VERSION/linux/amd64/toolbox
Substitua
VERSIONpela versão da caixa de ferramentas do MCP. Por exemplo,v0.7.0.macOS darwin/arm64
curl -O https://storage.googleapis.com/genai-toolbox/VERSION/darwin/arm64/toolbox
Substitua
VERSIONpela versão da MCP Toolbox. Por exemplo,v0.7.0.macOS darwin/amd64
curl -O https://storage.googleapis.com/genai-toolbox/VERSION/darwin/amd64/toolbox
Substitua
VERSIONpela versão da caixa de ferramentas do MCP. Por exemplo,v0.7.0.windows/amd64
curl -O https://storage.googleapis.com/genai-toolbox/VERSION/windows/amd64/toolbox
Substitua
VERSIONpela versão da MCP Toolbox. Por exemplo,v0.7.0.Torne o binário executável:
chmod +x toolboxVerifique a instalação:
./toolbox --version
Configurar clientes e conexões
Esta seção explica como conectar o BigQuery às suas ferramentas.
Se você estiver usando a CLI do Gemini independente, não será necessário instalar ou configurar a caixa de ferramentas do MCP, porque os pacotes de extensões incluem os recursos necessários do servidor.
Para outras ferramentas e IDEs compatíveis com o MCP, primeiro instale o MCP Toolbox.
Código do Claude
- Instale o Claude Code.
- Crie um arquivo
.mcp.jsonna raiz do projeto, se ele não existir. - Adicione a configuração, substitua as variáveis de ambiente pelos seus
valores e salve:
{ "mcpServers": { "bigquery": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","bigquery","--stdio"], "env": { "BIGQUERY_PROJECT": "PROJECT_ID" } } } } - Reinicie o Claude Code para carregar as novas configurações. Quando ela for reaberta, a ferramenta vai indicar que o servidor MCP configurado foi detectado.
Claude para computador
- Abra o Claude para computador e acesse Configurações.
- Na guia Desenvolvedor, clique em Editar configuração para abrir o arquivo de configuração.
- Adicione a configuração, substitua as variáveis de ambiente pelos seus
valores e salve:
{ "mcpServers": { "bigquery": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","bigquery","--stdio"], "env": { "BIGQUERY_PROJECT": "PROJECT_ID" } } } } - Reinicie o Claude Desktop.
- A nova tela de chat mostra um ícone de martelo (MCP) com o novo servidor MCP.
Cline
- Abra a extensão Cline no VS Code e toque no ícone Servidores MCP.
- Toque em Configurar servidores MCP para abrir o arquivo de configuração.
- Adicione a seguinte configuração, substitua as variáveis de ambiente
pelos seus valores e salve:
{ "mcpServers": { "bigquery": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","bigquery","--stdio"], "env": { "BIGQUERY_PROJECT": "PROJECT_ID" } } } }
Um status ativo verde aparece depois que o servidor se conecta.
Cursor
- Crie o diretório
.cursorna raiz do projeto se ele não existir. - Crie o arquivo
.cursor/mcp.json, se ele não existir, e abra-o. - Adicione a seguinte configuração, substitua as variáveis de ambiente
pelos seus valores e salve:
{ "mcpServers": { "bigquery": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","bigquery","--stdio"], "env": { "BIGQUERY_PROJECT": "PROJECT_ID" } } } } - Abra Cursor e navegue até Configurações > Configurações do cursor > MCP. Um status ativo verde aparece quando o servidor se conecta.
Visual Studio Code (Copilot)
- Abra o
VS Code
e crie um diretório
.vscodena raiz do projeto, se ele não existir. - Crie o arquivo
.vscode/mcp.json, se ele não existir, e abra-o. - Adicione a seguinte configuração, substitua as variáveis de ambiente
pelos seus valores e salve:
{ "servers": { "bigquery": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","bigquery","--stdio"], "env": { "BIGQUERY_PROJECT": "PROJECT_ID" } } } } - Atualize a janela do VS Code. A extensão compatível com MCP detecta automaticamente a configuração e inicia o servidor.
Windsurf
- Abra o Windsurf e navegue até o assistente do Cascade.
- Clique no ícone do MCP e em Configurar para abrir o arquivo de configuração.
- Adicione a seguinte configuração, substitua as variáveis de ambiente
pelos seus valores e salve:
{ "mcpServers": { "bigquery": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","bigquery","--stdio"], "env": { "BIGQUERY_PROJECT": "PROJECT_ID" } } } }
Observação:a variável de ambiente
BIGQUERY_PROJECTespecifica o ID do projeto Cloud de Confiance padrão para uso da MCP Toolbox. Todas as operações do BigQuery, como a execução de consultas, são realizadas nesse projeto.
Usar as ferramentas
Sua ferramenta de IA agora está conectada ao BigQuery usando a MCP. Peça ao assistente de IA para listar tabelas, criar uma tabela ou definir e executar outras instruções SQL.
As seguintes ferramentas estão disponíveis para o LLM:
- analyze_contribution: realiza a análise de contribuição, também chamada de análise de principais fatores.
- ask_data_insights: realiza análises de dados, gera insights ou responde a perguntas complexas sobre o conteúdo das tabelas do BigQuery.
- execute_sql: executa uma instrução SQL.
- forecast: prevê dados de série temporal.
- get_dataset_info: recebe metadados do conjunto de dados.
- get_table_info: recebe metadados da tabela.
- list_dataset_ids: lista os conjuntos de dados.
- list_table_ids: lista tabelas.
- search_catalog: pesquisa uma tabela usando linguagem natural.