Use o Cloud SQL para MySQL com o MCP, a Gemini CLI e outros agentes

Esta página mostra como ligar a sua instância do Cloud SQL a várias ferramentas de assistência para programadores de IA, incluindo o seguinte:

Para uma experiência integrada, recomendamos que use a extensão da CLI do Gemini para o Cloud SQL para MySQL dedicada.

Como Google Cloud; interface de linha de comandos de próxima geração, a CLI Gemini agrupa o servidor MCP subjacente diretamente na extensão, o que simplifica a configuração. Pode configurar o Gemini Code Assist para usar a Gemini CLI, o que oferece vantagens de configuração semelhantes no seu IDE.

Para outras ferramentas para programadores que suportam o protocolo Model Context Protocol (MCP), pode estabelecer ligação configurando manualmente a caixa de ferramentas do MCP para bases de dados (caixa de ferramentas). A caixa de ferramentas é um servidor MCP de código aberto que liga os agentes de IA aos seus dados através da gestão de tarefas como a autenticação e a partilha de ligações. Isto permite-lhe interagir com os seus dados através de linguagem natural diretamente a partir do IDE. Para estas ferramentas, este método oferece capacidades de interação com a base de dados essenciais.

Para mais informações, consulte as ferramentas pré-criadas e a caixa de ferramentas da MCP para bases de dados no GitHub.

Acerca da Gemini CLI e das extensões

O Gemini CLI é um agente de IA de código aberto concebido para ajudar nos fluxos de trabalho de desenvolvimento, auxiliando na programação, na depuração, na exploração de dados e na criação de conteúdo. Oferece uma interface de agente para interagir com serviços de base de dados e análise, bem como bases de dados de código aberto populares.

Como funcionam as extensões

O Gemini CLI é altamente extensível, o que permite a adição de novas ferramentas e capacidades através de extensões. Pode carregar as extensões a partir de um URL do GitHub, de um diretório local ou de um registo configurável. Oferecem novas ferramentas, comandos com barra e comandos para ajudar no seu fluxo de trabalho.

Use as extensões da Gemini CLI no Cloud SQL para MySQL

A extensão da CLI Gemini do Cloud SQL baseia-se na MCP Toolbox for Databases. Atualmente, a caixa de ferramentas da MCP para bases de dados está na versão beta (pré-v1.0) e pode sofrer alterações significativas até ao primeiro lançamento estável (v1.0).

A integração com a CLI do Gemini é feita através de uma extensão dedicada que oferece capacidades adicionais em comparação com a ligação padrão da caixa de ferramentas. A extensão oferece um processo de instalação simplificado e um conjunto de ferramentas.

Para mais informações, consulte a documentação do GitHub sobre a extensão da CLI Gemini para o Cloud SQL para MySQL.

Extensão da Gemini CLI para bases de dados do Cloud SQL para MySQL

A extensão cloud-sql-mysql inclui ferramentas para consultar a base de dados e monitorizar o estado da base de dados.

Categoria Ferramentas
Operações de base de dados
  • list_tables: lista todas as tabelas e as respetivas descrições encontradas numa base de dados.
  • execute_sql: executa qualquer declaração SQL.
  • list_active_queries: lista as consultas em execução numa instância do Cloud SQL.
  • list_tables_missing_unique_indexes: encontra tabelas sem chaves principais ou únicas.
  • list_table_fragmentation: recebe informações de fragmentação de tabelas.
  • get_query_plan: obtém o plano de consulta para uma única declaração de uma instância do Cloud SQL.
Gestão de recursos para instâncias e utilizadores
  • create_user: cria um novo utilizador numa instância do Cloud SQL.
  • list_databases: lista todas as bases de dados de uma instância do Cloud SQL.
  • create_database: cria uma nova base de dados numa instância do Cloud SQL.
  • list_instances: lista as instâncias do Cloud SQL num determinado projeto.
  • get_instance: Obtenha os detalhes sobre uma instância específica do Cloud SQL.
  • create_instance: cria uma nova instância do Cloud SQL.
  • wait_for_operation: consulta a API Operations até que uma operação esteja concluída.

A extensão cloud-sql-mysql-observability oferece uma interface unificada para gerir e monitorizar o desempenho e o estado da base de dados diretamente a partir da Gemini CLI.

