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 使用者帳戶。
  • 重要事項：如果建立 Private Service Connect 或私人服務連線執行個體，請將 ipv4_enabled 設為「false」。

  • 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",
  "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。
  • 對於內建使用者，必須設定 password_secret_version。
  • 否則，如果是 MySQL 執行個體，IAM 使用者的資料庫旗標 cloudsql_iam_authentication 必須設為 on。如果是 PostgreSQL 執行個體，資料庫旗標 cloudsql.iam_authentication 必須設為 on。
  • 使用 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 陳述式執行期間是否有任何部分錯誤或警告。
execute_sql_readonly

在 Cloud SQL 執行個體上執行任何有效的唯讀 SQL 陳述式。

如要支援 execute_sql_readonly 工具，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_readonly 工具。這項工具會使用透過 IAM 資料庫驗證登入的資料庫使用者權限，執行 SQL 陳述式。

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

execute_sql_readonly 工具具有下列限制：

  • 如果 SQL 陳述式傳回的回應大於 10 MB，系統就會截斷回應。
  • 這項工具的預設逾時時間為 30 秒。如果查詢執行時間超過 30 秒，工具會傳回 DEADLINE_EXCEEDED 錯誤。
  • 這項工具不支援 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_readonly 工具或 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 或 BUILT_IN。
  • 除非您在要求中明確指定其他資料庫角色，否則系統預設會為新建立的使用者指派 cloudsqlsuperuser 角色。
  • 如果使用者是目前登入的 IAM 使用者，您可以使用 execute_sql 工具建立新使用者。execute_sql 工具會使用透過 IAM 資料庫驗證登入的資料庫使用者權限，執行 SQL 陳述式。

create_user 工具具有下列限制：

  • 如要建立內建使用者並設定密碼，請使用 password_secret_version 欄位，透過 Google Cloud Secret Manager 提供密碼。password_secret_version 的值應為密鑰版本的資源名稱，例如 projects/12345/locations/us-central1/secrets/my-password-secret/versions/1 或 projects/12345/locations/us-central1/secrets/my-password-secret/versions/latest。呼叫者必須擁有 Secret 版本的 secretmanager.secretVersions.access 權限。
  • 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 服務帳戶，請按照下列步驟操作：

  • MySQL 適用的 Cloud SQL 儲存使用者名稱時，會截斷使用者或服務帳戶電子郵件地址中的 @ 和網域名稱。舉例來說，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 執行個體的所有資料庫使用者。
create_backup 在 Cloud SQL 執行個體上建立備份。請務必在要求中填入專案和執行個體欄位。您也可以選擇性提供備份位置 (區域) 和說明，但必須填寫對應的要求欄位。
restore_backup

將備份還原至 Cloud SQL 執行個體。

要求中必須提供並填入 target_instance 和 target_project。

備用 ID 的提供方式如下：

  1. backup_run_id (整數)。
  2. 備份 URI，格式為 projects/{project-id}/backups/{backup-uid}。
  3. 備份 URI，格式為 projects/{project-id}/locations/{location}/backupVaults/{backupvault}/dataSources/{datasource}/backups/{backup-uid}。

使用 ID 在要求中填入 backup_id 欄位。

要求中必須填入 source_project。如果 ID 是 backup_run_id，系統會提供 source_project。如果 ID 是備份 URI，可能需要從 URI 擷取 source_project。請勿將擷取的 source_project 與 target_project 混淆，target_project 會以其他方式提供。

此外，如果 ID 是 backup_run_id，則必須在要求中提供並填入 source_instance。

請勿在還原前嘗試建立執行個體，還原程序本身會在需要時建立執行個體。

執行還原作業前，請先向使用者確認參數。
import_data

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

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

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

將檔案上傳至 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 工具輪詢狀態，直到作業完成為止。
postgres_upgrade_precheck

檢查 PostgreSQL 適用的 Cloud SQL 執行個體是否已準備好升級至指定目標主要版本。

要求中「必須」提供 target_database_version (例如 POSTGRES_15)。

這項工具可協助您在嘗試實際升級前找出潛在問題，降低失敗或停機的風險。

這項工具僅支援 PostgreSQL 主要執行個體，無法在唯讀副本上執行。

預檢通常會評估：

  • 資料庫結構定義與目標版本的相容性。
  • Cloud SQL 限制和不支援的功能。
  • 執行個體資源限制 (例如關係數量)。
  • 目前資料庫設定和擴充功能的相容性。
  • 執行個體的整體健康狀態和準備程度。

這項工具會傳回長時間執行的作業。使用 get_operation 工具和這項呼叫傳回的作業名稱，輪詢作業狀態。

重要事項：作業狀態為 DONE 後，詳細的預檢結果會顯示在 Operation 資源中。您需要檢查 get_operation 的回應。調查結果位於 pre_check_major_version_upgrade_context.pre_check_response 欄位。

調查結果會以結構化方式呈現，指出：

  • 資訊：一般資訊。
  • 警告：潛在問題不會阻礙升級，但建議您查看。
  • 錯誤：重大問題，必須先解決才能嘗試升級。

每項發現項目都應包含訊息和任何必要動作。請務必先解決所有回報的問題，再進行主要版本升級。如果 pre_check_response 為空白或遺失，表示預檢期間未發現任何問題。

執行這項前置檢查不會影響執行個體的可用性。

取得 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
}'