MCP Reference: cloud-sql

Model Context Protocol (MCP) 伺服器可做為代理伺服器，在外部服務與大型語言模型 (LLM) 或 AI 應用程式之間傳輸內容、資料或功能。MCP 伺服器會將 AI 應用程式連線至資料庫和 Web 服務等外部系統，並將系統回覆轉換成 AI 應用程式可理解的格式。

伺服器設定

您必須先啟用 MCP 伺服器並設定驗證，才能使用這項功能。如要進一步瞭解如何使用 Google 和 Google Cloud 遠端 MCP 伺服器，請參閱 Google Cloud MCP 伺服器總覽。

MCP 適用的 Cloud SQL Admin API

伺服器端點

MCP 服務端點是 MCP 伺服器的網路位址和通訊介面 (通常是網址)，AI 應用程式 (MCP 用戶端的主機) 會使用這個端點建立安全標準連線。這是 LLM 請求脈絡、呼叫工具或存取資源的聯絡點。Google MCP 端點可以是全域或區域。

cloud-sql MCP 伺服器具有下列 MCP 端點：

  • https://sqladmin.googleapis.com/mcp

MCP 工具

MCP 工具是 MCP 伺服器向 LLM 或 AI 應用程式公開的函式或可執行功能，可在現實世界中執行動作。

cloud-sql MCP 伺服器提供下列工具：

MCP 工具
list_instances 列出專案中的所有 Cloud SQL 執行個體。
get_instance 取得 Cloud SQL 執行個體的詳細資料。
create_instance

啟動 Cloud SQL 執行個體的建立作業。

  • 這項工具會傳回長時間執行的作業。使用 get_operation 工具輪詢狀態，直到作業完成為止。
  • 建立執行個體作業可能需要幾分鐘的時間。使用指令列工具暫停 30 秒，然後重新檢查狀態。
  • 使用 create_instance 工具建立執行個體後，您可以使用 create_user 工具，為目前登入專案的使用者建立 IAM 使用者帳戶。

  • data_api_access 的預設值為 ALLOW_DATA_API。這項設定可讓您使用 execute_sql 工具和 executeSql API 執行 SQL 陳述式。

除非另有指定，否則新建立的執行個體會使用開發環境的預設執行個體設定。

以下是開發環境中執行個體的預設設定：

{
  "tier": "db-perf-optimized-N-2",
  "data_disk_size_gb": 100,
  "region": "us-central1",
  "database_version": "POSTGRES_18",
  "edition": "ENTERPRISE_PLUS",
  "availability_type": "ZONAL",
  "tags": [{"environment": "dev"}]
}

建議您在正式環境中，為執行個體設定下列項目：

{
  "tier": "db-perf-optimized-N-8",
  "data_disk_size_gb": 250,
  "region": "us-central1",
  "database_version": "POSTGRES_18",
  "edition": "ENTERPRISE_PLUS",
  "availability_type": "REGIONAL",
  "tags": [{"environment": "prod"}]
}

建議您為 SQL Server 採用下列執行個體設定：

{
  "tier": "db-perf-optimized-N-8",
  "data_disk_size_gb": 250,
  "region": "us-central1",
  "database_version": "SQLSERVER_2022_STANDARD",
  "edition": "ENTERPRISE_PLUS",
  "availability_type": "REGIONAL",
  "tags": [{"environment": "prod"}]
}
execute_sql

在 Cloud SQL 執行個體上執行任何有效的 SQL 陳述式，包括資料定義語言 (DDL)、資料控制語言 (DCL)、資料查詢語言 (DQL) 或資料操縱語言 (DML) 陳述式。

如要支援 execute_sql 工具，Cloud SQL 執行個體必須符合下列條件：

  • data_api_access 的值必須設為 ALLOW_DATA_API。
  • 如果是 MySQL 執行個體，資料庫旗標 cloudsql_iam_authentication 必須設為 on。如果是 PostgreSQL 執行個體，資料庫旗標 cloudsql.iam_authentication 必須設為 on。
  • 您必須使用 IAM 使用者帳戶或 IAM 服務帳戶 (CLOUD_IAM_USER 或 CLOUD_IAM_SERVICE_ACCOUNT)，才能呼叫 execute_sql 工具。這項工具會使用透過 IAM 資料庫驗證登入的資料庫使用者權限，執行 SQL 陳述式。

