MCP Reference: cloudcli.googleapis.com

Google Cloud CLI MCP 伺服器提供相關工具，可在遠端沙箱環境中執行 Google Cloud CLI 指令。

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

伺服器設定

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

伺服器端點

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

Cloud CLI Execution API MCP 伺服器具有下列全域 MCP 端點：

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

MCP 工具

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

工具

cloudcli.googleapis.com MCP 伺服器提供下列工具：

MCP 工具
run_gcloud_command

在使用者 Google Cloud 專案中執行單一 gcloud CLI 指令。

重大安全警告 (可能造成破壞)：這個工具可以建立、更新或刪除 Google Cloud 資源 (例如 gcloud compute instances delete)。這項功能「不」限於唯讀指令。請務必極度謹慎。

禁止執行的指令：代理程式不得執行下列 gcloud 指令 (包括 alpha/beta 變體)：app deploy、app instances ssh、auth、billing、components、config、docker、feedback、info、init、meta、survey。

嚴格執行規則：

  1. 使用這項工具時，您「必須」提供「專案」參數 (即 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 來覆寫配額專案，這會對不支援資源專案覆寫的 Google Cloud API 生效。
  4. 專案範圍：您「應該」一律為專案範圍的指令傳遞 --project=PROJECT_ID 旗標。請勿用於機構或資料夾層級的指令。如果未提供專案範圍指令的 --project flag，資源專案預設會設為 --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 的 Compute Engine 執行個體記錄：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 旗標變更格式。
run_bq_command

執行單一 BigQuery CLI (bq) 指令。您可以使用這項工具在使用者專案中執行任何 bq 指令，包括建立、更新或刪除 Google Cloud 資源的指令 (即突變)。

重大安全警告 (可能造成破壞)：這項工具可以建立、更新或刪除 BigQuery 資源 (例如 bq rm、bq cancel、bq query)，不限於唯讀指令。請務必極度謹慎。

禁止使用的指令：代理程式不得執行下列 bq 指令：bq init、bq pyshell、bq shell。

嚴格執行規則：

  1. 指令字串中必須至少指定一個 --project_id 或 --quota_project_id。
  2. 專案 ID 與配額專案：--project_id 旗標會指定指令執行的資源專案 (與 gcloud 的 --project 旗標相同)。--quota_project_id 標記會指定下游 BigQuery API 呼叫的帳單/配額費用所計入的專案 (與 gcloud 的 --billing-project 標記相同)。如果指令中指定 --project_id，系統會將其做為帳單/配額專案。如未指定 --project_id 或另外指定 --quota_project_id，則計費/配額專案會是 --quota_project_id 旗標中設定的專案。
  3. 旗標格式：對於所有長選項，您「必須」一律使用「=」符號分隔旗標鍵和值。正確做法：'--project_id=my-project' 或 '--location=us'。錯誤：'--project_id my-project' 或 '--location us'。標記和值之間不得有空格。
  4. 沒有設定預設值：bq 指令會以無狀態方式執行，不會載入 .bigqueryrc 等本機設定檔。因此，對於所有區域作業 (例如建立資料集或查詢區域資料集)，您「必須」明確指定 --location 旗標 (例如 --location=us 或 --location=EU)。
  5. 非同步作業：部分指令會啟動同步長時間執行的作業 (例如執行查詢工作)。您「應該」一律為這些指令傳遞 --nosync 標記，以免代理逾時。
  6. 指令限制：您「不得」使用下列 bq 指令：bq init、bq pyshell、bq shell。系統「不」支援指令管道或鏈結。
  7. 自我修正：如果指令傳回錯誤，請分析 stderr、修正語法或標記，然後在下一次疊代中重試。

變更 bq 指令的範例包括：bq mk、bq rm、bq update、bq insert、bq query (不含 --dry_run) 等。用法：RunBq(command="bq query --project_id=PROJECT_ID 'SELECT 1'", project="projects/PROJECT_ID", input_files=[{"path": "PATH", "contents": "CONTENTS"}])。您必須在「command」參數中，以單一字串的形式提供完整的 bq 指令。您「必須」提供「project」參數 (格式：projects/PROJECT_ID) 做為 API 執行專案，以進行帳單、API 啟用和配額消耗檢查。

bq 指令/模式範例：

  1. 執行查詢：bq query --use_legacy_sql=false --project_id=PROJECT_ID 'SELECT * FROMproject.dataset.tableLIMIT 10'
  2. 建立資料集：bq mk --dataset --location=us --project_id=PROJECT_ID myDataset
  3. 建立表格：bq mk --table --project_id=PROJECT_ID myDataset.myTable name:string,value:integer
  4. 移除資料集：bq rm -f --dataset --project_id=PROJECT_ID myDataset
  5. 移除表格：bq rm -f -t --project_id=PROJECT_ID myDataset.myTable
  6. 更新表格說明：bq update --description="New description" --project_id=PROJECT_ID myDataset.myTable
  7. 列出專案中的資料集：bq ls --datasets=true --project_id=PROJECT_ID

取得 MCP 工具規格

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

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