Usa Cloud SQL para PostgreSQL con MCP, la CLI de Gemini y otros agentes

MySQL   |  PostgreSQL   |  SQL Server

En esta página, se muestra cómo conectar tu instancia de Cloud SQL a varias herramientas de asistencia para desarrolladores de IA, incluidas las siguientes:

• Extensión de Gemini CLI para Cloud SQL para PostgreSQL
• Extensión de Gemini CLI para PostgreSQL

• Gemini Code Assist
• Claude Code
• Claude para computadoras de escritorio
• Codex
• Cline (extensión de VS Code)
• Cursor
• Visual Studio Code (Copilot)
• Windsurf (Codeium)
• Antigravity

Para obtener una experiencia integrada, te recomendamos que uses la extensión de Gemini CLI dedicada para Cloud SQL para PostgreSQL.

Como la interfaz de línea de comandos de nueva generación de Google Cloud, Gemini CLI empaqueta las habilidades subyacentes directamente en la extensión, lo que simplifica la configuración. Puedes configurar Gemini Code Assist para que use la CLI de Gemini, lo que ofrece beneficios de configuración similares en tu IDE.

En el caso de otras herramientas para desarrolladores que admiten el Protocolo de contexto del modelo (MCP), puedes conectarte configurando de forma manual la MCP Toolbox para bases de datos (Toolbox). Toolbox es un servidor de MCP de código abierto que conecta agentes de IA a tus datos administrando tareas como la autenticación y la agrupación de conexiones. Esto te permite interactuar con tus datos usando lenguaje natural directamente desde tu IDE. Para estas herramientas, este método proporciona capacidades de interacción con la base de datos principal.

Para obtener más información, consulta Herramientas compiladas previamente y MCP Toolbox para bases de datos en GitHub.

Acerca de Gemini CLI y las extensiones

Gemini CLI es un agente de IA de código abierto diseñado para ayudar con los flujos de trabajo de desarrollo, ya que asiste con la programación, la depuración, la exploración de datos y la creación de contenido. Proporciona una interfaz de agentes para interactuar con servicios de bases de datos y análisis, y bases de datos de código abierto populares.

Cómo funcionan las extensiones

Gemini CLI es muy extensible, lo que permite agregar nuevas herramientas y capacidades a través de extensiones. Puedes cargar las extensiones desde una URL de GitHub, un directorio local o un registro configurable. Proporcionan nuevas herramientas, comandos de barra, habilidades y mensajes para ayudarte con tu flujo de trabajo.

Usa las extensiones de Gemini CLI en Cloud SQL para PostgreSQL

La extensión de Gemini CLI de Cloud SQL se basa en MCP Toolbox para bases de datos.

La integración con Gemini CLI se realiza a través de una extensión dedicada que ofrece capacidades adicionales en comparación con la conexión estándar de Toolbox. La extensión ofrece un proceso de instalación optimizado y un conjunto de habilidades basadas en las herramientas de MCP.

Para obtener más información, consulta la documentación de GitHub sobre la extensión de Gemini CLI para Cloud SQL para PostgreSQL.

Extensión de Gemini CLI para bases de datos de Cloud SQL para PostgreSQL

La extensión cloud-sql-postgresql incluye habilidades para consultar la base de datos, administrar recursos de Cloud SQL y supervisar el estado de la base de datos.

Para conocer todas las habilidades disponibles, consulta las habilidades de Cloud SQL en GitHub.

La extensión cloud-sql-postgresql-observability proporciona una interfaz unificada para administrar y supervisar el rendimiento y el estado de la base de datos directamente desde la CLI de Gemini.

Categoría	Herramientas
Observabilidad	get_system_metrics: Recupera las métricas del sistema de una instancia de Cloud SQL. get_query_metrics: Recupera métricas relacionadas con las consultas para una instancia de Cloud SQL.

Extensión de Gemini CLI para bases de datos de PostgreSQL

Para obtener una lista de esas operaciones, consulta MCP Toolbox para bases de datos y Extensión de Gemini CLI para PostgreSQL.

