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

  1. Na Cloud de Confiance consola, na página do seletor de projetos, selecione ou crie um Cloud de Confiance by S3NS projeto.

  2. Certifique-se de que a faturação está ativada para o seu Cloud de Confiance projeto.

  3. Ative a API BigQuery no Cloud de Confiance projeto.

  4. 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.

  5. 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.

  1. 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.

  2. Torne o executável binário:

    chmod +x toolbox
    
  3. 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

  1. Instale o Claude Code.
  2. Crie um ficheiro .mcp.json na raiz do projeto, se ainda não existir.
  3. 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"
                  }
                }
              }
            }
            
  4. 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

  1. Abra o Claude Desktop e navegue para Definições.
  2. No separador Programador, clique em Editar configuração para abrir o ficheiro de configuração.
  3. 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"
                  }
                }
              }
            }
            
  4. Reinicie o Claude Desktop.
  5. O novo ecrã de chat apresenta um ícone de martelo (MCP) com o novo servidor MCP.

Cline

  1. Abra a extensão Cline no VS Code e toque no ícone Servidores MCP.
  2. Toque em Configurar servidores MCP para abrir o ficheiro de configuração.
  3. 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

  1. Crie o diretório .cursor na raiz do projeto se não existir.
  2. Cria o ficheiro .cursor/mcp.json se não existir e abre-o.
  3. 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"
                  }
                }
              }
            }
            
  4. 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)

  1. Abra o VS Code e crie um diretório .vscode na raiz do projeto, se ainda não existir.
  2. Crie o ficheiro .vscode/mcp.json se não existir e abra-o.
  3. 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"
                  }
                }
              }
            }
            
  4. Atualize a janela do VS Code. A extensão compatível com MCP deteta automaticamente a configuração e inicia o servidor.

Windsurf

  1. Abra o Windsurf e navegue para o assistente Cascade.
  2. Clique no ícone do MCP e, de seguida, clique em Configurar para abrir o ficheiro de configuração.
  3. 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.