Conectar LLMs ao Cloud Storage com o MCP

Neste guia, mostramos como conectar o Cloud Storage a ambientes de desenvolvimento integrado (IDEs) e ferramentas para desenvolvedores. Para isso, execute um servidor MCP local na sua máquina usando a MCP Toolbox for Databases.

A MCP Toolbox for Databases é um repositório de código aberto que contém conectores para bancos de dados e repositórios de dados, incluindo Cloud Storage, BigQuery, AlloyDB, Spanner e Cloud SQL. A caixa de ferramentas é compatível com a autenticação OAuth2 e OIDC e se integra ao Open Telemetry para observabilidade. Com a integração da caixa de ferramentas do Cloud Storage, é possível usar um LLM para realizar as seguintes ações:

  • Criar, listar e excluir buckets.
  • Receber metadados de buckets e objetos.
  • Acessar políticas do Identity and Access Management (IAM) nos seus buckets.
  • Ler, gravar, fazer upload e download de objetos.
  • Copie ou mova objetos.

Este guia demonstra o processo de conexão para os seguintes IDEs e ferramentas:

  • 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 Storage do Cloud Storage no Google Cloud projeto.

  4. Configure os papéis e as permissões necessárias para concluir essa tarefa. O usuário que invoca os agentes de LLM precisa das seguintes funções no nível do bucket ou do projeto:

    • Para listar, criar e excluir buckets vazios: Administrador do Storage (roles/storage.admin)
    • Para listar objetos, ler objetos, receber metadados de objetos ou metadados de buckets: Leitor de objetos do Storage (roles/storage.objectViewer)
    • Para gravar conteúdo em um objeto ou fazer upload dele: Criador de objetos do Storage (roles/storage.objectCreator)
    • Para copiar, mover ou excluir objetos: Administrador de objetos do Storage (roles/storage.objectAdmin)

  5. Configure as Credenciais padrão do aplicativo (ADC) para seu ambiente.

Conecte-se com o Antigravity

Você conecta o Cloud Storage ao Antigravity usando uma configuração personalizada. Nesse contexto, um servidor MCP personalizado é um servidor que você configura manualmente editando o arquivo de configuração (como mcp_config.json). Essa configuração manual é usada em vez da instalação do servidor diretamente do catálogo da MCP Store integrada.

Para configurar um servidor MCP personalizado, faça o seguinte:

  1. Execute npx --version no terminal para verificar se npx está instalado e configurado corretamente no seu sistema. Se você precisar instalar o Node.js, que inclui o npx, consulte o guia do npm Como fazer o download e instalar o Node.js e o npm.
  2. Abra o Antigravity e navegue até a loja do MCP usando o menu suspenso "..." na parte de cima do painel do agente do editor.
  3. Para abrir o arquivo mcp_config.json, clique em Servidores MCP e em Gerenciar servidores MCP > Ver configuração bruta.
  4. Adicione a seguinte configuração, substitua o marcador de posição pelo ID do projeto e salve: 
    {
  "mcpServers": {
    "storage": {
      "command": "npx",
      "args": ["-y","@toolbox-sdk/server","--prebuilt","cloud-storage","--stdio"],
      "env": {
          "CLOUD_STORAGE_PROJECT": "PROJECT_ID"
      }
    }
  }
}

Instalar a MCP Toolbox

A caixa de ferramentas é um servidor Protocolo de Contexto de Modelo (MCP) de código aberto que é executado localmente na sua máquina. O servidor local gerencia a comunicação entre o ambiente de desenvolvimento integrado e o Cloud Storage. Essa conexão oferece um ambiente 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 1.2.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 do MCP Toolbox. Por exemplo, v1.2.0.

    macOS darwin/arm64

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

    Substitua VERSION pela versão do MCP Toolbox. Por exemplo, v1.2.0.

    macOS darwin/amd64

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

    Substitua VERSION pela versão do MCP Toolbox. Por exemplo, v1.2.0.

    windows/amd64

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

    Substitua VERSION pela versão do MCP Toolbox. Por exemplo, v1.2.0.

  2. Torne o binário executável:

    chmod +x toolbox

  3. Verifique a instalação:

    ./toolbox --version

Para configurar a caixa de ferramentas com uma imagem de contêiner ou o Homebrew, consulte a página Instalar a caixa de ferramentas.

Configurar clientes e conexões