使用 create_instance 工具建立執行個體後，您可以使用 create_user 工具，為目前登入專案的使用者建立 IAM 使用者帳戶。

execute_sql 工具具有下列限制：

  • 如果 SQL 陳述式傳回的回應大於 10 MB，系統就會截斷回應。
  • execute_sql 工具的預設逾時時間為 30 秒。如果查詢執行時間超過 30 秒，工具會傳回 DEADLINE_EXCEEDED 錯誤。
  • execute_sql 工具不支援 SQL Server。

如果收到類似「執行個體未啟用 IAM 驗證」的錯誤訊息，可以使用 get_instance 工具檢查執行個體的 IAM 資料庫驗證旗標值。

如果收到「The instance doesn't allow using executeSql to access this instance」等錯誤訊息，可以使用 get_instance 工具檢查 data_api_access 設定。

收到驗證錯誤訊息時：

  1. 使用 list_users 工具，檢查目前登入的使用者帳戶是否為執行個體上的 IAM 使用者。
  2. 如果 IAM 使用者帳戶不存在，請使用 create_user 工具為登入的使用者建立 IAM 使用者帳戶。
  3. 如果目前登入的使用者沒有適當的資料庫使用者角色，可以使用 update_user 工具授予使用者資料庫角色。舉例來說，cloudsqlsuperuser 角色可為 IAM 使用者提供許多必要權限。

  4. 檢查目前登入的使用者是否已獲派專案的正確 IAM 權限。您可以使用 gcloud projects get-iam-policy [PROJECT_ID] 指令，檢查使用者是否已獲派專案的適當 IAM 角色或權限。

    • 使用者必須具備 cloudsql.instance.login 權限，才能進行自動 IAM 資料庫驗證。
    • 使用者必須具備 cloudsql.instances.executeSql 權限，才能使用 execute_sql 工具或 executeSql API 執行 SQL 陳述式。
    • 包含必要權限的常見 IAM 角色：Cloud SQL 執行個體使用者 (roles/cloudsql.instanceUser) 或 Cloud SQL 管理員 (roles/cloudsql.admin)

收到 ExecuteSqlResponse 時，請務必檢查回覆主體中的 message 和 status 欄位。HTTP 狀態碼成功不代表所有 SQL 陳述式都完全成功。message 和 status 欄位會指出 SQL 陳述式執行期間是否有任何部分錯誤或警告。
get_operation 取得長時間執行作業的狀態。長時間執行的作業可能需要幾分鐘才能完成。如果作業需要較長時間，請使用指令列工具暫停 30 秒，然後重新檢查作業狀態。
create_user

為 Cloud SQL 執行個體建立資料庫使用者。

  • 這項工具會傳回長時間執行的作業。使用 get_operation 工具輪詢狀態，直到作業完成為止。
  • 使用 create_user 工具時，請指定使用者類型：CLOUD_IAM_USER 或 CLOUD_IAM_SERVICE_ACCOUNT。
  • 除非您在要求中明確指定其他資料庫角色，否則系統預設會為新建立的使用者指派 cloudsqlsuperuser 角色。
  • 如果使用者是目前登入的 IAM 使用者，您可以使用 execute_sql 工具建立新使用者。execute_sql 工具會使用透過 IAM 資料庫驗證登入的資料庫使用者權限，執行 SQL 陳述式。

create_user 工具具有下列限制：

  • 您無法使用密碼建立內建使用者。
  • create_user 工具不支援為 SQL Server 建立使用者。

如要在 PostgreSQL 中建立 IAM 使用者，請按照下列步驟操作：

  • 資料庫使用者名稱必須是 IAM 使用者的電子郵件地址，且全部為小寫。舉例來說，如要為 PostgreSQL IAM 使用者 example-user@example.com 建立使用者，可以使用下列要求：
{
  "name": "example-user@example.com",
  "type": "CLOUD_IAM_USER",
  "instance":"test-instance",
  "project": "test-project"
}