Categoria Ferramentas
Observabilidade
  • get_system_metrics: Obtém métricas do sistema para uma instância do Cloud SQL.
  • get_query_metrics: Obtém métricas relacionadas com consultas para uma instância do Cloud SQL.

Extensão da CLI do Gemini para bases de dados MySQL

Para ver uma lista dessas operações, consulte o artigo MCP Toolbox for Databases e a extensão da CLI Gemini para MySQL.

Antes de começar

  • Na Google Cloud consola, na página do seletor de projetos, selecione ou crie um Google Cloud projeto.

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

  • Ative a API Admin do Cloud SQL no Google Cloud projeto.

  • Por predefinição, o Cloud SQL atribui um endereço IP público a uma nova instância. Consoante o seu exemplo de utilização, certifique-se de que tem configurado um IP público ou um IP privado para as suas instâncias do Cloud SQL. A caixa de ferramentas liga-se de forma segura através dos conetores de linguagem do Cloud SQL.

  • Conceda as funções necessárias de gestão de identidade e de acesso (IAM) ao utilizador que vai executar o servidor do MCP. As ferramentas disponíveis dependem das funções concedidas:

    Tarefa Nome da função Função de IAM necessária
    Fornece acesso só de leitura aos recursos, incluindo as seguintes operações:
    • get_instance
    • list_instances
    • list_databases
    • wait_for_operation
    		 Visualizador do Cloud SQL roles/cloudsql.viewer
    Fornece acesso só de leitura a dados de monitorização, como métricas de séries cronológicas. Visualizador do Cloud Monitoring roles/monitoring.viewer
    Fornece autorizações para gerir recursos existentes, incluindo o seguinte:
    • Todas as ferramentas de viewer
    • create_database
    		 Editor do Cloud SQL roles/cloudsql.editor
    Oferece controlo total sobre todos os recursos, incluindo o seguinte:
    • Todas as ferramentas viewer e editor
    • create_instance
    • create_user
    		 Administrador do Cloud SQL roles/cloudsql.admin

  • Configure as Credenciais padrão da aplicação (ADC) para o seu ambiente.

  • Crie ou reutilize um utilizador da base de dados e tenha o nome de utilizador e a palavra-passe preparados.

Instale a caixa de ferramentas do MCP

  1. Para instalar o conjunto de ferramentas, transfira o ficheiro binário que corresponde ao seu sistema operativo e arquitetura da CPU.

    linux/amd64

    curl -O https://storage.googleapis.com/genai-toolbox/v0.7.0/linux/amd64/toolbox

    darwin/arm64

    curl -O https://storage.googleapis.com/genai-toolbox/v0.7.0/darwin/arm64/toolbox

    darwin/amd64

    curl -O https://storage.googleapis.com/genai-toolbox/v0.7.0/darwin/amd64/toolbox

    windows/amd64

    curl -O https://storage.googleapis.com/genai-toolbox/v0.7.0/windows/amd64/toolbox

  2. Torne o executável binário:

    chmod +x toolbox

  3. Valide a instalação através do seguinte comando:

    ./toolbox --version

Configure o cliente MCP

Esta secção descreve como configurar várias ferramentas para programadores para estabelecer ligação à sua instância do Cloud SQL através da Toolbox. A caixa de ferramentas funciona como um servidor de protocolo Model Context Protocol (MCP) de código aberto que se encontra entre o seu IDE e a sua base de dados, oferecendo um plano de controlo seguro e eficiente para as suas ferramentas de IA. Selecione o separador da sua ferramenta específica para ver as instruções de configuração.

CLI do Gemini para o Cloud SQL para MySQL


1. Instale a CLI do Gemini.
2. Instale a extensão Cloud SQL para MySQL para a Gemini CLI a partir do repositório do GitHub com o seguinte comando: 
    gemini extensions install https://github.com/gemini-cli-extensions/cloud-sql-mysql
3. Defina variáveis de ambiente para estabelecer ligação à sua instância do Cloud SQL: 
    export CLOUD_SQL_MYSQL_PROJECT="PROJECT_NAME"
    export CLOUD_SQL_MYSQL_REGION="REGION"
    export CLOUD_SQL_MYSQL_INSTANCE="INSTANCE_NAME"
    export CLOUD_SQL_MYSQL_DATABASE="DATABASE_NAME"
    export CLOUD_SQL_MYSQL_USER="DATABASE_USER_NAME"
    export CLOUD_SQL_MYSQL_PASSWORD="PASSWORD"
    export CLOUD_SQL_MYSQL_IP_TYPE="IP_TYPE"
Substitua o seguinte:
  • PROJECT_NAME: O Google Cloud ID do projeto.
  • REGION: a região da sua instância do Cloud SQL.
  • INSTANCE_NAME: o ID da sua instância do Cloud SQL.
  • DATABASE_NAME: o nome da base de dados à qual estabelecer ligação.
  • DATABASE_USER_NAME: opcional: o nome de utilizador da base de dados. A predefinição é a autenticação IAM se não for especificado.
  • PASSWORD: opcional: a palavra-passe do utilizador da base de dados. A predefinição é a autenticação IAM se não for especificado.
  • IP_TYPE: Opcional: o tipo de IP, como "Público" (predefinição) ou "Privado".
4. Inicie a CLI do Gemini no modo interativo: 
      gemini

A CLI carrega automaticamente a extensão Gemini CLI para o Cloud SQL e as respetivas ferramentas, que pode usar para interagir com a sua base de dados.

Na Gemini CLI, use o comando /extensions para verificar se a extensão está instalada e o comando /mcp list para ver as ferramentas.

CLI do Gemini para MySQL


1. Instale a CLI do Gemini.
2. Instale a extensão de software MySQL para a Gemini CLI a partir do repositório do GitHub com o seguinte comando: 
      gemini extensions install https://github.com/gemini-cli-extensions/mysql
3. Defina variáveis de ambiente para estabelecer ligação à sua instância do MySQL: 
      export MYSQL_HOST="HOST"
      export MYSQL_PORT="PORT"
      export MYSQL_DATABASE="DATABASE"
      export MYSQL_USER="USER"
      export MYSQL_PASSWORD="PASSWORD"
      export MYSQL_QUERY_PARAMETERS="QUERY_PARAMETERS"
Substitua o seguinte:
  • HOST: o nome de anfitrião ou o endereço IP do servidor MySQL.
  • PORT: o número da porta do servidor MySQL.
  • DATABASE: o nome da base de dados à qual estabelecer ligação.
  • USER: o nome de utilizador da base de dados.
  • PASSWORD: a palavra-passe do utilizador da base de dados.
  • QUERY_PARAMETERS: opcional: a consulta não processada a adicionar à sequência de carateres de ligação db.
4. Inicie a CLI do Gemini no modo interativo: 
      gemini

A CLI carrega automaticamente a extensão Gemini CLI para MySQL e as respetivas ferramentas, que pode usar para interagir com a sua base de dados.

Gemini Code Assist


1. Instale a extensão Gemini Code Assist no Visual Studio Code.
2. Ative o modo de agente no chat do Gemini Code Assist.
3. No seu diretório de trabalho, crie uma pasta denominada .gemini. No interior, crie um ficheiro settings.json.
4. Adicione a seguinte configuração, substitua as variáveis de ambiente pelos seus valores e, de seguida, guarde:


{
  "mcpServers": {
    "cloud-sql-mysql": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","cloud-sql-mysql","--stdio"],
      "env": {
          "CLOUD_SQL_MYSQL_PROJECT": "PROJECT_ID",
          "CLOUD_SQL_MYSQL_REGION": "REGION",
          "CLOUD_SQL_MYSQL_INSTANCE":"INSTANCE_ID",
          "CLOUD_SQL_MYSQL_DATABASE": "DATABASE_NAME",
          "CLOUD_SQL_MYSQL_USER": "USER_ID",
          "CLOUD_SQL_MYSQL_PASSWORD": "PASSWORD"
      }
    }
  }
}

Código do Claude


1. Instale o Claude Code.
2. Crie o ficheiro .mcp.json na raiz do projeto, se não existir.
3. Adicione a configuração, substitua as variáveis de ambiente pelos seus valores e guarde: 


