Console
    Contact Us Start free

    Use AlloyDB for PostgreSQL with MCP, Gemini CLI, and other agents

    This document describes how to connect your AlloyDB instance to various agents that support the Model Context Protocol (MCP) .

    We recommend using the dedicated AlloyDB extension for Gemini CLI . The Gemini CLI integrates the underlying MCP server directly into the extension, so you don't need to perform a separate server setup. You can configure Gemini Code Assist to use the Gemini CLI, offering similar setup benefits in your IDE.

    Alternatively, other IDEs and agents supporting the MCP can connect through MCP Toolbox for Databases . Toolbox is an open-source MCP server designed to connect AI agents to your data. It handles tasks like authentication and connection pooling, letting you interact with your data with natural language directly from your IDE.

    Before you begin

    To connect to your AlloyDB instance and use the available tools, you must have one of the following Identity and Access Management (IAM) roles, or a custom role with equivalent permissions:

    Task
    Role name
    Required Identity and Access Management (IAM) role
    Use read-only tools to list and get AlloyDB resources
    AlloyDB Viewer
    roles/alloydb.viewer
    Connect to an instance and run queries
    Cloud AlloyDB Client
    roles/alloydb.client
    Service Usage Consumer
    roles/serviceusage.serviceUsageConsumer
    Perform administrative tasks (such as creating or managing clusters, instances, and users)
    AlloyDB Admin
    roles/alloydb.admin
    Use the observability extension
    Monitoring Viewer
    roles/monitoring.viewer

    Before you can connect to your AlloyDB instance, complete the following steps to set up your project and database.

    1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

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

      Roles required to select or create a project

      • Select a project : Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
      • Create a project : To create a project, you need the Project Creator ( roles/resourcemanager.projectCreator ), which contains the resourcemanager.projects.create permission. Learn how to grant roles .

      Go to project selector

    3. Verify that billing is enabled for your Google Cloud project .

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

      Roles required to select or create a project

      • Select a project : Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
      • Create a project : To create a project, you need the Project Creator ( roles/resourcemanager.projectCreator ), which contains the resourcemanager.projects.create permission. Learn how to grant roles .

      Go to project selector

    5. Verify that billing is enabled for your Google Cloud project .

      6.

    6. Enable the Cloud APIs necessary to create and connect to AlloyDB.

      Enable the APIs

      1. In the Confirm project step, click Next to confirm the name of the project you are going to make changes to.

      2. In the Enable APIs step, click Enable to enable the following:

        • AlloyDB API
        • Compute Engine API
        • Cloud Resource Manager API
        • Service Networking API

        The Service Networking API is required if you plan to configure network connectivity to AlloyDB using a VPC network that resides in the same Google Cloud project as AlloyDB.

        The Compute Engine API and Cloud Resource Manager API are required if you plan to configure network connectivity to AlloyDB using a VPC network that resides in a different Google Cloud project.

    7. Create or select a cluster and its primary instance .
    8. Configure Application Default Credentials (ADC) for your environment.
    9. Create or reuse a database user . Be ready to enter the username and password.

    Use the Gemini CLI extensions for AlloyDB

    Gemini CLI is an open-source AI agent designed to assist with development workflows by assisting with coding, debugging, data exploration, and content creation. Its mission is to provide an agentic interface for interacting with Data Cloud services and popular open-source databases.

    The integration with Gemini CLI is through dedicated extensions that offer additional capabilities compared to a standard MCP Toolbox connection. The following sections describe the alloydb and alloydb-observability extensions, which offer an installation process and a set of tools. The open-source extensions contains detailed information on installation, configuration, and usage examples. For more information, see the Gemini CLI Extension - AlloyDB for PostgreSQL .

    The alloydb extension includes tools for querying the database, managing AlloyDB resources, and monitoring database health.

    The following examples use a sample ecommerce database with the following tables:

    • products : contains product information, including product_id , product_name , category , and price .
    • customers : stores customer data, such as customer_id , first_name , last_name , and email .
    • orders : holds order information, including order_id , customer_id , and order_date .
    Category
    Tools
    Example natural language prompt
    Database operations
    list_tables
    Show me all the tables in the current database.
    execute_sql
    Show me the 10 most expensive products in the 'Laptops' category.
    list_active_queries
    What queries are running on the database?
    get_query_plan
    Explain the query plan for a query that finds all customers who have not placed an order in the last 6 months.
    list_available_extensions
    What are the available extensions I can install?
    list_installed_extensions
    List all the extensions that are installed.
    Resource management
    clusters, instances, users
    create_cluster
    Create an AlloyDB cluster named sales-quarterly-db in the us-east1 region.
    get_cluster
    Get the details for the cluster sales-quarterly-db .
    list_clusters
    List all of my AlloyDB clusters.
    create_instance
    Create a new read instance in the sales-quarterly-db cluster.
    get_instance
    Show me the information for the instance sales-quarterly-db-rp .
    list_instances
    List all instances in the sales-quarterly-db cluster.
    create_user
    Create a new database user named reporting_user with password report_password .
    Create a new IAM database user for reporting_user@example.com .
    get_user
    Get the information for the user reporting_user .
    list_users
    List all database users.
    wait_for_operation
    What is the status of the operation operation-163562789 ?
    Database health & maintenance
    list_autovacuum_configurations
    Show me the current autovacuum configuration.
    list_memory_configurations
    What are the current memory configurations for the primary instance?
    list_top_bloated_tables
    List the top five most bloated tables.
    list_replication_slots
    Display all active replication slots.
    list_invalid_indexes
    Check for any invalid indexes in the ecommerce database.

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

    Category
    Tools
    Example natural language prompt
    Observability
    get_system_metrics
    What are the system metrics, like CPU usage, for the last hour?
    get_query_metrics
    Show me the query performance metrics from the last 15 minutes.

    You can use the Gemini CLI extension for AlloyDB in two ways:

    • A standalone command-line tool
    • Integrated into your IDE with Gemini Code Assist

    Gemini CLI

    1. Install the Gemini CLI .
    2. Install the AlloyDB extension for Gemini CLI from the GitHub repository using the following command: 
      gemini extensions install https://github.com/gemini-cli-extensions/alloydb
    3. Set environment variables to connect to your AlloyDB instance: 
      export ALLOYDB_POSTGRES_PROJECT=" PROJECT_ID 
