将 AlloyDB for PostgreSQL 与 MCP、Gemini CLI 和其他代理搭配使用

本文档介绍了如何将 AlloyDB 实例连接到支持 Model Context Protocol (MCP) 的各种代理。

我们建议使用 Gemini CLI 的专用 AlloyDB 扩展程序。Gemini CLI 直接将底层 MCP 服务器集成到扩展程序中，因此您无需单独设置服务器。您可以将 Gemini Code Assist 配置为使用 Gemini CLI，从而在 IDE 中获得类似的设置优势。

或者，支持 MCP 的其他 IDE 和代理可以通过 MCP Toolbox for Databases 进行连接。Toolbox 是一款开源 MCP 服务器，旨在将 AI 智能体连接到您的数据。它可处理身份验证和连接池等任务，让您可以直接通过 IDE 使用自然语言与数据进行交互。

准备工作

如需连接到 AlloyDB 实例并使用可用工具，您必须拥有以下 Identity and Access Management (IAM) 角色之一，或者拥有具有等效权限的自定义角色：

任务	角色名称	所需的 Identity and Access Management (IAM) 角色
使用只读工具列出和获取 AlloyDB 资源	AlloyDB Viewer	roles/alloydb.viewer
连接到实例并运行查询	Cloud AlloyDB Client	roles/alloydb.client
	Service Usage Consumer	roles/serviceusage.serviceUsageConsumer
执行管理任务（例如创建或管理集群、实例和用户）	AlloyDB Admin	roles/alloydb.admin
使用可观测性扩展程序	Monitoring Viewer	roles/monitoring.viewer

在连接到 AlloyDB 实例之前，请完成以下步骤来设置项目和数据库。

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.

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.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

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.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

1. 启用创建和连接到 AlloyDB 所需的 Cloud API。

   启用 API

   1. 在确认项目步骤中，点击下一步以确认您要更改的项目的名称。

   2. 在启用 API 步骤中，点击启用以启用以下内容：

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

      如果您计划使用与 AlloyDB 位于同一 Google Cloud 项目中的 VPC 网络配置与 AlloyDB 的网络连接，则需要使用 Service Networking API。

      如果您计划使用位于其他 Google Cloud 项目中的 VPC 网络配置与 AlloyDB 的网络连接，则需要使用 Compute Engine API 和 Cloud Resource Manager API。

2. 创建或选择集群及其主实例。
3. 为您的环境配置应用默认凭证 (ADC)。
4. 创建或重复使用数据库用户。准备好输入用户名和密码。

使用适用于 AlloyDB 的 Gemini CLI 扩展程序

注意： AlloyDB Gemini CLI 扩展程序基于 MCP Toolbox for Databases。MCP Toolbox for Databases 目前为 Beta 版（v1.0 之前的版本），在第一个稳定版本 (v1.0) 发布之前，可能会出现重大变更。

Gemini CLI 是一款开源 AI 智能体，旨在通过协助编码、调试、数据探索和内容创建来帮助完成开发工作流。其使命是提供一个智能体接口，用于与 Data Cloud 服务和热门的开源数据库进行互动。

与 Gemini CLI 的集成是通过专用扩展程序实现的，与标准 MCP Toolbox 连接相比，该扩展程序可提供更多功能。以下部分介绍了 alloydb 和 alloydb-observability 扩展程序，它们提供安装流程和一组工具。该开源扩展程序包含有关安装、配置和使用示例的详细信息。如需了解详情，请参阅 Gemini CLI 扩展程序 - AlloyDB for PostgreSQL。

alloydb 扩展程序包含用于查询数据库、管理 AlloyDB 资源和监控数据库健康状况的工具。

类别	工具	自然语言提示示例
数据库操作	list_tables	显示当前数据库中的所有表。
	execute_sql	运行查询：SELECT * FROM products WHERE category = 'electronics';
	list_active_queries	数据库上正在运行哪些查询？
	get_query_plan	针对“SELECT * FROM customers WHERE last_seen > '2025-08-01'”解释查询计划
	list_available_extensions	我可以安装哪些可用的扩展程序？
	list_installed_extensions	列出所有已安装的扩展程序。
资源管理 集群、实例、用户	create_cluster	在 us-east1 区域中创建一个名为 sales-quarterly-db 的 AlloyDB 集群。
	get_cluster	获取集群 sales-quarterly-db 的详细信息。
	list_clusters	列出我的所有 AlloyDB 集群。
	create_instance	在 sales-quarterly-db 集群中创建新的读取实例。
	get_instance	显示实例 sales-quarterly-db-rp 的信息。
	list_instances	列出 sales-quarterly-db 集群中的所有实例。
	create_user	创建名为 reporting_user 的新数据库用户。
	get_user	获取用户 reporting_user 的信息。
	list_users	列出所有数据库用户。
	wait_for_operation	操作 operation-163562789 的状态是什么？
数据库健康状况和维护	list_autovacuum_configurations	显示当前的自动清理配置。
	list_memory_configurations	主实例的当前内存配置是什么？
	list_top_bloated_tables	列出膨胀程度最高的五个表。
	list_replication_slots	显示所有有效的复制槽。
	list_invalid_indexes	检查 orders 数据库中是否存在任何无效索引。

alloydb-observability 扩展程序提供了一个统一的界面，用于直接从 Gemini CLI 管理和监控数据库性能和健康状况。

类别	工具	自然语言提示示例
可观测性	get_system_metrics	过去一小时的系统指标（例如 CPU 使用情况）是多少？
	get_query_metrics	显示过去 15 分钟内的查询性能指标。

