MCP Tools Reference: cloudcli.googleapis.com

Tool: run_gcloud_command

Führt einen einzelnen gcloud CLI-Befehl im Google Cloud-Projekt des Nutzers aus. KRITISCHE SICHERHEITSWARNUNG (POTENZIELL DESTRUKTIV): Mit diesem Tool können GCP-Ressourcen erstellt, aktualisiert oder gelöscht werden (z.B. „gcloud compute instances delete“). Sie ist NICHT auf schreibgeschützte Befehle beschränkt. Sei ä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“ (z. B. project=„projects/PROJECT_ID“) verwenden, wenn Sie dieses Tool verwenden. Er wird für die Aktivierungsprüfung 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 Flag-Schlüssel von ihren Werten zu trennen. Das gilt für alle langen Optionen. Richtig: --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 nicht von vorkonfigurierten Projekt- oder Abrechnungseinstellungen ausgehen. Für Befehle, die nicht auf Projektebene ausgeführt werden (z.B. auf Ordner- oder Organisationsebene) oder für bestimmte Szenarien wie Cloud Storage Requester Pays MÜSSEN Sie das Flag --billing-project=PROJECT übergeben. Bei projektbezogenen Befehlen 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. Projektumfang: Sie SOLLTEN das Flag --project=PROJECT_ID IMMER für Befehle mit Projektumfang übergeben. Verwenden Sie sie nicht für Befehle auf Organisations- oder Ordnerebene. Wenn Sie für einen projektbezogenen Befehl kein --project-Flag angeben, wird für das Ressourcenprojekt standardmäßig das Projekt verwendet, das im --billing-project-Flag 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. Im Befehlsstring muss mindestens --project oder --billing-project angegeben werden.
  7. Asynchrone Vorgänge: Bei lang andauernden synchronen Vorgängen (z.B. beim Erstellen einer VM oder einer Datenbank) SOLLTEN Sie IMMER das Flag --async übergeben, um Agent-Timeouts zu vermeiden.
  8. Ratenbegrenzung für Logs: Wenn Sie gcloud logging read verwenden, MÜSSEN Sie IMMER das Flag --limit (z.B. --limit=100) angeben, um Zeitüberschreitungen bei Anmeldedaten und Verbindungen zu vermeiden.
  9. Selbstkorrektur: Wenn ein Befehl einen Fehler zurückgibt, analysieren Sie „stderr“, korrigieren Sie die Syntax oder Flags und versuchen Sie es in der nächsten Iteration noch einmal.
  10. input_files: (Optional) Eine Liste der 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 „contents“-Wert muss Nur-Text sein, der den Inhalt der Datei darstellt. Dies ist nützlich für Befehle, die Dateien lesen (z.B. gcloud builds submit --config=cloudbuild.yaml --async --project=PROJECT_ID).

Beispiele für gcloud-Befehle/Muster:

  1. GCE-Instanzlogs mit dem Schweregrad>=ERROR 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. Einen 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 (stdout oder stderr) formatiert. Verwenden Sie das Flag „--format“, um das Format zu ändern.

Im folgenden Beispiel wird gezeigt, wie Sie mit curl das MCP-Tool run_gcloud_command aufrufen.

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 Vorgänge mit langer Ausführungszeit zu verwenden, um Zeitüberschreitungen 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 Pfadnavigation zum übergeordneten Verzeichnis (..) 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 aus der Ausführung des CLI-Tools, die einen unabhängigen stdout- und stderr-Stream sowie einen Exit-Code enthält.
outputFiles[]

object (File)

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

CliExecutionResponse

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

string

Der stdout-Stream aus der Ausführung des CLI-Tools.
stderr

string

Der stderr-Stream aus der Ausführung des CLI-Tools.
exitCode

string (int64 format)

Der Exitcode der Ausführung des CLI-Tools.

Datei

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

string

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

string

Erforderlich. Inhalt der Datei.

Tool-Annotationen

Destruktiver Hinweis: ✅ | Idempotenter Hinweis: ❌ | Hinweis „Nur lesen“: ❌ | Hinweis „Offene Welt“: ❌