Antes de comenzar

• En la consola de Google Cloud , en la página del selector de proyectos, selecciona o crea un proyecto de Google Cloud .

• Asegúrate de tener habilitada la facturación para tu proyecto de Google Cloud .

• Habilita la API de Cloud SQL Admin en el proyecto Google Cloud .

• De forma predeterminada, Cloud SQL asigna una dirección IP pública a una instancia nueva. Según tu caso de uso, asegúrate de que se configure una IP pública o una IP privada para tus instancias de Cloud SQL. Toolbox se conecta de forma segura con los conectores de lenguaje de Cloud SQL.

• Otorga los roles de Identity and Access Management (IAM) necesarios al usuario que ejecutará el servidor de MCP. Las herramientas disponibles dependen de los roles otorgados:

  Tarea	Nombre del rol	Rol de IAM requerido
  Proporciona acceso de solo lectura a los recursos, incluidas las siguientes operaciones: get_instance list_instances list_databases wait_for_operation	Visualizador de Cloud SQL	roles/cloudsql.viewer
  Proporciona acceso de solo lectura a los datos de supervisión, como las métricas de series temporales.	Visualizador de Cloud Monitoring	roles/monitoring.viewer
  Proporciona permisos para administrar recursos existentes, incluidos los siguientes: Todas las herramientas de viewer create_database	Editor de Cloud SQL	roles/cloudsql.editor
  Proporciona control total sobre todos los recursos, incluidos los siguientes: Todas las herramientas de viewer y editor create_instance create_user	Administrador de Cloud SQL	roles/cloudsql.admin

• Configura las credenciales predeterminadas de la aplicación (ADC) para tu entorno.

• Crea o reutiliza un usuario de base de datos y ten listos el nombre de usuario y la contraseña.

Conéctate con Data Agent Kit

La extensión Google Cloud Data Agent Kit te permite conectarte a Cloud SQL y realizar consultas en él desde Visual Studio Code o cualquier IDE basado en VS Code. Te permite conectarte a servidores de MCP, consultar datos y ejecutar cargas de trabajo de ingeniería de datos desde tu IDE. Data Agent Kit también proporciona complementos de la CLI.

Para obtener más información, consulta la descripción general del kit de agentes de datos.

Conéctate con Antigravity

Puedes conectar Cloud SQL para PostgreSQL a Antigravity de las siguientes maneras:

• Usa MCP Store
• Usa una configuración personalizada

Nota: No es necesario que descargues el objeto binario de MCP Toolbox para usar estos métodos.

MCP Store

El método más recomendado para conectarse a Cloud SQL para PostgreSQL en Antigravity es usar la MCP Store integrada.

1. Abre Antigravity y el panel de agentes del editor.
2. Haz clic en el ícono "..." en la parte superior del panel y selecciona Servidores de MCP.
3. Busca Cloud SQL para PostgreSQL en la lista de servidores disponibles y haz clic en Instalar.
4. Sigue las instrucciones en pantalla para vincular tus cuentas de forma segura, cuando corresponda.

Después de instalar Cloud SQL para PostgreSQL en MCP Store, los recursos y las herramientas del servidor estarán disponibles automáticamente para el editor.

Configuración personalizada

Para conectarte a un servidor de MCP personalizado, sigue estos pasos:

1. Abre Antigravity y el panel de agentes del editor.
2. Haz clic en el ícono "..." en la parte superior del panel y selecciona Servidores de MCP.
3. Haz clic en Manage MCP Servers > View raw config para abrir el archivo mcp_config.json.
4. Agrega la siguiente configuración, reemplaza las variables de entorno por tus valores y guarda los cambios.

