使用 MCP Toolbox 将 IDE 连接到 AlloyDB

本页面介绍了如何使用 MCP Toolbox for Databases 将 AlloyDB for PostgreSQL 实例连接到支持 Model Context Protocol (MCP) 的集成开发环境 (IDE) 和开发者工具。您可以使用这些工具运行 SQL 查询并与数据库互动。本指南适用于使用现有 IDE 和开发者工具来处理 AlloyDB 的开发者。

本页面假定您已拥有 AlloyDB 数据库，并且您的 AlloyDB 实例具有公共 IP 地址。如需了解详情，请参阅使用 MCP Toolbox 创建 AlloyDB 数据库。

Model Context Protocol (MCP) 是一种开放协议，用于将大语言模型 (LLM) 连接到 AlloyDB 等数据源。本页面介绍了如何使用 MCP Toolbox for Databases 通过以下 IDE 将开发者辅助工具公开给 AlloyDB 实例：

• Cursor
• Windsurf (Codium)
• Visual Studio Code (Copilot)
• Cline（VS Code 扩展程序）
• Claude Desktop
• Claude Code
• Gemini CLI
• Gemini Code Assist

准备工作

确保您拥有所需的角色。

所需的角色

如需连接到 AlloyDB 实例，您需要以下角色或等效的 Identity and Access Management (IAM) 权限：

• Cloud AlloyDB Client (roles/alloydb.client)
• Service Usage Consumer (roles/serviceusage.serviceUsageConsumer)

设置数据库

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.

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.

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 for PostgreSQL 所需的 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. 创建或选择集群及其主实例。MCP Toolbox 使用 AlloyDB 语言连接器安全地连接到您的实例。
3. 为您的环境配置应用默认凭证 (ADC)。
4. 创建或重复使用数据库用户。准备好输入用户名和密码。

安装 MCP Toolbox

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

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

   chmod +x toolbox
   

3. 验证安装。

   ./toolbox --version
   

配置 MCP 客户端

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

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

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


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



Cursor

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

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

Visual Studio Code (Copilot)

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

{
 "mcp":{
    "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. 打开 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"
      }
    }
  }
}

Gemini CLI

1. 安装 Gemini CLI。
2. 在工作目录中，创建一个名为 .gemini 的文件夹。在该文件夹中，创建一个 settings.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"
      }
    }
  }
}

Gemini Code Assist

1. 在 Visual Studio Code 中安装 Gemini Code Assist 扩展程序。
2. 在 Gemini Code Assist 对话中启用智能体模式。
3. 在工作目录中，创建一个名为 .gemini 的文件夹。在该文件夹中，创建一个 settings.json 文件。
4. 添加以下配置，将环境变量替换为您的值，然后保存。

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

使用 AI 工具

您的 AI 工具现在已使用 MCP 连接到 AlloyDB。尝试提示 AI 助理列出表、创建表或定义和执行其他 SQL 语句。

LLM 可使用以下工具：

• list_tables：列出表和说明。
• execute_sql：执行任何 SQL 语句。
注意：预构建工具的版本低于 1.0，因此不同版本之间可能会有一些工具变化。LLM 会适应可用的工具，因此大多数用户不会受到影响。