"
export ALLOYDB_POSTGRES_REGION=" REGION 
"
export ALLOYDB_POSTGRES_CLUSTER=" CLUSTER_NAME 
"
export ALLOYDB_POSTGRES_INSTANCE=" INSTANCE_NAME 
"
export ALLOYDB_POSTGRES_DATABASE=" DATABASE_NAME 
"

      The Gemini CLI extension for AlloyDB uses your [application default credentials (ADC)](/authentication/application-default-credentials) for authentication by default. If you want to connect as a database user instead, set the following optional environment variables:

      #Optional: Set for database user authentication
export ALLOYDB_POSTGRES_USER=" USERNAME 
"
export ALLOYDB_POSTGRES_PASSWORD=" PASSWORD 
"

      To connect using a private IP address, you must also set the following environment variable:

      export ALLOYDB_POSTGRES_IP_TYPE="private"
    4. Start the Gemini CLI in interactive mode: 
      gemini
       The CLI automatically loads the AlloyDB extension for Gemini CLI extension and its tools, which you can use to interact with your database.

    Gemini Code Assist

    We recommend to configure Gemini Code Assist to use the Gemini CLI, this approach removes the need to manually configure an MCP server.

    1. Make sure you have installed and configured the Gemini CLI and the alloydb extension .
    2. Configure Gemini Code Assist to use the Gemini CLI .
    3. Start interacting with your AlloyDB instance using natural language directly within the Gemini Code Assist chat.

    Connect with other IDEs using MCP Toolbox for Databases

    This section describes how to connect to your AlloyDB instance from various agents using MCP Toolbox for Databases . Toolbox acts as an open-source Model Context Protocol (MCP) server that sits between your IDE and your database, providing a control plane for your AI tools. This section provides instructions for connecting to an AlloyDB instance using either a public or private IP address. By default, Toolbox uses a public IP address, but you can configure a private IP connection by setting the ALLOYDB_POSTGRES_IP_TYPE environment variable as shown in the configuration examples.

    Install MCP Toolbox for Databases

    To connect your IDE to AlloyDB, you must install MCP Toolbox for Databases, an open-source server that connects AI agents to your data.

    1. Download the latest version of Toolbox as a binary. Select the binary corresponding to your operating system (OS) and CPU architecture. You must use Toolbox version v0.15.0 or later.

      linux/amd64

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

      darwin/arm64

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

      darwin/amd64

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

      windows/amd64

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

    2. Make the binary an executable.

       chmod  
+x  
toolbox

    3. Verify the installation.

       ./toolbox  