{
  "mcpServers": {
    "cloud-sql-postgres": {
      "command": "npx",
      "args": ["-y","@toolbox-sdk/server","--prebuilt","cloud-sql-postgres","--stdio"],
      "env": {
          "CLOUD_SQL_POSTGRES_PROJECT": "PROJECT_ID",
          "CLOUD_SQL_POSTGRES_REGION": "REGION",
          "CLOUD_SQL_POSTGRES_INSTANCE": "INSTANCE_ID",
          "CLOUD_SQL_POSTGRES_DATABASE": "DATABASE_NAME",
          "CLOUD_SQL_POSTGRES_USER": "USER_ID",
          "CLOUD_SQL_POSTGRES_PASSWORD": "PASSWORD"
      }
    }
  }
}

Una vez que configures el servidor de MCP personalizado, los recursos y las herramientas del servidor de Cloud SQL para PostgreSQL estarán disponibles para el editor.

Instala MCP Toolbox

Nota: Este paso no es obligatorio para las extensiones de Gemini CLI.

1. Descarga el objeto binario que corresponda a tu sistema operativo y arquitectura de la 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. Haz que el objeto binario sea ejecutable:

   chmod +x toolbox

3. Verifica la instalación con el siguiente comando:

   ./toolbox --version

Configura el cliente de MCP

En esta sección, se describe cómo configurar varias herramientas para desarrolladores para conectarse a tu instancia de Cloud SQL con Toolbox. Toolbox actúa como un servidor de Protocolo de contexto del modelo (MCP) de código abierto que se ubica entre tu IDE y tu base de datos, lo que proporciona un plano de control seguro y eficiente para tus herramientas de IA. Selecciona la pestaña de tu herramienta específica para ver las instrucciones de configuración.

Gemini CLI para Cloud SQL para PostgreSQL

1. Instala la CLI de Gemini.
2. Instala la extensión de Cloud SQL para PostgreSQL para la CLI de Gemini desde el repositorio de GitHub con el siguiente comando:

   gemini extensions install https://github.com/gemini-cli-extensions/cloud-sql-postgresql
   

   Mientras instalas la extensión, reemplaza lo siguiente:
   • PROJECT_NAME: Es el ID del proyecto de Google Cloud .
   • REGION: Es la región de tu instancia de Cloud SQL.
   • INSTANCE_NAME: Es el ID de tu instancia de Cloud SQL.
   • DATABASE_NAME: El nombre de la base de datos a la que te conectarás.
   • DATABASE_USER_NAME: Es el nombre de usuario de la base de datos (opcional). Si no se especifica, se usa la autenticación de IAM de forma predeterminada.
   • PASSWORD: Es opcional y corresponde a la contraseña del usuario de la base de datos. Si no se especifica, se usa la autenticación de IAM de forma predeterminada.
   • IP_TYPE: Es opcional. Es el tipo de IP, como "Pública" (predeterminada) o "Privada".
3. Inicia la CLI de Gemini en modo interactivo:

   gemini
   

   La CLI carga automáticamente la extensión de Gemini CLI para Cloud SQL y sus habilidades, que puedes usar para interactuar con tu base de datos.

   En la CLI de Gemini, usa el comando /extensions para verificar que la extensión esté instalada y el comando /mcp list para ver las herramientas.

Gemini CLI para PostgreSQL

1. Instala la CLI de Gemini.
2. Instala la extensión de software de PostgreSQL para Gemini CLI desde el repositorio de GitHub con el siguiente comando:

   gemini extensions install https://github.com/gemini-cli-extensions/postgres
   

   Mientras instalas la extensión, reemplaza lo siguiente:

   export POSTGRES_HOST="HOST"
   export POSTGRES_PORT="PORT"
   export POSTGRES_DATABASE="DATABASE"
   export POSTGRES_USER="USER"
   export POSTGRES_PASSWORD="PASSWORD"
   export POSTGRES_QUERY_PARAMETERS="QUERY_PARAMETERS"
   

   Reemplaza lo siguiente:
   • HOST: Es el nombre de host o la dirección IP del servidor de PostgreSQL.
   • PORT: Es el número de puerto del servidor de PostgreSQL.
   • DATABASE: El nombre de la base de datos a la que te conectarás.
   • USER: Es el nombre de usuario de la base de datos.
   • PASSWORD: Es la contraseña del usuario de la base de datos.
   • QUERY_PARAMETERS: Es opcional. Es la consulta sin procesar que se agregará a la cadena de conexión de db.
