MCP Tools Reference: cloudcli.googleapis.com

Tool: run_gcloud_command

Führt einen einzelnen gcloud CLI-Befehl im Google Cloud-Projekt des Nutzers aus.

WICHTIGER SICHERHEITSHINWEIS (POTENZIELL DESTRUKTIV): Mit diesem Tool können GCP-Ressourcen erstellt, aktualisiert oder gelöscht werden (z.B. mit `gcloud compute instances delete`). Es ist NICHT auf schreibgeschützte Befehle beschränkt. Seien Sie äußerst vorsichtig.

VERBOTENE BEFEHLE: Ein Agent darf die folgenden gcloud-Befehle (einschließlich ihrer Alpha-/Beta-Varianten) NICHT ausführen: app deploy, app instances ssh, auth, billing, components, config, docker, feedback, info, init, meta, survey.

STRENGE AUSFÜHRUNGSREGELN:

  1. Sie MÜSSEN den Parameter „project“ angeben (d. h. `project="projects/PROJECT_ID"`), wenn Sie dieses Tool verwenden. Er wird für die Überprüfung der Aktivierung der Cloud CLI Execution API, die Abrechnung, das Kontingent usw. verwendet. Dies ist NICHT dasselbe wie das Flag `--project` in gcloud-Befehlen, mit dem das Projekt angegeben wird, in dem gcloud ausgeführt wird.
  2. Flag-Formatierung: Sie MÜSSEN immer ein Gleichheitszeichen („=“) verwenden, um die Flag-Schlüssel von ihren Werten zu trennen. Korrekt: --zone=us-central1-a oder --project=my-project. Falsch: --zone us-central1-a oder --project my-project.
  3. Abrechnungsprojekt: In der Ausführungsumgebung können Sie keine vorkonfigurierten Projekt- oder Abrechnungseinstellungen annehmen. Für Befehle ohne Projektbereich (z.B. auf Ordner- oder Organisationsebene) oder für bestimmte Szenarien wie „Requester Pays“ in Cloud Storage MÜSSEN Sie das Flag --billing-project=PROJECT übergeben. Für Befehle mit Projektbereich können Sie zusätzlich --billing-project=PROJECT angeben, um das Kontingentprojekt zu überschreiben. Dies gilt für GCP APIs, die keine Überschreibung des Ressourcenprojekts unterstützen.
  4. Projektbereich: Sie SOLLTEN IMMER das Flag --project=PROJECT_ID für Befehle mit Projektbereich übergeben. Verwenden Sie es nicht für Befehle auf Organisations- oder Ordnerebene. Wenn Sie für einen Befehl mit Projektbereich kein --project flag angeben, wird das Ressourcenprojekt standardmäßig auf das Projekt festgelegt, das im Flag --billing-project festgelegt ist.
  5. Wenn Sie das Flag --billing-project im gcloud-Befehl angeben, muss der Wert eine Projekt-ID oder eine Projektnummer sein. Der Wert darf kein Sonderwert sein (z. B. LEGACY, CURRENT_PROJECT, CURRENT_PROJECT_WITH_FALLBACK).
  6. In der Befehlszeile muss mindestens eines der Flags --project oder --billing-project angegeben werden.
  7. Asynchrone Vorgänge: Bei lange laufenden synchronen Vorgängen (z.B. beim Erstellen einer VM oder einer Datenbank) SOLLTEN Sie IMMER das Flag --async übergeben, um Agent-Time-outs zu vermeiden.
  8. Log-Ratenbegrenzung: Wenn Sie gcloud logging read verwenden, MÜSSEN Sie IMMER ein --limit-Flag angeben (z.B. --limit=100), um Time-outs bei Anmeldedaten und Verbindungen zu vermeiden.
  9. Selbstkorrektur: Wenn ein Befehl einen Fehler zurückgibt, analysieren Sie die Standardfehlerausgabe, korrigieren Sie die Syntax oder die Flags und versuchen Sie es in der nächsten Iteration noch einmal.
  10. `input_files`: (Optional) Eine Liste von Dateien, die in der Umgebung erstellt werden sollen, bevor der Befehl ausgeführt wird. Jede Datei muss einen „Pfad“ (relativ zum aktuellen Verzeichnis) und einen „Inhalt“ haben. Der „Inhalt“ muss Klartext sein, der den Inhalt der Datei darstellt. Dies ist nützlich für Befehle, die aus Dateien lesen (z.B. gcloud builds submit --config=cloudbuild.yaml --async --project=PROJECT_ID).

