Conectar LLMs ao BigQuery com a MCP

Este guia mostra como usar a MCP Toolbox for Databases para 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
  • Antigravity

Antes de começar

  1. No console do Google Cloud , na página do seletor de projetos, selecione ou crie um projeto do Google Cloud .

  2. Verifique se o faturamento está ativado para o projeto do Google Cloud .

  3. Ative a API BigQuery no Google Cloud projeto.

  4. Configure os papéis e as permissões necessárias para concluir essa tarefa. Você vai precisar da função Usuário do BigQuery (roles/bigquery.user), da função Visualizador de dados do BigQuery (roles/bigquery.dataViewer) ou de permissões equivalentes do IAM para se conectar ao projeto.

  5. Configure as Application Default Credentials (ADC) para seu ambiente.

Conectar-se ao Antigravity

É possível conectar o BigQuery ao Antigravity das seguintes maneiras:

  • Como usar a loja do MCP
  • Usar uma configuração personalizada

Observação:não é necessário fazer o download do binário da MCP Toolbox para usar esses métodos.

Loja do MCP

A maneira mais simples de se conectar ao BigQuery no Antigravity é usando a MCP Store integrada.

  1. Abra o Antigravity e o painel do agente do editor.
  2. Clique no ícone "..." na parte de cima do painel e selecione Servidores MCP.
  3. Localize BigQuery na lista de servidores disponíveis e clique em Instalar.
  4. Siga as instruções na tela para vincular suas contas com segurança, quando aplicável.

Depois de instalar o BigQuery na MCP Store, os recursos e as ferramentas do servidor ficam disponíveis automaticamente para o editor.

Configuração personalizada

Para se conectar a um servidor MCP personalizado, siga estas etapas:

  1. Abra o Antigravity e navegue até a loja da MCP usando o menu suspenso "..." na parte de cima do painel do agente do editor.
  2. Para abrir o arquivo mcp_config.json, clique em Servidores MCP e em Gerenciar servidores MCP > Ver configuração bruta.
  3. Adicione a configuração a seguir, substitua a variável de ambiente pelos seus valores e salve.
{
  "mcpServers": {
    "bigquery": {
      "command": "npx",
      "args": ["-y","@toolbox-sdk/server","--prebuilt","bigquery","--stdio"],
      "env": {
          "BIGQUERY_PROJECT": "PROJECT_ID"
      }
    }
  }
}

Instalar a MCP Toolbox

Não é necessário instalar o MCP Toolbox se você pretende usar apenas as extensões da CLI do Gemini para BigQuery, já que elas incluem 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 de Protocolo de Contexto de Modelo (MCP) de código aberto que fica entre seu IDE e o BigQuery, fornecendo um plano de controle seguro e eficiente para suas ferramentas de IA.

  1. 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 e arquitetura de 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/mcp-toolbox-for-databases/VERSION/linux/amd64/toolbox

    Substitua VERSION pela versão da caixa de ferramentas do MCP. Por exemplo, v1.14.0.

    macOS darwin/arm64

    curl -O https://storage.googleapis.com/mcp-toolbox-for-databases/VERSION/darwin/arm64/toolbox

    Substitua VERSION pela versão da caixa de ferramentas do MCP. Por exemplo, v1.14.0.

    macOS darwin/amd64

    curl -O https://storage.googleapis.com/mcp-toolbox-for-databases/VERSION/darwin/amd64/toolbox

    Substitua VERSION pela versão da caixa de ferramentas do MCP. Por exemplo, v1.14.0.

    windows/amd64

    curl -O https://storage.googleapis.com/mcp-toolbox-for-databases/VERSION/windows/amd64/toolbox

    Substitua VERSION pela versão da caixa de ferramentas do MCP. Por exemplo, v1.14.0.

  2. Torne o binário executável:

    chmod +x toolbox

  3. 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, já que o pacote de extensões inclui 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

  1. Instale o Claude Code.
  2. Crie um arquivo .mcp.json na raiz do projeto, se ele não existir.
  3. 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"
              }
            }
          }
        }
  4. Reinicie o Claude Code para carregar as novas configurações. Quando ele for reaberto, a ferramenta vai indicar que o servidor MCP configurado foi detectado.

Claude para computador

  1. Abra o Claude para computador e acesse Configurações.
  2. Na guia Desenvolvedor, clique em Editar configuração para abrir o arquivo de configuração.
  3. 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"
              }
            }
          }
        }
  4. Reinicie o Claude Desktop.
  5. A nova tela de chat mostra 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 arquivo de configuração.
  3. Adicione a configuração a seguir, 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

  1. Crie o diretório .cursor na raiz do projeto, se ele não existir.
  2. Crie o arquivo .cursor/mcp.json se ele não existir e abra-o.
  3. Adicione a configuração a seguir, 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"
              }
            }
          }
        }
  4. 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)

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

Windsurf

  1. Abra o Windsurf e navegue até o assistente do Cascade.
  2. Clique no ícone do MCP e em Configurar para abrir o arquivo de configuração.
  3. Adicione a configuração a seguir, 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 Google Cloud padrão que a MCP Toolbox vai usar. 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 conjuntos de dados.
  • list_table_ids: lista tabelas.
  • search_catalog: pesquisa uma tabela usando linguagem natural.