3. Inicia la CLI de Gemini en modo interactivo:

   gemini

   La CLI carga automáticamente la extensión de Gemini CLI para PostgreSQL y sus herramientas, que puedes usar para interactuar con tu base de datos.

Gemini Code Assist

1. Instala la extensión de Gemini Code Assist en Visual Studio Code.
2. Habilitar el modo de agente en el chat de Gemini Code Assist
3. En tu directorio de trabajo, crea una carpeta llamada .gemini. Dentro de ella, crea un archivo settings.json.
4. Agrega la siguiente configuración, reemplaza las variables de entorno por tus valores y, luego, guarda:

   {
     "mcpServers": {
       "cloud-sql-postgres": {
         "command": "./PATH/TO/toolbox",
         "args": ["--prebuilt","cloud-sql-postgres","--stdio"],
         "env": {
           "CLOUD_SQL_POSTGRES_PROJECT": "PROJECT_ID",
           "CLOUD_SQL_POSTGRES_REGION": "REGION",
           "CLOUD_SQL_POSTGRES_INSTANCE": "INSTANCE_ID",
           "CLOUD_SQL_POSTGRES_DATABASE": "DATABASE_NAME",
           "CLOUD_SQL_POSTGRES_USER": "USER_ID",
           "CLOUD_SQL_POSTGRES_PASSWORD": "PASSWORD"
         }
       }
     }
   }
   
   

Claude Code

1. Instala Claude Code.
2. Establece variables de entorno para conectarte a tu instancia de Cloud SQL:

   export CLOUD_SQL_POSTGRES_PROJECT="PROJECT_NAME"
   export CLOUD_SQL_POSTGRES_REGION="REGION"
   export CLOUD_SQL_POSTGRES_INSTANCE="INSTANCE_NAME"
   export CLOUD_SQL_POSTGRES_DATABASE="DATABASE_NAME"
   export CLOUD_SQL_POSTGRES_USER="DATABASE_USER_NAME"
   export CLOUD_SQL_POSTGRES_PASSWORD="PASSWORD"
   export CLOUD_SQL_POSTGRES_IP_TYPE="IP_TYPE"
   

   Reemplaza lo siguiente:
   • PROJECT_NAME: Es el ID del proyecto de Google Cloud .
   • REGION: Es la región de tu instancia de Cloud SQL.
   • INSTANCE_NAME: Es el ID de tu instancia de Cloud SQL.
   • DATABASE_NAME: El nombre de la base de datos a la que te conectarás.
   • DATABASE_USER_NAME: Es el nombre de usuario de la base de datos (opcional). Si no se especifica, se usa la autenticación de IAM de forma predeterminada.
   • PASSWORD: Es opcional y corresponde a la contraseña del usuario de la base de datos. Si no se especifica, se usa la autenticación de IAM de forma predeterminada.
   • IP_TYPE: Es opcional. Es el tipo de IP, como "Pública" (predeterminada) o "Privada".
3. Inicia el agente:

   claude

4. Instala el complemento:

   /plugin install cloud-sql-postgresql@claude-plugins-official

Sugerencia: Ejecuta /plugin list dentro de Claude Code para verificar que el complemento esté activo o /reload-plugins si lo acabas de instalar.

Claude para computadoras de escritorio

1. Abre Claude para computadoras y navega a Configuración.
2. En la pestaña Desarrollador, presiona Editar configuración para abrir el archivo de configuración.
3. Agrega lo siguiente para conectarte al servidor de MCP y configurar las variables de entorno:

   {
     "mcpServers": {
       "cloud-sql-postgres": {
         "command": "./PATH/TO/toolbox",
         "args": ["--prebuilt","cloud-sql-postgres","--stdio"],
         "env": {
           "CLOUD_SQL_POSTGRES_PROJECT": "PROJECT_ID",
           "CLOUD_SQL_POSTGRES_REGION": "REGION",
           "CLOUD_SQL_POSTGRES_INSTANCE": "INSTANCE_ID",
           "CLOUD_SQL_POSTGRES_DATABASE": "DATABASE_NAME",
           "CLOUD_SQL_POSTGRES_USER": "USER_ID",
           "CLOUD_SQL_POSTGRES_PASSWORD": "PASSWORD"
       }
     }
   }
   }
   
   

