MCP Tools Reference: cloudcli.googleapis.com

工具：run_gcloud_command

在使用者 Google Cloud 專案中執行單一 gcloud CLI 指令。重要安全警告 (可能造成破壞)：這個工具可以建立、更新或刪除 GCP 資源 (例如 gcloud compute instances delete)。這項功能「不」限於唯讀指令。請務必謹慎使用。禁止執行的指令：代理程式不得執行下列 gcloud 指令 (包括 Alpha/Beta 變體)：app deploy、app instances ssh、auth、billing、components、config、docker、feedback、info、init、meta、survey。嚴格執行規則：

  1. 使用這項工具時，您「必須」提供「project」參數 (即 project="projects/PROJECT_ID")，這項參數用於 Cloud CLI Execution API 啟用檢查、帳單、配額等。這與 gcloud 指令中用於指定 gcloud 運作專案的 --project 標記不同。
  2. 旗標格式：所有長選項都必須使用「=」符號分隔旗標鍵和值。正確：--zone=us-central1-a 或 --project=my-project。錯誤：--zone us-central1-a 或 --project my-project。
  3. 帳單專案：您無法在執行環境中採用任何預先設定的專案或帳單設定。如果是專案範圍以外的指令 (例如資料夾或機構層級)，或是 Cloud Storage Requester Pays 等特定情境，則必須傳遞 --billing-project=PROJECT 旗標。如果是專案範圍的指令，您「可以」額外指定 --billing-project=PROJECT 來覆寫配額專案，這會對不支援資源專案覆寫的 GCP API 生效。
  4. 專案範圍：您「應該」一律為專案範圍指令傳遞 --project=PROJECT_ID 標記。請勿用於機構或資料夾層級的指令。如果未提供專案範圍指令的 --project 標記，資源專案預設會設為 --billing-project 標記中設定的專案。
  5. 如果在 gcloud 指令中指定 --billing-project 旗標，請確認值為專案 ID 或專案編號。值不得為特殊值 (即 LEGACY、CURRENT_PROJECT、CURRENT_PROJECT_WITH_FALLBACK)。
  6. 指令字串中必須至少指定 --project 或 --billing-project。
  7. 非同步作業：對於長時間執行的同步作業 (例如建立 VM 或資料庫)，您「一律」應傳遞 --async 旗標，避免代理程式逾時。
  8. 記錄速率限制：使用 gcloud logging read 時，請務必加入 --limit 旗標 (例如 --limit=100)，以免發生憑證和連線逾時問題。
  9. 自我修正：如果指令傳回錯誤，請分析 stderr、修正語法或標記，然後在下一次疊代中重試。
  10. input_files：(選用) 在執行指令前，要在環境中建立的檔案清單。每個檔案都必須有「路徑」(相對於目前目錄) 和「內容」。「內容」必須是代表檔案內容的純文字。這對於從檔案讀取的指令很有用 (例如 gcloud builds submit --config=cloudbuild.yaml --async --project=PROJECT_ID)。

gcloud 指令/模式範例：

  1. 讀取嚴重程度>=ERROR 的 GCE 執行個體記錄：gcloud logging read "severity>=ERROR AND resource.type='gce_instance'" --limit=10 --order=DESC --project=PROJECT_ID
    • 請注意篩選運算式使用引號。
  2. 列出所有 PSC 端點：gcloud compute forwarding-rules list --project=PROJECT_ID
  3. 說明 PSC 端點：gcloud compute forwarding-rules describe FORWARDING_RULE_NAME --region=REGION --project=PROJECT_ID
    • 請注意，--region 標記使用「=」。
  4. 列出所有叢集：gcloud container clusters list --project=PROJECT_ID
  5. 描述叢集：gcloud container clusters describe CLUSTER_NAME --region=REGION --project=PROJECT_ID
  6. 列出運算執行個體：gcloud compute instances list --project=PROJECT_ID
  7. 取得專案的 IAM 政策：gcloud projects get-iam-policy PROJECT_ID --project=PROJECT_ID

根據預設，回應字串會格式化為終端機輸出 (stdout 或 stderr)。使用 --format 標記變更格式。

下列範例示範如何使用 curl 叫用 run_gcloud_command MCP 工具。

Curl 要求 
                  
curl --location 'https://cloudcli.googleapis.com/mcp' \
--header 'content-type: application/json' \
--header 'accept: application/json, text/event-stream' \
--data '{
  "method": "tools/call",
  "params": {
    "name": "run_gcloud_command",
    "arguments": {
      // provide these details according to the tool's MCP specification
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

輸入內容的結構定義

RunGcloud 的要求訊息。

RunGcloudRequest

JSON 表示法 
{
  "project": string,
  "command": string,
  "inputFiles": [
    {
      object (File)
    }
  ]
}
欄位
project

string

這是必要旗標，專案：用於啟用 Cloud CLI Execution API 和消耗配額。

格式必須為 projects/ 或 projects/
command

string

這是必要旗標，以單一字串形式執行的完整 gcloud 指令列。範例：「gcloud compute instances create my-vm --zone=us-central1-a」

系統會指示 LLM 對長時間執行的作業使用 --async 旗標，避免逾時。
inputFiles[]

object (File)

選用。供 gcloud 指令執行的檔案。

檔案

JSON 表示法 
{
  "path": string,
  "contents": string
}
欄位
path

string

這是必要旗標，檔案路徑 (相對於主目錄)。不得包含父項目錄遍歷 (..) 或殼層擴充功能。
contents

string

這是必要旗標，檔案內容。

輸出內容的結構定義

RunGcloud 的回應訊息。

RunGcloudResponse

JSON 表示法 
{
  "response": {
    object (CliExecutionResponse)
  },
  "outputFiles": [
    {
      object (File)
    }
  ]
}
欄位
response

object (CliExecutionResponse)

CLI 工具執行作業的回應，包含獨立的 stdout、stderr 串流和結束代碼。
outputFiles[]

object (File)

gcloud 指令執行時產生的檔案。

CliExecutionResponse

JSON 表示法 
{
  "stdout": string,
  "stderr": string,
  "exitCode": string
}
欄位
stdout

string

CLI 工具執行作業的 stdout 串流。
stderr

string

CLI 工具執行作業的 stderr 串流。
exitCode

string (int64 format)

CLI 工具執行的結束代碼。

檔案

JSON 表示法 
{
  "path": string,
  "contents": string
}
欄位
path

string

這是必要旗標，檔案路徑 (相對於主目錄)。不得包含父項目錄遍歷 (..) 或殼層擴充功能。
contents

string

這是必要旗標，檔案內容。

工具註解

破壞性提示：✅ | 等冪提示：❌ | 唯讀提示：❌ | 開放世界提示：❌