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 请求者付款），您必须传递 --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. 异步操作：对于长时间运行的同步操作（例如，创建虚拟机或数据库），您应始终传递 --async 标志，以防止代理超时。
  8. 日志速率限制：使用 gcloud logging read 时，您必须始终添加 --limit 标志（例如，--limit=100），以防止凭据和连接超时。
  9. 自我更正：如果命令返回错误，请分析 stderr，更正语法或标志，然后在下一次迭代中重试。
  10. input_files：（可选）在运行命令之前要在环境中创建的文件列表。每个文件都必须具有“path”（相对于当前目录）和“contents”。“contents”必须是表示文件内容的纯文本。这对于从文件中读取的命令非常有用（例如 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 的 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

必需。相对于主目录的文件路径。不得包含父目录遍历 (..) 或 shell 扩展。
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

必需。相对于主目录的文件路径。不得包含父目录遍历 (..) 或 shell 扩展。
contents

string

必需。文件的内容。

工具注释

破坏性提示：✅ | 等幂性提示：❌ | 只读提示：❌ | 开放世界提示：❌