4. Reinicia Claude para computadoras de escritorio. En la pantalla de chat nueva, se muestra el ícono de MCP con el nuevo servidor de MCP disponible.

Cline

1. Abre la extensión de Cline en VS Code y presiona el ícono de servidores de MCP.
2. Presiona Configure MCP Servers para abrir el archivo de configuración.
3. Agrega la siguiente configuración, reemplaza las variables de entorno por tus valores y guarda los cambios:

   {
     "mcpServers": {
       "cloud-sql-postgres": {
         "command": "./PATH/TO/toolbox",
         "args": ["--prebuilt","cloud-sql-postgres","--stdio"],
         "env": {
           "CLOUD_SQL_POSTGRES_PROJECT": "PROJECT_ID",
           "CLOUD_SQL_POSTGRES_REGION": "REGION",
           "CLOUD_SQL_POSTGRES_INSTANCE": "INSTANCE_ID",
           "CLOUD_SQL_POSTGRES_DATABASE": "DATABASE_NAME",
           "CLOUD_SQL_POSTGRES_USER": "USER_ID",
           "CLOUD_SQL_POSTGRES_PASSWORD": "PASSWORD"
         }
       }
     }
   }
   
   

   Aparecerá un estado activo de color verde después de que el servidor se conecte correctamente.

Codex

1. Instala el mercado de complementos de Data Cloud:

   codex plugin marketplace add GoogleCloudPlatform/data-cloud-plugins

2. Instala el complemento:

   codex plugin install cloud-sql-postgresql@data-cloud-plugins

3. Configura las variables de entorno para conectarte a tu instancia de Cloud SQL:

   export CLOUD_SQL_POSTGRES_PROJECT="PROJECT_NAME"
   export CLOUD_SQL_POSTGRES_REGION="REGION"
   export CLOUD_SQL_POSTGRES_INSTANCE="INSTANCE_NAME"
   export CLOUD_SQL_POSTGRES_DATABASE="DATABASE_NAME"
   export CLOUD_SQL_POSTGRES_USER="DATABASE_USER_NAME"
   export CLOUD_SQL_POSTGRES_PASSWORD="PASSWORD"
   export CLOUD_SQL_POSTGRES_IP_TYPE="IP_TYPE"
   

   Reemplaza lo siguiente:
   • PROJECT_NAME: Es el ID del proyecto de Google Cloud .
   • REGION: Es la región de tu instancia de Cloud SQL.
   • INSTANCE_NAME: Es el ID de tu instancia de Cloud SQL.
   • DATABASE_NAME: El nombre de la base de datos a la que te conectarás.
   • DATABASE_USER_NAME: Es el nombre de usuario de la base de datos (opcional). Si no se especifica, se usa la autenticación de IAM de forma predeterminada.
   • PASSWORD: Es opcional y corresponde a la contraseña del usuario de la base de datos. Si no se especifica, se usa la autenticación de IAM de forma predeterminada.
   • IP_TYPE: Es opcional. Es el tipo de IP, como "Pública" (predeterminada) o "Privada".
4. Es opcional. Actualiza el mercado:

   codex plugin marketplace upgrade data-cloud-plugins

5. Ejecuta codex plugin list o usa el menú interactivo plugins para verificar los complementos instalados.

Cline