您可以通过以下两种方式使用适用于 AlloyDB 的 Gemini CLI 扩展程序：

• 独立命令行工具
• 通过 Gemini Code Assist 集成到 IDE 中

Gemini CLI

1. 安装 Gemini CLI。
2. 使用以下命令从 GitHub 代码库安装适用于 Gemini CLI 的 AlloyDB 扩展程序：

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

3. 设置环境变量以连接到 AlloyDB 实例：

   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"
   

   AlloyDB 的 Gemini CLI 扩展程序默认使用您的 [应用默认凭据 (ADC)](/authentication/application-default-credentials) 进行身份验证。如果您想以数据库用户的身份连接，请设置以下可选环境变量：

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

   如需使用专用 IP 地址进行连接，您还必须设置以下环境变量：

   export ALLOYDB_POSTGRES_IP_TYPE="private"
   

4. 以互动模式启动 Gemini CLI：

   gemini
   

   该 CLI 会自动加载适用于 Gemini CLI 的 AlloyDB 扩展程序及其工具，您可以使用这些工具与数据库进行交互。

Gemini Code Assist

我们建议您将 Gemini Code Assist 配置为使用 Gemini CLI，因为这种方法无需手动配置 MCP 服务器。

1. 确保您已安装并配置 Gemini CLI 和 alloydb 扩展程序。
2. 将 Gemini Code Assist 配置为使用 Gemini CLI。
3. 直接在 Gemini Code Assist 对话窗口中使用自然语言开始与 AlloyDB 实例互动。

使用 MCP Toolbox for Databases 连接其他 IDE

本部分介绍了如何使用 MCP Toolbox for Databases 从各种代理连接到 AlloyDB 实例。该工具箱充当位于 IDE 和数据库之间的开源 Model Context Protocol (MCP) 服务器，为 AI 工具提供控制平面。本部分介绍了如何使用公共或专用 IP 地址连接到 AlloyDB 实例。默认情况下，Toolbox 使用公共 IP 地址，但您可以通过设置 ALLOYDB_POSTGRES_IP_TYPE 环境变量来配置专用 IP 连接，如配置示例所示。

安装 MCP Toolbox for Databases

如需将 IDE 连接到 AlloyDB，您必须安装 MCP Toolbox for Databases，这是一款可将 AI 智能体连接到您的数据的开源服务器。

1. 以二进制文件形式下载最新版本的 Toolbox。选择与您的操作系统 (OS) 和 CPU 架构对应的二进制文件。您必须使用 v0.15.0 或更高版本的 Toolbox。

   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. 将该二进制文件设为可执行文件。

   chmod +x toolbox
   

3. 验证安装。

   ./toolbox --version
   

配置客户端

从以下选项中选择您的智能体工具：

Claude Code

1. 安装 Claude Code。
2. 在项目根目录中创建 .mcp.json 目录（如果尚不存在）。
3. 添加配置，将环境变量替换为您的值，然后保存。




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

注意：如需使用专用 IP 地址进行连接，请将以下行添加到 env 对象："ALLOYDB_POSTGRES_IP_TYPE": "private"

Claude Desktop

1. 打开 Claude Desktop，然后前往设置。
2. 在开发者标签页中，点击修改配置以打开配置文件。
3. 添加配置，将环境变量替换为您的值，然后保存。




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

注意：如需使用专用 IP 地址进行连接，请将以下行添加到 env 对象："ALLOYDB_POSTGRES_IP_TYPE": "private"

4. 重启 Claude Desktop。
5. 新聊天界面会显示锤子 (MCP) 图标以及新的 MCP 服务器。

Cline

1. 在 VS Code 中打开 Cline 扩展程序，然后点按 MCP 服务器图标。
2. 点击配置 MCP 服务器以打开配置文件。
3. 添加以下配置，将环境变量替换为您的值，然后保存。




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


服务器成功连接后，系统会显示绿色的活跃状态。



注意：如需使用专用 IP 地址进行连接，请将以下行添加到 env 对象："ALLOYDB_POSTGRES_IP_TYPE": "private"

光标

1. 在项目根目录中创建 .cursor 目录（如果尚不存在）。
2. 创建 .cursor/mcp.json 文件（如果尚不存在）并打开该文件。
3. 添加以下配置，将环境变量替换为您的值，然后保存。

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

注意：如需使用专用 IP 地址进行连接，请将以下行添加到 env 对象："ALLOYDB_POSTGRES_IP_TYPE": "private"

4. 打开 Cursor，然后依次前往设置 > Cursor 设置 > MCP。服务器连接时，系统会显示绿色的活跃状态。

Visual Studio Code (Copilot)

1. 打开 VS Code，并在项目根目录中创建 .vscode 目录（如果尚不存在）。
2. 创建 .vscode/mcp.json 文件（如果尚不存在）并打开该文件。
3. 添加以下配置，将环境变量替换为您的值，然后保存。

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

注意：如需使用专用 IP 地址进行连接，请将以下行添加到 env 对象："ALLOYDB_POSTGRES_IP_TYPE": "private"

Windsurf

1. 打开 Windsurf 并前往 Cascade 助理。
2. 点击 MCP 图标，然后点击配置以打开配置文件。
3. 添加以下配置，将环境变量替换为您的值，然后保存。

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

注意：如需使用专用 IP 地址进行连接，请将以下行添加到 env 对象："ALLOYDB_POSTGRES_IP_TYPE": "private"