--version

    Configure your client

    Select your agent tool from the following options:

    Claude code

    1. Install Claude Code .
    2. Create the .mcp.json file in your project root, if it doesn't exist.
    3. Add the configuration, replace the environment variables with your values, and save.

    {
  "mcpServers": {
    "alloydb": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","alloydb-postgres","--stdio"],
      "env": {
          "ALLOYDB_POSTGRES_PROJECT": " PROJECT_ID 
",
          "ALLOYDB_POSTGRES_REGION": " REGION 
",
          "ALLOYDB_POSTGRES_CLUSTER": " CLUSTER_NAME 
",
          "ALLOYDB_POSTGRES_INSTANCE": " INSTANCE_NAME 
",
          "ALLOYDB_POSTGRES_DATABASE": " DATABASE_NAME 
",
          "ALLOYDB_POSTGRES_USER": " USERNAME 
",
          "ALLOYDB_POSTGRES_PASSWORD": " PASSWORD 
"
      }
    }
  }
}

    Claude desktop

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

    {
  "mcpServers": {
    "alloydb": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","alloydb-postgres","--stdio"],
      "env": {
          "ALLOYDB_POSTGRES_PROJECT": " PROJECT_ID 
",
          "ALLOYDB_POSTGRES_REGION": " REGION 
",
          "ALLOYDB_POSTGRES_CLUSTER": " CLUSTER_NAME 
",
          "ALLOYDB_POSTGRES_INSTANCE": " INSTANCE_NAME 
",
          "ALLOYDB_POSTGRES_DATABASE": " DATABASE_NAME 
",
          "ALLOYDB_POSTGRES_USER": " USERNAME 
",
          "ALLOYDB_POSTGRES_PASSWORD": " PASSWORD 
"
      }
    }
  }
}
    1. Restart Claude Desktop.
    2. The new chat screen displays a hammer (MCP) icon with the new MCP server.

    Cline

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

    {
  "mcpServers": {
    "alloydb": {
     "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","alloydb-postgres","--stdio"],
      "env": {
          "ALLOYDB_POSTGRES_PROJECT": " PROJECT_ID 
",
          "ALLOYDB_POSTGRES_REGION": " REGION 
",
          "ALLOYDB_POSTGRES_CLUSTER": " CLUSTER_NAME 
",
          "ALLOYDB_POSTGRES_INSTANCE": " INSTANCE_NAME 
",
          "ALLOYDB_POSTGRES_DATABASE": " DATABASE_NAME 
",
          "ALLOYDB_POSTGRES_USER": " USERNAME 
",
          "ALLOYDB_POSTGRES_PASSWORD": " PASSWORD 
"
      }
    }
  }
}
    A green active status appears after the server connects successfully.

    Cursor

    1. Create the .cursor directory in your project root if it doesn't exist.
    2. Create the .cursor/mcp.json file if it doesn't exist, and open it.
    3. Add the following configuration, replace the environment variables with your values, and save.
    {
  "mcpServers": {
    "alloydb": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","alloydb-postgres","--stdio"],
      "env": {
          "ALLOYDB_POSTGRES_PROJECT": " PROJECT_ID 
",
          "ALLOYDB_POSTGRES_REGION": " REGION 
",
          "ALLOYDB_POSTGRES_CLUSTER": " CLUSTER_NAME 
",
          "ALLOYDB_POSTGRES_INSTANCE": " INSTANCE_NAME 
",
          "ALLOYDB_POSTGRES_DATABASE": " DATABASE_NAME 
",
          "ALLOYDB_POSTGRES_USER": " USERNAME 
",
          "ALLOYDB_POSTGRES_PASSWORD": " PASSWORD 
"
      }
    }
  }
}
    1. 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 the .vscode/mcp.json file if it doesn't exist, and open it.
    3. Add the following configuration, replace the environment variables with your values, and save.
    {
  "servers": {
    "alloydb": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","alloydb-postgres","--stdio"],
      "env": {
        "ALLOYDB_POSTGRES_PROJECT": " PROJECT_ID 
",
        "ALLOYDB_POSTGRES_REGION": " REGION 
",
        "ALLOYDB_POSTGRES_CLUSTER": " CLUSTER_NAME 
",
        "ALLOYDB_POSTGRES_INSTANCE": " INSTANCE_NAME 
",
        "ALLOYDB_POSTGRES_DATABASE": " DATABASE_NAME 
",
        "ALLOYDB_POSTGRES_USER": " USERNAME 
",
        "ALLOYDB_POSTGRES_PASSWORD": " PASSWORD 
"
      }
    }
  }
}

    Windsurf

    1. Open Windsurf and navigate to Cascade assistant.
    2. Click the MCP icon, then click Configure to open the configuration file.
    3. Add the following configuration, replace the environment variables with your values, and save.
    {
  "mcpServers": {
    "alloydb": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","alloydb-postgres","--stdio"],
      "env": {
          "ALLOYDB_POSTGRES_PROJECT": " PROJECT_ID 
",
          "ALLOYDB_POSTGRES_REGION": " REGION 
",
          "ALLOYDB_POSTGRES_CLUSTER": " CLUSTER_NAME 
",
          "ALLOYDB_POSTGRES_INSTANCE": " INSTANCE_NAME 
",
          "ALLOYDB_POSTGRES_DATABASE": " DATABASE_NAME 
",
          "ALLOYDB_POSTGRES_USER": " USERNAME 
",
          "ALLOYDB_POSTGRES_PASSWORD": " PASSWORD 
"
      }
    }
  }
}
    Design a Mobile Site
    View Site in Mobile | Classic
    Share by: