MCP Tools Reference: cloudcli.googleapis.com

Herramienta: run_gcloud_command

Ejecuta un solo comando de gcloud CLI dentro del proyecto de Google Cloud del usuario.

ADVERTENCIA DE SEGURIDAD CRÍTICA (POTENCIALMENTE DESTRUCTIVA): Esta herramienta puede crear, actualizar o borrar recursos de GCP (p.ej., gcloud compute instances delete). NO se limita a los comandos de solo lectura. Úsala con extrema precaución.

COMANDOS PROHIBIDOS: Un agente NO DEBE ejecutar los siguientes comandos de gcloud (incluidas sus variantes alfa/beta): app deploy, app instances ssh, auth, billing, components, config, docker, feedback, info, init, meta y survey.

REGLAS DE EJECUCIÓN ESTRICTAS:

  1. Debes proporcionar el parámetro "project" (es decir, project="projects/PROJECT_ID") cuando uses esta herramienta (se usa para la verificación de habilitación de la API de Cloud CLI Execution, la facturación, la cuota, etcétera). NO es lo mismo que la marca --project en los comandos de gcloud que se usan para especificar el proyecto en el que opera gcloud.
  2. Formato de marcas: SIEMPRE debes usar un signo "=" para separar las claves de las marcas de sus valores para todas las opciones largas. Correcto: --zone=us-central1-a o --project=my-project. Incorrecto: --zone us-central1-a o --project my-project.
  3. Proyecto de facturación: No puedes asumir ninguna configuración de proyecto o facturación preconfigurada en el entorno de ejecución. Para los comandos que no están dentro del alcance del proyecto (p.ej., a nivel de la organización o la carpeta) o situaciones específicas como Cloud Storage Requester Pays, DEBES pasar la marca --billing-project=PROJECT. Para los comandos dentro del alcance del proyecto, TAMBIÉN puedes especificar --billing-project=PROJECT para anular el proyecto de cuota, que entrará en vigencia para las APIs de GCP que no admiten la anulación de resource-project.
  4. Alcance del proyecto: SIEMPRE debes pasar la marca --project=PROJECT_ID para los comandos dentro del alcance del proyecto. No la uses para comandos a nivel de la organización o la carpeta. Si no proporcionas una --project flag para un comando dentro del alcance del proyecto, el proyecto de recursos se establecerá de forma predeterminada en el proyecto establecido en la marca --billing-project.
  5. Si especificas la marca --billing-project en el comando de gcloud, asegúrate de que el valor sea un ID del proyecto o un número de proyecto. El valor NO DEBE ser un valor especial (es decir, LEGACY, CURRENT_PROJECT, CURRENT_PROJECT_WITH_FALLBACK).
  6. Se DEBE especificar al menos uno de --project o --billing-project en la cadena de comandos.
  7. Operaciones asíncronas: Para las operaciones síncronas de larga duración (p.ej., crear una VM o una base de datos), SIEMPRE debes pasar la marca --async para evitar los tiempos de espera del agente.
  8. Limitación de la tasa de registros: Cuando uses gcloud logging read, SIEMPRE debes incluir una marca --limit (p.ej., --limit=100) para evitar los tiempos de espera de las credenciales y la conexión.
  9. Autocorrección: Si un comando muestra un error, analiza stderr, corrige la sintaxis o las marcas y vuelve a intentarlo en la siguiente iteración.
  10. input_files: (Opcional) Es una lista de archivos que se crearán en el entorno antes de ejecutar el comando. Cada archivo debe tener una "ruta de acceso" (relativa al directorio actual) y "contenido". El "contenido" debe ser texto simple que represente el contenido del archivo. Esto es útil para los comandos que leen archivos (p.ej., gcloud builds submit --config=cloudbuild.yaml --async --project=PROJECT_ID).

Ejemplos de comandos o patrones de gcloud:

  1. Lee los registros de instancias de GCE con gravedad>=ERROR: gcloud logging read "severity>=ERROR AND resource.type='gce_instance'" --limit=10 --order=DESC --project=PROJECT_ID
    • Ten en cuenta el uso de comillas para la expresión de filtro.
  2. Enumera todos los extremos de PSC: gcloud compute forwarding-rules list --project=PROJECT_ID
  3. Describe un extremo de PSC: gcloud compute forwarding-rules describe FORWARDING_RULE_NAME --region=REGION --project=PROJECT_ID
    • Ten en cuenta el uso de "=" para la marca --region.
  4. Enumera todos los clústeres: gcloud container clusters list --project=PROJECT_ID
  5. Describe un clúster: gcloud container clusters describe CLUSTER_NAME --region=REGION --project=PROJECT_ID
  6. Enumera las instancias de procesamiento: gcloud compute instances list --project=PROJECT_ID
  7. Obtén la política de IAM para un proyecto: gcloud projects get-iam-policy PROJECT_ID --project=PROJECT_ID

Las cadenas de respuesta se formatean para la salida de la terminal de forma predeterminada (stdout o stderr). Usa la marca --format para cambiar el formato.

En la siguiente muestra de código, se muestra cómo usar curl para llamar a la herramienta MCP run_gcloud_command.

Solicitud de 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
}'

Esquema de entrada

Mensaje de solicitud para RunGcloud.

RunGcloudRequest

Representación JSON 
{
  "project": string,
  "command": string,
  "inputFiles": [
    {
      object (File)
    }
  ]
}
Campos
project

string

Obligatorio. Proyecto para la habilitación de la API y el consumo de cuotas para la API de Cloud CLI Execution.

El formato debe ser projects/ o projects/
command

string

Obligatorio. La línea de comandos completa de gcloud para ejecutar como una sola cadena. Ejemplo: "gcloud compute instances create my-vm --zone=us-central1-a"

Se les indica a los LLM que usen la marca --async para las operaciones de larga duración para evitar los tiempos de espera.
inputFiles[]

object (File)

Es opcional. Archivos que se pondrán a disposición del comando de gcloud para su ejecución.

Archivo

Representación JSON 
{
  "path": string,
  "contents": string
}
Campos
path

string

Obligatorio. Ruta de acceso al archivo relativa al directorio principal. No debe contener el recorrido del directorio superior (..) ni las expansiones de shell.
contents

string

Obligatorio. Contenido del archivo.

Esquema de salida

Mensaje de respuesta para RunGcloud.

RunGcloudResponse

Representación JSON 
{
  "response": {
    object (CliExecutionResponse)
  },
  "outputFiles": [
    {
      object (File)
    }
  ]
}
Campos
response

object (CliExecutionResponse)

La respuesta de la ejecución de la herramienta de CLI, que contiene stdout, stderr y un código de salida independientes.
outputFiles[]

object (File)

Archivos generados por el comando de gcloud a partir de su ejecución.

CliExecutionResponse

Representación JSON 
{
  "stdout": string,
  "stderr": string,
  "exitCode": string
}
Campos
stdout

string

El flujo stdout de la ejecución de la herramienta de CLI.
stderr

string

El flujo stderr de la ejecución de la herramienta de CLI.
exitCode

string (int64 format)

El código de salida de la ejecución de la herramienta de CLI.

Archivo

Representación JSON 
{
  "path": string,
  "contents": string
}
Campos
path

string

Obligatorio. Ruta de acceso al archivo relativa al directorio principal. No debe contener el recorrido del directorio superior (..) ni las expansiones de shell.
contents

string

Obligatorio. Contenido del archivo.

Anotaciones de herramientas

Sugerencia destructiva: ✅ | Sugerencia idempotente: ❌ | Sugerencia de solo lectura: ❌ | Sugerencia de mundo abierto: ❌