MCP Tools Reference: cloudcli.googleapis.com

Ferramenta: run_gcloud_command

Executa um único comando da CLI gcloud no projeto na nuvem do Google Cloud do usuário.

AVISO DE SEGURANÇA CRÍTICO (POTENCIALMENTE DESTRUTIVO): essa ferramenta pode criar, atualizar ou excluir recursos do GCP (por exemplo, gcloud compute instances delete). Ela NÃO é restrita a comandos somente leitura. Use com extrema cautela.

COMANDOS PROIBIDOS: um agente NÃO PODE executar os seguintes comandos gcloud (incluindo as variantes alfa/beta): app deploy, app instances ssh, auth, billing, components, config, docker, feedback, info, init, meta, survey.

REGRAS DE EXECUÇÃO ESTRICTAS:

  1. Você PRECISA fornecer o parâmetro "project" (ou seja, project="projects/PROJECT_ID") ao usar essa ferramenta. Ele é usado para a verificação de ativação da API Cloud CLI Execution, faturamento, cota etc. Isso NÃO é o mesmo que a flag --project em comandos gcloud usados para especificar o projeto em que a gcloud opera.
  2. Formatação de flag: você PRECISA sempre usar um sinal de igual (=) para separar as chaves de flag dos valores de todas as opções longas. Correto: --zone=us-central1-a ou --project=my-project. Incorreto: --zone us-central1-a ou --project my-project.
  3. Projeto de faturamento: não é possível assumir nenhum projeto pré-configurado ou configurações de faturamento no ambiente de execução. Para comandos não relacionados ao projeto (por exemplo, no nível da pasta ou da organização) ou cenários específicos, como o Requester Pays do Cloud Storage, você PRECISA transmitir a flag --billing-project=PROJECT. Para comandos com escopo de projeto, você também pode especificar --billing-project=PROJECT para substituir o projeto de cota, que entrará em vigor para APIs do GCP que não oferecem suporte à substituição de projeto de recurso.
  4. Escopo do projeto: você SEMPRE PRECISA transmitir a flag --project=PROJECT_ID para comandos com escopo de projeto. Não a use para comandos no nível da organização ou da pasta. Se você não fornecer uma --project flag para um comando com escopo de projeto, o projeto de recurso será definido como o projeto definido na flag --billing-project.
  5. Se você especificar a flag --billing-project no comando gcloud, verifique se o valor é um ID do projeto ou número do projeto. O valor NÃO PODE ser um valor especial (ou seja, LEGACY, CURRENT_PROJECT, CURRENT_PROJECT_WITH_FALLBACK).
  6. Pelo menos um de --project ou --billing-project PRECISA ser especificado na string de comando.
  7. Operações assíncronas: para operações síncronas de longa duração (por exemplo, criar uma VM ou um banco de dados), você SEMPRE PRECISA transmitir a flag --async para evitar tempos limite do agente.
  8. Limitação de taxa de registro: ao usar gcloud logging read, você SEMPRE PRECISA incluir uma flag --limit (por exemplo, --limit=100) para evitar tempos limite de credenciais e conexões.
  9. Autocorreção: se um comando retornar um erro, analise o stderr, corrija a sintaxe ou as flags e tente novamente na próxima iteração.
  10. input_files: (opcional) uma lista de arquivos a serem criados no ambiente antes de executar o comando. Cada arquivo precisa ter um "caminho" (relativo ao diretório atual) e "conteúdo". O "conteúdo" precisa ser texto simples que representa o conteúdo do arquivo. Isso é útil para comandos que leem arquivos (por exemplo, gcloud builds submit --config=cloudbuild.yaml --async --project=PROJECT_ID).

Exemplo de comandos/padrões gcloud:

  1. Ler registros de instâncias do GCE com gravidade>=ERROR: gcloud logging read "severity>=ERROR AND resource.type='gce_instance'" --limit=10 --order=DESC --project=PROJECT_ID
    • Observe o uso de aspas para a expressão de filtro.
  2. Listar todos os endpoints do PSC: gcloud compute forwarding-rules list --project=PROJECT_ID
  3. Descrever um endpoint do PSC: gcloud compute forwarding-rules describe FORWARDING_RULE_NAME --region=REGION --project=PROJECT_ID
    • Observe o uso de "=" para a flag --region.
  4. Listar todos os clusters: gcloud container clusters list --project=PROJECT_ID
  5. Descrever um cluster: gcloud container clusters describe CLUSTER_NAME --region=REGION --project=PROJECT_ID
  6. Listar instâncias de computação: gcloud compute instances list --project=PROJECT_ID
  7. Receber a política do IAM de um projeto: gcloud projects get-iam-policy PROJECT_ID --project=PROJECT_ID

As strings de resposta são formatadas para saída de terminal por padrão (stdout ou stderr). Use a flag --format para mudar o formato.

O exemplo de código a seguir mostra como usar curl para chamar a ferramenta run_gcloud_command do MCP.

Solicitação 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

A mensagem de solicitação para RunGcloud.

RunGcloudRequest

Representação JSON 
{
  "project": string,
  "command": string,
  "inputFiles": [
    {
      object (File)
    }
  ]
}
Campos
project

string

Obrigatório. Projeto para ativação da API e consumo de cota da API Cloud CLI Execution.

O formato precisa ser projects/ ou projects/
command

string

Obrigatório. A linha de comando gcloud completa a ser executada como uma única string. Exemplo: "gcloud compute instances create my-vm --zone=us-central1-a"

Os LLMs são instruídos a usar a flag --async para operações de longa duração para evitar tempos limite.
inputFiles[]

object (File)

Opcional. Arquivos a serem disponibilizados para o comando gcloud para execução.

Arquivo

Representação JSON 
{
  "path": string,
  "contents": string
}
Campos
path

string

Obrigatório. Caminho do arquivo relativo ao diretório principal. Não pode conter a travessia do diretório pai (..) ou expansões de shell.
contents

string

Obrigatório. Conteúdo do arquivo.

Esquema de saída

A mensagem de resposta para RunGCloud.

RunGcloudResponse

Representação JSON 
{
  "response": {
    object (CliExecutionResponse)
  },
  "outputFiles": [
    {
      object (File)
    }
  ]
}
Campos
response

object (CliExecutionResponse)

A resposta da execução da ferramenta de CLI, contendo stdout, fluxo stderr independente e um código de saída.
outputFiles[]

object (File)

Arquivos gerados pelo comando gcloud da execução.

CliExecutionResponse

Representação JSON 
{
  "stdout": string,
  "stderr": string,
  "exitCode": string
}
Campos
stdout

string

O fluxo stdout da execução da ferramenta de CLI.
stderr

string

O fluxo stderr da execução da ferramenta de CLI.
exitCode

string (int64 format)

O código de saída da execução da ferramenta de CLI.

Arquivo

Representação JSON 
{
  "path": string,
  "contents": string
}
Campos
path

string

Obrigatório. Caminho do arquivo relativo ao diretório principal. Não pode conter a travessia do diretório pai (..) ou expansões de shell.
contents

string

Obrigatório. Conteúdo do arquivo.

Anotações da ferramenta

Dica destrutiva: ✅ | Dica idempotente: ❌ | Dica somente leitura: ❌ | Dica de mundo aberto: ❌