Esta página foi traduzida pela API Cloud Translation.

Conectar LLMs ao BigQuery com a MCP

Neste guia, você vai aprender a 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
Antigravity

Antes de começar

No console do Google Cloud , na página do seletor de projetos, selecione ou crie um projeto do Google Cloud .
Verifique se o faturamento está ativado para o projeto do Google Cloud .
Ative a API BigQuery no Google Cloud projeto.
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 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.

Conectar com o 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.

Abra o Antigravity e o painel do agente do editor.
Clique no ícone "..." na parte de cima do painel e selecione Servidores MCP.
Localize BigQuery na lista de servidores disponíveis e clique em Instalar.
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:

Abra o Antigravity e navegue até a loja da MCP usando o menu suspenso "..." na parte de cima do painel do agente do editor.
Para abrir o arquivo mcp_config.json, clique em Servidores MCP e em Gerenciar servidores MCP > Ver configuração bruta.
Adicione a seguinte configuração, 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 a caixa de ferramentas do MCP se você pretende usar apenas as extensões da CLI do Gemini do 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 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 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 ele for reaberto, 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 para computador.
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 ativo verde 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 Google Cloud 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.

Conectar LLMs ao BigQuery com a MCP

Antes de começar

Conectar com o Antigravity

Loja do MCP

Configuração personalizada

Instalar a MCP Toolbox

linux/amd64

macOS darwin/arm64

macOS darwin/amd64

windows/amd64

Configurar clientes e conexões

Código do Claude

Claude para computador

Cline

Cursor

Visual Studio Code (Copilot)

Windsurf

Usar as ferramentas