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 "=" 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 nenhuma configuração de projeto ou faturamento pré-configurada no ambiente de execução. Para comandos não relacionados ao projeto (por exemplo, nível de pasta ou organização) ou cenários específicos, como o Cloud Storage Requester Pays, você PRECISA transmitir a flag --billing-project=PROJECT. Para comandos com escopo de projeto, você 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 use para comandos de organização ou pasta. Se você não fornecer uma flag --project para um comando com escopo de projeto, o projeto de recurso será definido como o projeto definido na flag --billing-project.
  5. Ao especificar a flag --billing-project no comando gcloud, verifique se o valor é um ID do projeto ou um 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 da 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ão.
  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 a seguir demonstra como usar curl para invocar 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

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 travessia de diretório pai (..) ou expansões de shell.
contents

string

Obrigatório. Conteúdo do arquivo.

Esquema de saída

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 na 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 travessia de 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: ❌