Esta seção descreve como conectar o Cloud Storage às suas ferramentas depois de instalar a Caixa de ferramentas do MCP.

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 os marcadores pelos seus valores e salve: 
            {
          "mcpServers": {
            "storage": {
              "command": "./PATH/TO/toolbox",
              "args": ["--prebuilt","cloud-storage","--stdio"],
              "env": {
                "CLOUD_STORAGE_PROJECT": "PROJECT_ID"
              }
            }
          }
        }
    Substitua as seguintes variáveis pelos seus valores:
    • ./PATH/TO/toolbox: o caminho para o binário toolbox.
    • CLOUD_STORAGE_PROJECT: a variável de ambiente que especifica o ID do projeto Google Cloud .
    • PROJECT_ID: o ID do projeto do Google Cloud .
  4. Reinicie o Claude Code para carregar as novas configurações. Quando o Claude Code reabrir, o aplicativo vai detectar o servidor MCP configurado.

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 os marcadores pelos seus valores e salve: 
            {
          "mcpServers": {
            "storage": {
              "command": "./PATH/TO/toolbox",
              "args": ["--prebuilt","cloud-storage","--stdio"],
              "env": {
                "CLOUD_STORAGE_PROJECT": "PROJECT_ID"
              }
            }
          }
        }
    Substitua as seguintes variáveis pelos seus valores:
    • ./PATH/TO/toolbox: o caminho para o binário toolbox.
    • CLOUD_STORAGE_PROJECT: a variável de ambiente que especifica o ID do projeto Google Cloud .
    • PROJECT_ID: o ID do projeto do Google Cloud .
  4. Reinicie o Claude para computador.
  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 clique no ícone Servidores MCP.
  2. Clique em Configurar servidores MCP para abrir o arquivo de configuração.
  3. Adicione a seguinte configuração, substitua os marcadores pelos seus valores e salve: 
            {
          "mcpServers": {
            "storage": {
              "command": "./PATH/TO/toolbox",
              "args": ["--prebuilt","cloud-storage","--stdio"],
              "env": {
                "CLOUD_STORAGE_PROJECT": "PROJECT_ID"
              }
            }
          }
        }
    Substitua as seguintes variáveis pelos seus valores:
    • ./PATH/TO/toolbox: o caminho para o binário toolbox.
    • CLOUD_STORAGE_PROJECT: a variável de ambiente que especifica o ID do projeto Google Cloud .
    • PROJECT_ID: o ID do projeto do Google Cloud .

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 seguinte configuração, substitua os marcadores pelos seus valores e salve: 
            {
          "mcpServers": {
            "storage": {
              "command": "./PATH/TO/toolbox",
              "args": ["--prebuilt","cloud-storage","--stdio"],
              "env": {
                "CLOUD_STORAGE_PROJECT": "PROJECT_ID"
              }
            }
          }
        }
    Substitua as seguintes variáveis pelos seus valores:
    • ./PATH/TO/toolbox: o caminho para o binário toolbox.
    • CLOUD_STORAGE_PROJECT: a variável de ambiente que especifica o ID do projeto Google Cloud .
    • PROJECT_ID: o ID do projeto do Google Cloud .
  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 seguinte configuração, substitua os marcadores pelos seus valores e salve: 
            {
          "mcpServers": {
            "storage": {
              "command": "./PATH/TO/toolbox",
              "args": ["--prebuilt","cloud-storage","--stdio"],
              "env": {
                "CLOUD_STORAGE_PROJECT": "PROJECT_ID"
              }
            }
          }
        }
    Substitua as seguintes variáveis pelos seus valores:
    • ./PATH/TO/toolbox: o caminho para o binário toolbox.
    • CLOUD_STORAGE_PROJECT: a variável de ambiente que especifica o ID do projeto Google Cloud .
    • PROJECT_ID: o ID do projeto do Google Cloud .
  4. Atualize 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 seguinte configuração, substitua os marcadores pelos seus valores e salve: 
            {
          "mcpServers": {
            "storage": {
              "command": "./PATH/TO/toolbox",
              "args": ["--prebuilt","cloud-storage","--stdio"],
              "env": {
                "CLOUD_STORAGE_PROJECT": "PROJECT_ID"
              }
            }
          }
        }
    Substitua as seguintes variáveis pelos seus valores:
    • ./PATH/TO/toolbox: o caminho para o binário toolbox.
    • CLOUD_STORAGE_PROJECT: a variável de ambiente que especifica o ID do projeto Google Cloud .
    • PROJECT_ID: o ID do projeto do Google Cloud .

Ferramentas pré-criadas

Depois de conectar a MCP Toolbox ao Cloud Storage, seu agente usa as seguintes ferramentas pré-criadas:

  • list_buckets: lista os buckets do Cloud Storage no projeto configurado.
  • list_objects: lista objetos em um bucket com filtragem opcional de prefixo e delimitador.
  • get_bucket_metadata: retorna metadados de um bucket.
  • get_bucket_iam_policy: retorna as vinculações da política de IAM de um bucket.
  • get_object_metadata: retorna metadados de um objeto.
  • read_object: lê um objeto de texto UTF-8 (ou intervalo de bytes). Limitado a 8 MiB. Objetos binários são rejeitados.
  • download_object: faz o download de um objeto para um caminho local.
  • create_bucket: cria um bucket no projeto configurado.
  • delete_bucket: exclui um bucket vazio.
  • upload_object: faz upload de um arquivo local para um objeto.
  • write_object: grava conteúdo de texto diretamente em um objeto.
  • copy_object: copia um objeto para um objeto de destino.
  • move_object: renomeia atomicamente um objeto no mesmo bucket.
  • delete_object: exclui um objeto.