Use Cloud SQL for PostgreSQL with MCP, Gemini CLI, and other agents

This page shows you how to connect your Cloud SQL instance to various AI developer assistance tools, including the following:

For an integrated experience, we recommend using the dedicated Gemini CLI extension for Cloud SQL for PostgreSQL.

As Google Cloud's next-generation command-line interface, Gemini CLI bundles the underlying MCP server directly into the extension, which simplifies setup and configuration. You can configure Gemini Code Assist to use the Gemini CLI, offering similar setup benefits in your IDE.

For other developer tools that support the Model Context Protocol (MCP), you can connect by manually configuring the MCP Toolbox for Databases (Toolbox). Toolbox is an open-source MCP server that connects AI agents to your data by managing tasks such as authentication and connection pooling. This lets you interact with your data using natural language directly from your IDE. For these tools, this method provides core database interaction capabilities.

For more information, see Prebuilt tools and MCP Toolbox for Databases on GitHub.

About Gemini CLI and extensions

Gemini CLI is an open-source AI agent designed to assist with development workflows by assisting with coding, debugging, data exploration, and content creation. It provides an agentic interface for interacting with database and analytics services and popular open-source databases.

How extensions work

Gemini CLI is highly extensible, allowing for the addition of new tools and capabilities through extensions. You can load the extensions from a GitHub URL, a local directory, or a configurable registry. They provide new tools, slash commands, and prompts to assist with your workflow.

Use the Gemini CLI extensions in Cloud SQL for PostgreSQL

The Cloud SQL Gemini CLI extension is based on MCP Toolbox for Databases. MCP Toolbox for Databases is currently in beta (pre-v1.0), and may see breaking changes until the first stable release (v1.0).

The integration with Gemini CLI is through a dedicated extension that offers additional capabilities compared to the standard Toolbox connection. The extension offers a streamlined installation process and a set of tools.

For more information, see GitHub documentation for the Gemini CLI extension for Cloud SQL for PostgreSQL.

Gemini CLI extension for Cloud SQL for PostgreSQL databases

The cloud-sql-postgresql extension includes tools for querying the database, managing Cloud SQL resources, and monitoring database health.

Category Tools
Database operations
  • list_tables: Lists all the tables and their corresponding descriptions found in a database.
  • execute_sql: Executes any SQL statement.
  • list_active_queries: Lists currently running queries on a Cloud SQL instance.
  • list_available_extensions: Lists available PostgreSQL extensions for installation on a Cloud SQL instance.
  • list_installed_extensions: Lists the installed PostgreSQL extensions on a Cloud SQL instance.
  • get_query_plan: Gets the query plan for a single statement from a Cloud SQL instance.
Resource management for instances, & users
  • create_user: Creates a new user in a Cloud SQL instance.
  • list_databases: Lists all databases for a Cloud SQL instance.
  • create_database: Creates a new database within a Cloud SQL instance.
  • list_instances: Lists Cloud SQL instances in a given project.
  • get_instance: Get the details about a specific Cloud SQL instance.
  • create_instance: Creates a new Cloud SQL instance.
  • wait_for_operation: Polls the operations API until an operation is complete.
Database health & maintenance
  • list_autovacuum_configurations: Lists autovacuum settings on a Cloud SQL instance. Vacuum operations remove dead tuples to help free up disk space, prevent table bloat, and improve read and write performance.
  • list_memory_configurations: Lists the instance-level memory settings on a Cloud SQL instance. Displays parameters like shared_buffers and work_mem, to help you assess and optimize resource allocation for query execution and caching.
  • list_top_bloated_tables: Lists the tables in a Cloud SQL instance with the most unused space (bloat). This information can be used to help you schedule maintenance, including vacuuming or reindexing, to reclaim disk space and improve query speed.
  • list_replication_slots: Lists the replication slot details, such as write-ahead logging (WAL) on a Cloud SQL instance. Helps support management and troubleshooting of replication-related issues.
  • list_invalid_indexes: Lists invalid indexes on a Cloud SQL instance. You can use this information to rebuild or drop invalid indexes for improved query performance.

The cloud-sql-postgresql-observability extension provides a unified interface for managing and monitoring database performance and health directly from the Gemini CLI.

Category Tools
Observability
  • get_system_metrics: Retrieves system metrics for a Cloud SQL instance.
  • get_query_metrics: Retrieves query-related metrics for a Cloud SQL instance.

Gemini CLI extension for PostgreSQL databases

For a list of those operations, see MCP Toolbox for Databases and Gemini CLI extension for PostgreSQL.

Before you begin

  • In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

  • Make sure that billing is enabled for your Google Cloud project.

  • Enable the Cloud SQL Admin API in the Google Cloud project.

  • By default, Cloud SQL assigns a public IP address to a new instance. Depending on your use case, make sure either a Public IP or Private IP is set up for your Cloud SQL instances. Toolbox connects securely using the Cloud SQL Language Connectors.

  • Grant the necessary Identity and Access Management (IAM) roles to the user that will be running the MCP server. The tools available depends on the roles granted:

    Task Role name Required IAM role
    Provides read-only access to resources, including the following operations:
    • get_instance
    • list_instances
    • list_databases
    • wait_for_operation
    		 Cloud SQL Viewer roles/cloudsql.viewer
    Provides read-only access to monitoring data such as time series metrics. Cloud Monitoring Viewer roles/monitoring.viewer
    Provides permissions to manage existing resources, including the following:
    • All viewer tools
    • create_database
    		 Cloud SQL Editor roles/cloudsql.editor
    Provides full control over all resources, including the following:
    • All viewer and editor tools
    • create_instance
    • create_user
    		 Cloud SQL Admin roles/cloudsql.admin

  • Configure Application Default Credentials (ADC) for your environment.

  • Create or reuse a database user, and have the username and password ready.

Install the MCP Toolbox

  1. To install the toolbox, download the binary that corresponds to your operating system and CPU architecture.

    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. Make the binary executable:

    chmod +x toolbox

  3. Verify the installation using the following command:

    ./toolbox --version

Configure the MCP Client

This section describes how to configure various developer tools to connect to your Cloud SQL instance using Toolbox. Toolbox acts as an open-source Model Context Protocol (MCP) server that sits between your IDE and your database, providing a secure and efficient control plane for your AI tools. Select the tab for your specific tool to see the configuration instructions.

Gemini CLI for Cloud SQL for PostgreSQL


  1. Install the Gemini CLI.
  2. Install the Cloud SQL for PostgreSQL extension for Gemini CLI from the GitHub repository using the following command: 
      gemini extensions install https://github.com/gemini-cli-extensions/cloud-sql-postgresql
  3. Set environment variables to connect to your Cloud SQL instance: 
      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"
    Replace the following:
    • PROJECT_NAME: The Google Cloud project ID.
    • REGION: The region of your Cloud SQL instance.
    • INSTANCE_NAME: The ID of your Cloud SQL instance.
    • DATABASE_NAME: The name of the database to connect to.
    • DATABASE_USER_NAME: Optional: The database username. Defaults to IAM authentication if unspecified.
    • PASSWORD: Optional: The password for the database user. Defaults to IAM authentication if unspecified.
    • IP_TYPE: Optional: The IP type, such as "Public" (default) or "Private".
  4. Start the Gemini CLI in interactive mode: 
      gemini

    The CLI automatically loads the Gemini CLI extension for Cloud SQL and its tools, which you can use to interact with your database.

    In the Gemini CLI, use the /extensions command to verify the extension is installed and /mcp list command to see the tools.

Gemini CLI for PostgreSQL


1. Install the Gemini CLI.
2. Install the PostgreSQL software extension for Gemini CLI from the GitHub repository using the following command: 
      gemini extensions install https://github.com/gemini-cli-extensions/postgres
3. Set environment variables to connect to your PostgreSQL instance: 
      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"
Replace the following:
  • HOST: The hostname or IP address of the PostgreSQL server.
  • PORT: The port number for the PostgreSQL server.
  • DATABASE: The name of the database to connect to.
  • USER: The database username.
  • PASSWORD: The password for the database user.
  • QUERY_PARAMETERS: Optional: The raw query to be added to the db connection string.
4. Start the Gemini CLI in interactive mode: 
      gemini

The CLI automatically loads the Gemini CLI extension for PostgreSQL and its tools, which you can use to interact with your database.

Gemini Code Assist


1. Install the Gemini Code Assist extension in Visual Studio Code.
2. Enable Agent Mode in Gemini Code Assist chat.
3. In your working directory, create a folder named .gemini. Within it, create a settings.json file.
4. Add the following configuration, replace the environment variables with your values, and then save:


{
  "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. Install Claude Code.
2. Create .mcp.json file in your project root if it does not exist.
3. Add configuration, replace the environment variables with your values, and save: 


{
  "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 desktop


1. Open Claude Desktop and navigate to Settings.
2. Under the Developer tab, tap Edit Config to open the configuration file.
3. Add configuration, replace the environment variables with your values, and save: 


{
  "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"
    }
  }
}

5. Restart Claude Desktop.
6. The new chat screen displays a hammer (MCP) icon with the new MCP server available.

Cline


1. Open Cline extension in VS Code and tap MCP Servers icon.
2. Tap Configure MCP Servers to open the configuration file.
3. Add the following configuration, replace the environment variables with your values, and save: 


{
  "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. A green active status appears after the server connects successfully.

Cursor


1. Create .cursor directory in your project root if it does not exist.
2. Create .cursor/mcp.json file if it does not exist and open it.
3. Add the following configuration, replace the environment variables with your values, and save:


{
  "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. Open Cursor and navigate to Settings > Cursor Settings > MCP. A green active status appears when the server connects.

Visual Studio Code (Copilot)


1. Open VS Code and create .vscode directory in your project root if it does not exist.
2. Create .vscode/mcp.json file if it does not exist, and open it.
3. Add the following configuration, replace the environment variables with your values, and save: 


{
  "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. Open Windsurf and navigate to Cascade assistant.
2. Tap MCP icon, then tap Configure to open the configuration file.
3. Add the following configuration, replace the environment variables with your values, and save: 


{
  "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"
      }
    }
  }
}