Beispiel für gcloud-Befehle/Muster:

  1. GCE-Instanzlogs mit dem Schweregrad „ERROR“ oder höher lesen: gcloud logging read "severity>=ERROR AND resource.type='gce_instance'" --limit=10 --order=DESC --project=PROJECT_ID
    • Beachten Sie die Verwendung von Anführungszeichen für den Filterausdruck.
  2. Alle PSC-Endpunkte auflisten: gcloud compute forwarding-rules list --project=PROJECT_ID
  3. PSC-Endpunkt beschreiben: gcloud compute forwarding-rules describe FORWARDING_RULE_NAME --region=REGION --project=PROJECT_ID
    • Beachten Sie die Verwendung von „=“ für das Flag `--region`.
  4. Alle Cluster auflisten: gcloud container clusters list --project=PROJECT_ID
  5. Cluster beschreiben: gcloud container clusters describe CLUSTER_NAME --region=REGION --project=PROJECT_ID
  6. Compute-Instanzen auflisten: gcloud compute instances list --project=PROJECT_ID
  7. IAM-Richtlinie für ein Projekt abrufen: gcloud projects get-iam-policy PROJECT_ID --project=PROJECT_ID

Antwortstrings werden standardmäßig für die Terminalausgabe formatiert (Standardausgabe oder Standardfehlerausgabe). Verwenden Sie das Flag `--format`, um das Format zu ändern.

Das folgende Codebeispiel zeigt, wie Sie curl verwenden, um das MCP-Tool run_gcloud_command aufzurufen.

cURL-Anfrage 
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
}'

Eingabeschema

Anfragenachricht für RunGCloud.

RunGcloudRequest

JSON-Darstellung 
{
  "project": string,
  "command": string,
  "inputFiles": [
    {
      object (File)
    }
  ]
}
Felder
project

string

Erforderlich. Projekt für die API-Aktivierung und den Kontingentverbrauch für die Cloud CLI Execution API.

Das Format muss „projects/ “ oder „projects/“ sein.
command

string

Erforderlich. Die vollständige gcloud-Befehlszeile, die als einzelner String ausgeführt werden soll. Beispiel: „gcloud compute instances create my-vm --zone=us-central1-a“

LLMs werden angewiesen, das Flag --async für lange laufende Vorgänge zu verwenden, um Time-outs zu vermeiden.
inputFiles[]

object (File)

Optional. Dateien, die dem gcloud-Befehl für die Ausführung zur Verfügung gestellt werden sollen.

Datei

JSON-Darstellung 
{
  "path": string,
  "contents": string
}
Felder
path

string

Erforderlich. Dateipfad relativ zum Basisverzeichnis. Darf keine übergeordneten Verzeichnisse (..) oder Shell-Erweiterungen enthalten.
contents

string

Erforderlich. Inhalt der Datei.

Ausgabeschema

Antwortnachricht für RunGCloud.

RunGcloudResponse

JSON-Darstellung 
{
  "response": {
    object (CliExecutionResponse)
  },
  "outputFiles": [
    {
      object (File)
    }
  ]
}
Felder
response

object (CliExecutionResponse)

Die Antwort von der Ausführung des Befehlszeilentools, die unabhängige Standardausgabe-, Standardfehlerausgabe-Streams und einen Exit-Code enthält.
outputFiles[]

object (File)

Dateien, die vom gcloud-Befehl bei der Ausführung generiert wurden.

CliExecutionResponse

JSON-Darstellung 
{
  "stdout": string,
  "stderr": string,
  "exitCode": string
}
Felder
stdout

string

Der Standardausgabestream von der Ausführung des Befehlszeilentools.
stderr

string

Der Standardfehlerausgabestream von der Ausführung des Befehlszeilentools.
exitCode

string (int64 format)

Der Exit-Code der Ausführung des Befehlszeilentools.

Datei

JSON-Darstellung 
{
  "path": string,
  "contents": string
}
Felder
path

string

Erforderlich. Dateipfad relativ zum Basisverzeichnis. Darf keine übergeordneten Verzeichnisse (..) oder Shell-Erweiterungen enthalten.
contents

string

Erforderlich. Inhalt der Datei.

Toolanmerkungen

Destruktiver Hinweis: ✅ | Idempotenter Hinweis: ❌ | Schreibgeschützter Hinweis: ❌ | Open-World-Hinweis: ❌