Use o BigQuery com o MCP, o Gemini CLI e outros agentes
Este guia mostra-lhe como usar a caixa de ferramentas do MCP para bases de dados para associar o seu projeto do BigQuery a vários ambientes de desenvolvimento integrados (IDEs) e ferramentas para programadores. Usa o Model Context Protocol (MCP), um protocolo aberto para ligar modelos de linguagem grandes (LLMs) a origens de dados como o BigQuery, o que lhe permite executar consultas SQL e interagir com o seu projeto diretamente a partir das suas ferramentas existentes.
Se usar a Gemini CLI, pode usar extensões do BigQuery. Para saber como, consulte o artigo Desenvolva com a CLI do Gemini. Se planeia criar ferramentas personalizadas para a Gemini CLI, continue a ler.
Este guia demonstra o processo de associação para os seguintes IDEs:
- Cursor
- Windsurf (anteriormente Codeium)
- Visual Studio Code (Copilot)
- Cline (extensão do VS Code)
- Claude para computador
- Código do Claude
Antes de começar
Na Cloud de Confiance consola, na página do seletor de projetos, selecione ou crie um Cloud de Confiance by S3NS projeto.
Certifique-se de que a faturação está ativada para o seu Cloud de Confiance projeto.
Configure as funções e as autorizações necessárias para concluir esta tarefa. Precisa da função de utilizador do BigQuery (
roles/bigquery.user
), da função de visualizador de dados do BigQuery (roles/bigquery.dataViewer
) ou de autorizações do IAM equivalentes para estabelecer ligação ao projeto.Configure as Credenciais padrão da aplicação (ADC) para o seu ambiente.
Instale a caixa de ferramentas do MCP
Não precisa de instalar a MCP Toolbox se planear usar apenas as extensões da CLI do Gemini do BigQuery, uma vez que incluem as capacidades do servidor necessárias. Para outros IDEs e ferramentas, siga os passos nesta secção para instalar a MCP Toolbox.
O conjunto de ferramentas funciona como um servidor de protocolo Model Context Protocol (MCP) de código aberto que se encontra entre o seu IDE e o BigQuery, oferecendo um plano de controlo seguro e eficiente para as suas ferramentas de IA.
Transfira a versão mais recente da caixa de ferramentas do MCP como um ficheiro binário. Selecione o ficheiro binário correspondente ao seu sistema operativo (SO) e arquitetura da CPU. Tem de usar a versão V0.7.0 ou posterior da MCP Toolbox:
linux/amd64
curl -O https://storage.googleapis.com/genai-toolbox/VERSION/linux/amd64/toolbox
Substitua
VERSION
pela 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
VERSION
pela versão da caixa de ferramentas do MCP, 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 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
VERSION
pela versão da caixa de ferramentas do MCP, por exemplo,v0.7.0
.Torne o executável binário:
chmod +x toolbox
Valide a instalação:
./toolbox --version
Configure clientes e associações
Esta secção explica como associar o BigQuery às suas ferramentas.
Se estiver a usar a Gemini CLI autónoma, não precisa de instalar nem configurar a MCP Toolbox, uma vez que as extensões agrupam as capacidades do servidor necessárias.
Para outras ferramentas e IDEs compatíveis com o MCP, tem de instalar primeiro o MCP Toolbox.
Código do Claude
- Instale o Claude Code.
- Crie um ficheiro
.mcp.json
na raiz do projeto, se ainda não existir. - Adicione a configuração, substitua as variáveis de ambiente pelos seus valores e guarde:
{ "mcpServers": { "bigquery": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","bigquery","--stdio"], "env": { "BIGQUERY_PROJECT": "PROJECT_ID" } } } }
- Reinicie o Claude Code para carregar as novas definições. Quando reabrir, a ferramenta indica que o servidor MCP configurado foi detetado.
Claude para computador
- Abra o Claude Desktop e navegue para Definições.
- No separador Programador, clique em Editar configuração para abrir o ficheiro de configuração.
- Adicione a configuração, substitua as variáveis de ambiente pelos seus valores e guarde:
{ "mcpServers": { "bigquery": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","bigquery","--stdio"], "env": { "BIGQUERY_PROJECT": "PROJECT_ID" } } } }
- Reinicie o Claude Desktop.
- O novo ecrã de chat apresenta 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 ficheiro de configuração.
- Adicione a seguinte configuração, substitua as variáveis de ambiente
pelos seus valores e guarde:
{ "mcpServers": { "bigquery": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","bigquery","--stdio"], "env": { "BIGQUERY_PROJECT": "PROJECT_ID" } } } }
É apresentado um estado ativo verde depois de o servidor se ligar com êxito.
Cursor
- Crie o diretório
.cursor
na raiz do projeto se não existir. - Cria o ficheiro
.cursor/mcp.json
se não existir e abre-o. - Adicione a seguinte configuração, substitua as variáveis de ambiente
pelos seus valores e guarde:
{ "mcpServers": { "bigquery": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","bigquery","--stdio"], "env": { "BIGQUERY_PROJECT": "PROJECT_ID" } } } }
- Abra o Cursor e navegue para Definições > Definições do cursor > MCP. É apresentado um estado ativo verde quando o servidor se liga.
Visual Studio Code (Copilot)
- Abra o
VS Code
e crie um diretório
.vscode
na raiz do projeto, se ainda não existir. - Crie o ficheiro
.vscode/mcp.json
se não existir e abra-o. - Adicione a seguinte configuração, substitua as variáveis de ambiente
pelos seus valores e guarde:
{ "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 deteta automaticamente a configuração e inicia o servidor.
Windsurf
- Abra o Windsurf e navegue para o assistente Cascade.
- Clique no ícone do MCP e, de seguida, clique em Configurar para abrir o ficheiro de configuração.
- Adicione a seguinte configuração, substitua as variáveis de ambiente
pelos seus valores e guarde:
{ "mcpServers": { "bigquery": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt","bigquery","--stdio"], "env": { "BIGQUERY_PROJECT": "PROJECT_ID" } } } }
Nota: a variável de ambiente
BIGQUERY_PROJECT
especifica o ID do projeto Cloud de Confiance predefinido que a caixa de ferramentas do MCP deve usar. Todas as operações do BigQuery, como a execução de consultas, são executadas neste projeto.
Use as ferramentas
A sua ferramenta de IA está agora ligada ao BigQuery através do MCP. Experimente pedir ao seu assistente de IA para listar tabelas, criar uma tabela ou definir e executar outras declarações SQL.
As seguintes ferramentas estão disponíveis para o GML:
- analyze_contribution: fazer a análise da contribuição, também denominada análise dos principais fatores.
- ask_data_insights: realizar análises de dados, obter estatísticas ou responder a perguntas complexas sobre o conteúdo das tabelas do BigQuery.
- execute_sql: executar declaração SQL.
- forecast: prevê dados de intervalos temporais.
- get_dataset_info: obter metadados do conjunto de dados.
- get_table_info: obter metadados da tabela.
- list_dataset_ids: listar conjuntos de dados.
- list_table_ids: lista as tabelas.
- search_catalog: pesquise uma tabela através da linguagem natural.