搭配使用 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) 角色，或是具備同等權限的自訂角色：

工作	角色名稱	必要的身分與存取權管理 (IAM) 角色
使用唯讀工具列出及取得 AlloyDB 資源	AlloyDB 檢視者	`roles/alloydb.viewer`
連線至執行個體並執行查詢	Cloud AlloyDB 用戶端	`roles/alloydb.client`
連線至執行個體並執行查詢	服務使用情形用戶	`roles/serviceusage.serviceUsageConsumer`
執行管理工作 (例如建立或管理叢集、執行個體和使用者)	AlloyDB 管理員	`roles/alloydb.admin`
使用可觀測性擴充功能	監控檢視者	`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 role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

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 role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

啟用建立及連線至 AlloyDB 時所需的 Cloud API。

啟用 API
1. 在「確認專案」步驟中，按一下「下一步」，確認要變更的專案名稱。
2. 在「啟用 API」步驟中，按一下「啟用」，啟用下列項目：
  - AlloyDB API
  - Compute Engine API
  - Cloud Resource Manager API
  - Service Networking API
  如果您打算使用與 AlloyDB 位於相同 Google Cloud 專案的虛擬私有雲網路，設定 AlloyDB 的網路連線，則必須啟用 Service Networking API。
  
  如要使用位於不同 Google Cloud 專案的虛擬私有雲網路，設定 AlloyDB 的網路連線，則必須使用 Compute Engine API 和 Cloud Resource Manager API。
建立或選取叢集及其主要執行個體。
為環境設定應用程式預設憑證 (ADC)。
建立或重複使用資料庫使用者。準備好輸入使用者名稱和密碼。

使用 AlloyDB 的 Gemini CLI 擴充功能

Gemini CLI 是開放原始碼的 AI 代理，可協助程式設計、偵錯、資料探索和內容建立，進而提升開發工作流程效率。其任務是提供代理介面，與 Data Cloud 服務和熱門的開放原始碼資料庫互動。

與 Gemini CLI 的整合是透過專屬擴充功能進行，與標準 MCP Toolbox 連線相比，可提供額外功能。以下各節說明 alloydb 和 alloydb-observability 擴充功能，這兩者提供安裝程序和一組工具。開放原始碼擴充功能包含安裝、設定和使用範例的詳細資訊。詳情請參閱「Gemini CLI 擴充功能 - PostgreSQL 適用的 AlloyDB」。

AlloyDB 擴充功能

alloydb 擴充功能包含查詢資料庫、管理 AlloyDB 資源，以及監控資料庫健康狀態的工具。

下列範例使用範例 ecommerce 資料庫，其中包含下列資料表：

products：包含產品資訊，包括 product_id、product_name、category 和 price。
customers：儲存客戶資料，例如 customer_id、first_name、last_name 和 email。
orders：包含訂單資訊，包括 order_id、customer_id 和 order_date。

類別	工具	自然語言提示範例
資料庫作業	`database_overview`	請簡要說明目前的資料庫。
	`list_tables`	顯示目前資料庫中的所有資料表。
	`execute_sql`	顯示「筆記型電腦」類別中價格最高的 10 項產品。
	`list_active_queries`	資料庫正在執行哪些查詢？
	`get_query_plan`	說明查詢計畫，找出過去 6 個月內未下單的所有顧客。
	`list_available_extensions`	我可以安裝哪些擴充功能？
	`list_installed_extensions`	列出所有已安裝的擴充功能。
	`list_indexes`	列出 `products` 資料表中的所有索引。
	`list_locks`	顯示資料庫的所有有效鎖定。
	`list_schemas`	列出資料庫中的所有結構定義。
	`list_sequences`	顯示目前結構定義中的所有序列。
	`list_triggers`	列出 `orders` 資料表的所有觸發程序。
	`list_views`	Show me all the views in the `sales` schema.
資源管理叢集、執行個體、使用者	`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`	注意：`create_user` 工具可以建立兩種類型的資料庫使用者：使用內建驗證機制的資料庫使用者：這類使用者是在資料庫中管理，並透過密碼驗證。 IAM 使用者：這類使用者在 IAM 中管理，並使用 IAM 憑證進行驗證。使用內建驗證機制建立資料庫使用者時，您必須提供密碼。建立 IAM 使用者時，您必須提供 IAM 主體。建立名為 `reporting_user` 的新資料庫使用者，密碼為 `report_password`。為 `reporting_user@example.com` 建立新的 IAM 資料庫使用者。
	`get_user`	取得使用者 `reporting_user` 的資訊。
	`list_users`	列出所有資料庫使用者。
	`wait_for_operation`	作業 `operation-163562789` 的狀態為何？
資料庫健康狀態和維護	`list_autovacuum_configurations`	顯示目前的自動清除垃圾設定。
	`list_memory_configurations`	主要執行個體目前的記憶體設定為何？
	`list_top_bloated_tables`	列出前五個最臃腫的資料表。
	`list_replication_slots`	顯示所有有效的複製時段。
	`replication_stats`	顯示目前的複製統計資料。
	`list_invalid_indexes`	檢查 `ecommerce` 資料庫中是否有無效的索引。
	`long_running_transactions`	是否有任何長時間執行的交易？

AlloyDB Observability 擴充功能

alloydb-observability 擴充功能提供統一介面，方便您直接透過 Gemini CLI 管理及監控資料庫效能和健康狀態。

類別	工具	自然語言提示範例
觀測能力	`get_system_metrics`	過去一小時的系統指標 (例如 CPU 使用量) 為何？
觀測能力	`get_query_metrics`	顯示過去 15 分鐘的查詢效能指標。

您可以使用 Gemini CLI 擴充功能，透過下列兩種方式存取 AlloyDB：

獨立指令列工具
透過 Gemini Code Assist 整合至 IDE

Gemini CLI

安裝 Gemini CLI。
使用下列指令，從 GitHub 存放區安裝 Gemini CLI 的 AlloyDB 擴充功能：
```
gemini extensions install https://github.com/gemini-cli-extensions/alloydb
```

設定環境變數，連線至 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"

在互動模式下啟動 Gemini CLI：
```
gemini
```
CLI 會自動載入 Gemini CLI 擴充功能的 AlloyDB 擴充功能和工具，您可以使用這些工具與資料庫互動。

Gemini Code Assist

建議您將 Gemini Code Assist 設定為使用 Gemini CLI，這樣就不必手動設定 MCP 伺服器。

確認已安裝並設定 Gemini CLI 和 alloydb 擴充功能。
設定 Gemini Code Assist，以便使用 Gemini CLI。
直接在 Gemini Code Assist 對話中，以自然語言與 AlloyDB 執行個體互動。

連結至 Antigravity

您可以透過下列方式將 AlloyDB 連線至 Antigravity：

使用 MCP 商店
使用自訂設定

注意：您不需要下載 MCP Toolbox 二進位檔，即可使用這些方法。

MCP 商店

我們最建議使用內建的 MCP 商店，在 Antigravity 中連線至 AlloyDB。

開啟 Antigravity，然後開啟編輯器的代理程式面板。
按一下面板頂端的「...」圖示，然後選取「MCP Servers」。
在可用伺服器清單中找到「PostgreSQL 適用的 AlloyDB」，然後點選「安裝」。
按照畫面上的提示安全地連結帳戶 (如適用)。

在 MCP 商店中安裝 AlloyDB 後，編輯器會自動提供伺服器的資源和工具。

自訂設定

如要連線至自訂 MCP 伺服器，請按照下列步驟操作：

開啟 Antigravity，然後開啟編輯器的代理程式面板。
按一下面板頂端的「...」圖示，然後選取「MCP Servers」。
依序點選「Manage MCP Servers」>「View raw config」，開啟 mcp_config.json 檔案。
在 mcp_config.json 檔案中新增並儲存下列設定。

{
  "mcpServers": {
    "alloydb-postgres": {
      "command": "npx",
      "args": ["-y","@toolbox-sdk/server","--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 位址連線，請將 "ALLOYDB_POSTGRES_IP_TYPE": "private" 屬性新增至 env 物件。請務必在前一行加上半形逗號，確保 JSON 有效。

更改下列內容：

PROJECT_ID：您的 Google Cloud 專案 ID。
REGION：您的 AlloyDB 區域名稱。
CLUSTER_NAME：您的 AlloyDB 叢集名稱。
INSTANCE_NAME：您的 AlloyDB 執行個體名稱。
DATABASE_NAME：您的 AlloyDB 資料庫名稱。
：ALLOYDB_POSTGRES_USER變數的 AlloyDB 使用者名稱。USERNAME
PASSWORD：ALLOYDB_POSTGRES_PASSWORD 變數的 AlloyDB 密碼。

使用 MCP Toolbox for Databases 連線至其他 IDE

本節說明如何使用 MCP Toolbox for Databases，從各種代理程式連線至 AlloyDB 執行個體。Toolbox 可做為開放原始碼的模型上下文協定 (MCP) 伺服器，介於 IDE 和資料庫之間，為 AI 工具提供控制平面。本節將說明如何使用公開或私人 IP 位址連線至 AlloyDB 執行個體。根據預設，Toolbox 會使用公開 IP 位址，但您可以設定 ALLOYDB_POSTGRES_IP_TYPE 環境變數，如設定範例所示，設定私人 IP 連線。

安裝 MCP Toolbox for Databases

如要將 IDE 連線至 AlloyDB，您必須安裝 MCP Toolbox for Databases，這是一項開放原始碼伺服器，可將 AI 代理程式連線至您的資料。

以二進位檔形式下載最新版 Toolbox。選取與作業系統 (OS) 和 CPU 架構對應的二進位檔。您必須使用 Toolbox v0.15.0 以上版本。

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

將二進位檔設為可執行檔。
```
chmod +x toolbox
```
驗證安裝。
```
./toolbox --version
```

設定用戶端

從下列選項中選取代理程式工具：

Claude 代碼

安裝 Claude Code。
如果專案根目錄中沒有 .mcp.json 檔案，請建立該檔案。
新增設定、將環境變數替換為您的值，然後儲存。

{
  "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 電腦版

開啟 Claude Desktop，然後前往「設定」。
在「開發人員」分頁中，按一下「編輯設定」開啟設定檔。
新增設定、將環境變數替換為您的值，然後儲存。

{
  "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。
新的即時通訊畫面會顯示槌子 (MCP) 圖示和新的 MCP 伺服器。

Cline

在 VS Code 中開啟 Cline 擴充功能，然後輕觸「MCP Servers」圖示。
按一下「設定 MCP 伺服器」開啟設定檔。
新增下列設定，將環境變數換成您的值，然後儲存。

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

Cursor

如果專案根目錄中沒有 .cursor 目錄，請建立該目錄。
如果 .cursor/mcp.json 檔案不存在，請建立並開啟該檔案。
新增下列設定，將環境變數換成您的值，然後儲存。

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

開啟「游標」，然後依序前往「設定」>「游標設定」>「MCP」。伺服器連線後，會顯示綠色的「有效」狀態。

Visual Studio Code (Copilot)

開啟 VS Code，並在專案根目錄中建立 .vscode 目錄 (如果不存在)。
如果 .vscode/mcp.json 檔案不存在，請建立並開啟該檔案。
新增下列設定，將環境變數換成您的值，然後儲存。

{
  "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，然後前往 Cascade 助理。
按一下 MCP 圖示，然後點選「設定」開啟設定檔。
新增下列設定，將環境變數換成您的值，然後儲存。

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

搭配使用 AlloyDB for PostgreSQL 與 MCP、Gemini CLI 和其他代理程式 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

事前準備

使用 AlloyDB 的 Gemini CLI 擴充功能

AlloyDB 擴充功能

AlloyDB Observability 擴充功能

Gemini CLI

Gemini Code Assist

連結至 Antigravity

MCP 商店

自訂設定

使用 MCP Toolbox for Databases 連線至其他 IDE

安裝 MCP Toolbox for Databases

linux/amd64

darwin/arm64

darwin/amd64

windows/amd64

設定用戶端

Claude 代碼

Claude 電腦版

Cline

Cursor

Visual Studio Code (Copilot)

滑浪風帆

搭配使用 AlloyDB for PostgreSQL 與 MCP、Gemini CLI 和其他代理程式