{
  "mcpServers": {
    "cloud-sql-mysql": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","cloud-sql-mysql","--stdio"],
      "env": {
        "CLOUD_SQL_MYSQL_PROJECT": "PROJECT_ID",
        "CLOUD_SQL_MYSQL_REGION": "REGION",
        "CLOUD_SQL_MYSQL_INSTANCE":"INSTANCE_ID",
        "CLOUD_SQL_MYSQL_DATABASE": "DATABASE_NAME",
        "CLOUD_SQL_MYSQL_USER": "USER_ID",
        "CLOUD_SQL_MYSQL_PASSWORD": "PASSWORD"
      }
    }
  }
}

Claude para computador


1. Abra o Claude Desktop e navegue para Definições.
2. No separador Programador, toque em Editar config para abrir o ficheiro de configuração.
3. Adicione a configuração, substitua as variáveis de ambiente pelos seus valores e guarde: 


{
  "mcpServers": {
    "cloud-sql-mysql": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","cloud-sql-mysql","--stdio"],
      "env": {
        "CLOUD_SQL_MYSQL_PROJECT": "PROJECT_ID",
        "CLOUD_SQL_MYSQL_REGION": "REGION",
        "CLOUD_SQL_MYSQL_INSTANCE":"INSTANCE_ID",
        "CLOUD_SQL_MYSQL_DATABASE": "DATABASE_NAME",
        "CLOUD_SQL_MYSQL_USER": "USER_ID",
        "CLOUD_SQL_MYSQL_PASSWORD": "PASSWORD"
      }
    }
  }
}

5. Reinicie o Claude Desktop.
6. O novo ecrã de chat apresenta um ícone de martelo (MCP) com o novo servidor MCP disponível.

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": {
    "cloud-sql-mysql": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","cloud-sql-mysql","--stdio"],
      "env": {
        "CLOUD_SQL_MYSQL_PROJECT": "PROJECT_ID",
        "CLOUD_SQL_MYSQL_REGION": "REGION",
        "CLOUD_SQL_MYSQL_INSTANCE":"INSTANCE_ID",
        "CLOUD_SQL_MYSQL_DATABASE": "DATABASE_NAME",
        "CLOUD_SQL_MYSQL_USER": "USER_ID",
        "CLOUD_SQL_MYSQL_PASSWORD": "PASSWORD"
      }
    }
  }
}

4. É 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. Crie o ficheiro .cursor/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:


{
  "mcpServers": {
    "cloud-sql-mysql": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","cloud-sql-mysql","--stdio"],
      "env": {
        "CLOUD_SQL_MYSQL_PROJECT": "PROJECT_ID",
        "CLOUD_SQL_MYSQL_REGION": "REGION",
        "CLOUD_SQL_MYSQL_INSTANCE":"INSTANCE_ID",
        "CLOUD_SQL_MYSQL_DATABASE": "DATABASE_NAME",
        "CLOUD_SQL_MYSQL_USER": "USER_ID",
        "CLOUD_SQL_MYSQL_PASSWORD": "PASSWORD"
      }
    }
  }
}

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 o diretório .vscode na raiz do projeto, se ainda não existir.
2. Cria o ficheiro .vscode/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: 


{
  "servers": {
    "cloud-sql-mysql": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","cloud-sql-mysql","--stdio"],
      "env": {
        "CLOUD_SQL_MYSQL_PROJECT": "PROJECT_ID",
        "CLOUD_SQL_MYSQL_REGION": "REGION",
        "CLOUD_SQL_MYSQL_INSTANCE":"INSTANCE_ID",
        "CLOUD_SQL_MYSQL_DATABASE": "DATABASE_NAME",
        "CLOUD_SQL_MYSQL_USER": "USER_ID",
        "CLOUD_SQL_MYSQL_PASSWORD": "PASSWORD"
      }
    }
  }
}

Windsurf


1. Abra o Windsurf e navegue para o assistente Cascade.
2. Toque no ícone do MCP e, de seguida, 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": {
    "cloud-sql-mysql": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","cloud-sql-mysql","--stdio"],
      "env": {
          "CLOUD_SQL_MYSQL_PROJECT": "PROJECT_ID",
          "CLOUD_SQL_MYSQL_REGION": "REGION",
          "CLOUD_SQL_MYSQL_INSTANCE":"INSTANCE_ID",
          "CLOUD_SQL_MYSQL_DATABASE": "DATABASE_NAME",
          "CLOUD_SQL_MYSQL_USER": "USER_ID",
          "CLOUD_SQL_MYSQL_PASSWORD": "PASSWORD"
      }
    }
  }
}