1. Abre la extensión de Cline en VS Code y presiona el ícono de servidores de MCP.
2. Presiona Configure MCP Servers para abrir el archivo de configuración.
3. Agrega la siguiente configuración, reemplaza las variables de entorno por tus valores y guarda los cambios:

   {
     "mcpServers": {
       "cloud-sql-postgres": {
         "command": "./PATH/TO/toolbox",
         "args": ["--prebuilt","cloud-sql-postgres","--stdio"],
         "env": {
           "CLOUD_SQL_POSTGRES_PROJECT": "PROJECT_ID",
           "CLOUD_SQL_POSTGRES_REGION": "REGION",
           "CLOUD_SQL_POSTGRES_INSTANCE": "INSTANCE_ID",
           "CLOUD_SQL_POSTGRES_DATABASE": "DATABASE_NAME",
           "CLOUD_SQL_POSTGRES_USER": "USER_ID",
           "CLOUD_SQL_POSTGRES_PASSWORD": "PASSWORD"
         }
       }
     }
   }
   
   

   Aparecerá un estado activo de color verde después de que el servidor se conecte correctamente.

Cursor

1. Crea el directorio .cursor en la raíz de tu proyecto si no existe.
2. Crea el archivo .cursor/mcp.json si no existe y ábrelo.
3. Agrega la siguiente configuración, reemplaza las variables de entorno por tus valores y guarda los cambios:

   {
     "mcpServers": {
       "cloud-sql-postgres": {
         "command": "./PATH/TO/toolbox",
         "args": ["--prebuilt","cloud-sql-postgres","--stdio"],
         "env": {
           "CLOUD_SQL_POSTGRES_PROJECT": "PROJECT_ID",
           "CLOUD_SQL_POSTGRES_REGION": "REGION",
           "CLOUD_SQL_POSTGRES_INSTANCE": "INSTANCE_ID",
           "CLOUD_SQL_POSTGRES_DATABASE": "DATABASE_NAME",
           "CLOUD_SQL_POSTGRES_USER": "USER_ID",
           "CLOUD_SQL_POSTGRES_PASSWORD": "PASSWORD"
         }
       }
     }
   }
   
   

4. Abre Cursor y navega a Settings > Cursor Settings > MCP. Cuando el servidor se conecte, aparecerá un estado activo de color verde.

Visual Studio Code (Copilot)

1. Abre VS Code y crea el directorio .vscode en la raíz del proyecto si no existe.
2. Crea el archivo .vscode/mcp.json si no existe y ábrelo.
3. Agrega la siguiente configuración, reemplaza las variables de entorno por tus valores y guarda los cambios:

   {
     "servers": {
       "cloud-sql-postgres": {
         "command": "./PATH/TO/toolbox",
         "args": ["--prebuilt","cloud-sql-postgres","--stdio"],
         "env": {
           "CLOUD_SQL_POSTGRES_PROJECT": "PROJECT_ID",
           "CLOUD_SQL_POSTGRES_REGION": "REGION",
           "CLOUD_SQL_POSTGRES_INSTANCE": "INSTANCE_ID",
           "CLOUD_SQL_POSTGRES_DATABASE": "DATABASE_NAME",
           "CLOUD_SQL_POSTGRES_USER": "USER_ID",
           "CLOUD_SQL_POSTGRES_PASSWORD": "PASSWORD"
         }
       }
     }
   }
   
   

Windsurf

1. Abre Windsurf y navega a Cascade assistant.
2. Presiona el ícono de MCP y, luego, Configure para abrir el archivo de configuración.
3. Agrega la siguiente configuración, reemplaza las variables de entorno por tus valores y guarda los cambios:

   {
     "mcpServers": {
       "cloud-sql-postgres": {
         "command": "./PATH/TO/toolbox",
         "args": ["--prebuilt","cloud-sql-postgres","--stdio"],
         "env": {
           "CLOUD_SQL_POSTGRES_PROJECT": "PROJECT_ID",
           "CLOUD_SQL_POSTGRES_REGION": "REGION",
           "CLOUD_SQL_POSTGRES_INSTANCE": "INSTANCE_ID",
           "CLOUD_SQL_POSTGRES_DATABASE": "DATABASE_NAME",
           "CLOUD_SQL_POSTGRES_USER": "USER_ID",
           "CLOUD_SQL_POSTGRES_PASSWORD": "PASSWORD"
         }
       }
     }
   }