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. Ten mucho cuidado. COMANDOS PROHIBIDOS: Un agente NO DEBE ejecutar los siguientes comandos de gcloud (incluidas sus variantes alfa o beta): app deploy, app instances ssh, auth, billing, components, config, docker, feedback, info, init, meta, 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). Este NO es el 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 el signo "=" para separar las claves de las marcas de sus valores en 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 suponer que hay algún proyecto o configuración de facturación preconfigurados en el entorno de ejecución. Para los comandos que no se limitan a un proyecto (p.ej., a nivel de la carpeta o la organización) o situaciones específicas, como Cloud Storage Requester Pays, DEBES pasar la marca --billing-project=PROJECT. En el caso de los comandos con alcance para el proyecto, TAMBIÉN PUEDES especificar --billing-project=PROJECT para anular el proyecto de cuota, lo que tendrá efecto en las APIs de GCP que no admitan la anulación del proyecto de recursos.
  4. Alcance del proyecto: SIEMPRE DEBES pasar la marca --project=PROJECT_ID para los comandos con permiso del proyecto. No lo uses para comandos a nivel de la organización o la carpeta. Si no proporcionas una marca --project para un comando con alcance en el proyecto, el proyecto del recurso 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 que se agote el tiempo de espera del agente.
  8. Limitación de la velocidad de registro: Cuando uses gcloud logging read, SIEMPRE debes incluir una marca --limit (p.ej., --limit=100) para evitar que se agote el tiempo de espera de las credenciales y las conexiones.
  9. Autocorrección: Si un comando devuelve 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 un "contenido". El campo "contents" debe ser texto sin formato 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
    • Observa 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
    • Observa 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

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

En el siguiente ejemplo, se muestra cómo usar curl para invocar la herramienta de 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

Es el mensaje de solicitud para RunGcloud.

RunGcloudRequest

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

string

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

El formato debe ser projects/ o projects/
command

string

Obligatorio. 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 y, así, evitar los tiempos de espera agotados.
inputFiles[]

object (File)

Es opcional. Son los archivos que estarán disponibles para el comando de gcloud durante su ejecución.

Archivo

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

string

Obligatorio. Es la ruta de acceso al archivo relativa al directorio principal. No debe contener saltos de directorio principal (..) ni expansiones de shell.
contents

string

Obligatorio. Contenido del archivo.

Esquema de salida

Es el mensaje de respuesta de RunGcloud.

RunGcloudResponse

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

object (CliExecutionResponse)

Es 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)

Son los archivos que genera el comando de gcloud a partir de su ejecución.

CliExecutionResponse

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

string

Es el flujo stdout de la ejecución de la herramienta de la CLI.
stderr

string

Es el flujo stderr de la ejecución de la herramienta de CLI.
exitCode

string (int64 format)

Es 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. Es la ruta de acceso al archivo relativa al directorio principal. No debe contener saltos de directorio principal (..) ni expansiones de shell.
contents

string

Obligatorio. Contenido del archivo.

Anotaciones de herramientas

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