Usar o BigQuery com o MCP, a CLI do Gemini e outros agentes
Neste guia, mostramos 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. Assim, você pode executar consultas SQL e interagir com seu projeto diretamente nas ferramentas atuais.
Se você usa a CLI do Gemini, pode usar as extensões do BigQuery. Para saber como fazer isso, 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 Trusted Cloud , na página do seletor de projetos, selecione ou crie um projeto do Trusted Cloud by S3NS .
Verifique se o faturamento está ativado para seu projeto do Trusted Cloud .
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 caixa de ferramentas do MCP se você pretende usar apenas as extensões da CLI do Gemini no BigQuery, porque 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
VERSION
pela versão da MCP Toolbox. Por exemplo,v0.7.0
.macOS darwin/arm64
curl -O https://storage.googleapis.com/genai-toolbox/VERSION/darwin/arm64/toolbox
Substitua
VERSION
pela 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
VERSION
pela versão da MCP Toolbox. Por exemplo,v0.7.0
.windows/amd64
curl -O https://storage.googleapis.com/genai-toolbox/VERSION/windows/amd64/toolbox
Substitua
VERSION
pela versão da MCP Toolbox. Por exemplo,v0.7.0
.Torne o binário executável:
chmod +x toolbox
Verifique 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 as extensões agrupam 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.json
na 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
.cursor
na 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 verde ativo aparece quando o servidor se conecta.
Visual Studio Code (Copilot)
- Abra o
VS Code
e crie um diretório
.vscode
na 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_PROJECT
especifica o ID do projeto Trusted Cloud padrão para uso da caixa de ferramentas do MCP. 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 o 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.