為 IAM 使用者建立的資料庫使用者名稱為 example-user@example.com。

如要在 PostgreSQL 中建立 IAM 服務帳戶，請按照下列步驟操作：

  • 即使帳戶的完整電子郵件地址為 service-account-name@project-id.iam.gserviceaccount.com，建立資料庫使用者名稱時也不得加上 .gserviceaccount.com 後置字元。舉例來說，如要為 PostgreSQL 建立 IAM 服務帳戶，可以使用下列要求格式：
{
   "name": "test@test-project.iam",
   "type": "CLOUD_IAM_SERVICE_ACCOUNT",
   "instance": "test-instance",
   "project": "test-project"
}

IAM 服務帳戶的資料庫使用者名稱為 test@test-project.iam。

如要在 MySQL 中建立 IAM 使用者或 IAM 服務帳戶，請按照下列步驟操作：

  • Cloud SQL for MySQL 儲存使用者名稱時，會從使用者或服務帳戶的電子郵件地址截斷 @ 和網域名稱。舉例來說，example-user@example.com 會變為 example-user。
  • 因此，您無法將兩個使用者名稱相同但網域名稱不同的 IAM 使用者或服務帳戶，新增至同一個 Cloud SQL 執行個體。
  • 舉例來說，如要為 MySQL IAM 使用者 example-user@example.com 建立使用者，請使用下列要求：
{
   "name": "example-user@example.com",
   "type": "CLOUD_IAM_USER",
   "instance": "test-instance",
   "project": "test-project"
}

為 IAM 使用者建立的資料庫使用者名稱為 example-user。

  • 舉例來說，如要建立 MySQL IAM 服務帳戶 service-account-name@project-id.iam.gserviceaccount.com，請使用下列要求：
{
   "name": "service-account-name@project-id.iam.gserviceaccount.com",
   "type": "CLOUD_IAM_SERVICE_ACCOUNT",
   "instance": "test-instance",
   "project": "test-project"
}

IAM 服務帳戶的資料庫使用者名稱為 service-account-name。
update_user

更新 Cloud SQL 執行個體的資料庫使用者。update_user 的常見用途是授予使用者 cloudsqlsuperuser 角色，這可提供使用者許多必要權限。

這項工具僅支援更新使用者，以指派資料庫角色。

  • 這項工具會傳回長時間執行的作業。使用 get_operation 工具輪詢狀態，直到作業完成為止。
  • 呼叫 update_user 工具前，請務必先使用 list_users 工具檢查使用者的現有設定，例如使用者類型。
  • 以 MySQL 為例，如果 list_users 工具傳回 iamEmail 欄位的完整電子郵件地址 (例如 {name=test-account, iamEmail=test-account@project-id.iam.gserviceaccount.com})，請在 update_user 要求中，使用工具要求的 name 欄位中的 iamEmail 欄位完整電子郵件地址。例如：name=test-account@project-id.iam.gserviceaccount.com。

更新使用者角色的重要參數：

  • database_roles：要指派給使用者的資料庫角色清單。
  • revokeExistingRoles：布林值欄位 (預設值為 false)，可控管現有角色的處理方式。

角色更新的運作方式：

  1. 如果 revokeExistingRoles 為 true：

    • 系統會撤銷使用者目前擁有的角色，但不在提供的 database_roles 清單中。
    • 撤銷權限只適用於非系統角色。系統角色 (例如 cloudsqliamuser 等) 不會遭到撤銷。
    • 系統會授予使用者在 database_roles 清單中尚未擁有的角色。
    • 如果 database_roles 為空白，系統會撤銷所有現有的非系統角色。

  2. 如果 revokeExistingRoles 為 false (預設值)：

    • 系統會授予使用者在 database_roles 清單中尚未擁有的角色。
    • 系統會保留不在 database_roles 清單中的現有角色。
    • 如果 database_roles 為空值，則使用者的角色不會變更。

範例：

  • 現有角色：[roleA, roleB]

    • 要求：database_roles: [roleB, roleC], revokeExistingRoles: true
    • 結果：撤銷 roleA，授予 roleC。使用者角色會變成 [roleB, roleC]。
    • 要求：database_roles: [roleB, roleC], revokeExistingRoles: false
    • 結果：授予 roleC。使用者角色會變成 [roleA, roleB, roleC]。
    • 要求：database_roles: [], revokeExistingRoles: true
    • 結果：撤銷 roleA、撤銷 roleB。使用者角色會變成 []。
    • 要求：database_roles: [], revokeExistingRoles: false
    • 結果：沒有變更。使用者角色維持不變 [roleA, roleB]。
clone_instance

建立 Cloud SQL 執行個體，做為來源執行個體的副本。

  • 這項工具會傳回長時間執行的作業。使用 get_operation 工具輪詢狀態，直到作業完成為止。
  • 複製作業可能需要幾分鐘才能完成。使用指令列工具暫停 30 秒，然後重新檢查狀態。
update_instance

部分更新 Cloud SQL 執行個體的設定。

  • 這項工具會傳回長時間執行的作業。使用 get_operation 工具輪詢狀態，直到作業完成為止。
list_users 列出 Cloud SQL 執行個體的所有資料庫使用者。
import_data

將資料匯入 Cloud SQL 執行個體。

如果檔案開頭不是 gs://，系統會假設檔案儲存在本機。如果是本機檔案，您必須先將檔案上傳至 Cloud Storage，才能進行實際的 import_data 呼叫。如要將檔案上傳至 Cloud Storage，可以使用 gcloud 或 gsutil 指令。

將檔案上傳至 Cloud Storage 前，請考慮要使用現有值區，還是要在提供的專案中建立新值區。

將檔案上傳至 Cloud Storage 後，執行個體服務帳戶必須具備足夠的權限，才能從 Cloud Storage bucket 讀取上傳的檔案。

方法如下：

  1. 使用 get_instance 工具取得執行個體服務帳戶的電子郵件地址。從工具的輸出內容中，取得 serviceAccountEmailAddress 欄位的值。
  2. 在提供的 Cloud Storage bucket 中，將 storage.objectAdmin 角色授予執行個體服務帳戶。使用 gcloud storage buckets add-iam-policy-binding 等指令，或向 Cloud Storage API 發出要求。角色授予作業完成後，權限會傳播至 Cloud Storage 中的服務帳戶，這可能需要 2 到 7 分鐘，甚至更久。更新 IAM 政策後，如果發生權限錯誤，請稍候幾分鐘再試一次。

授予權限後，您就可以匯入資料。建議您將選用參數留空，並使用系統預設值。檔案類型通常可由副檔名判斷。舉例來說，如果是 SQL 檔案，請選取 .sql；如果是 CSV 檔案，請選取 .csv。

以下是 MySQL 的 SQL importContext 範例。

{
  "uri": "gs://sample-gcs-bucket/sample-file.sql",
  "kind": "sql#importContext",
  "fileType": "SQL"
}

由於資料庫名稱應位於 SQL 檔案中，因此 MySQL 沒有 database 參數。請只指定一個 URI。除了 importContext 以外，其他欄位都不是必填。

如果是 PostgreSQL，則必須填寫 database 欄位。以下是指定 database 欄位的 PostgreSQL importContext 範例。

{
  "uri": "gs://sample-gcs-bucket/sample-file.sql",
  "kind": "sql#importContext",
  "fileType": "SQL",
  "database": "sample-db"
}

import_data 工具會傳回長時間執行的作業。使用 get_operation 工具輪詢狀態，直到作業完成為止。

取得 MCP 工具規格

如要取得 MCP 伺服器中所有工具的 MCP 工具規格，請使用 tools/list 方法。以下範例說明如何使用 curl 列出 MCP 伺服器中目前可用的所有工具及其規格。

Curl 要求 
                      
curl --location 'https://sqladmin.googleapis.com/mcp' \
--header 'content-type: application/json' \
--header 'accept: application/json, text/event-stream' \
--data '{
    "method": "tools/list",
    "jsonrpc": "2.0",
    "id": 1
}'