MCP Reference: cloudcli.googleapis.com

Der Google Cloud CLI MCP-Server bietet Tools zum Ausführen von Google Cloud CLI-Befehlen in einer Remote-Sandbox-Umgebung.

Ein Model Context Protocol (MCP)-Server fungiert als Proxy zwischen einem externen Dienst, der einem Large Language Model (LLM) oder einer KI-Anwendung Kontext, Daten oder Funktionen bereitstellt. MCP-Server verbinden KI-Anwendungen mit externen Systemen wie Datenbanken und Webdiensten und übersetzen deren Antworten in ein Format, das die KI-Anwendung versteht.

Server einrichten

Sie müssen MCP-Server aktivieren und die Authentifizierung einrichten, bevor Sie sie verwenden können. Weitere Informationen zur Verwendung von Remote-MCP-Servern von Google und Google Cloud finden Sie unter Google Cloud-MCP-Server – Übersicht.

Serverendpunkte

Ein MCP-Dienstendpunkt ist die Netzwerkadresse und Kommunikationsschnittstelle (in der Regel eine URL) des MCP-Servers, über die eine KI-Anwendung (der Host für den MCP-Client) eine sichere, standardisierte Verbindung herstellt. Es ist der Ansprechpartner für das LLM, um Kontext anzufordern, ein Tool aufzurufen oder auf eine Ressource zuzugreifen. Google MCP-Endpunkte können global oder regional sein.

Der MCP-Server der Cloud CLI Execution API hat den folgenden globalen MCP-Endpunkt:

  • https://cloudcli.googleapis.com/mcp

MCP-Tools

Ein MCP-Tool ist eine Funktion oder ausführbare Funktion, die ein MCP-Server für ein LLM oder eine KI-Anwendung bereitstellt, um eine Aktion in der realen Welt auszuführen.

Tools

Der cloudcli.googleapis.com-MCP-Server hat die folgenden Tools:

MCP-Tools
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 Google Cloud-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“ angeben (z. B. project=„projects/PROJECT_ID“), 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 Befehlen mit Projektbereich können Sie optional zusätzlich --billing-project=PROJECT angeben, um das Kontingentprojekt zu überschreiben. Dies gilt für Google Cloud APIs, die keine Überschreibung des Ressourcenprojekts unterstützen.
  4. Projektumfang: Sie SOLLTEN IMMER das Flag --project=PROJECT_ID für Befehle mit Projektumfang übergeben. Verwenden Sie sie nicht für Befehle auf Organisations- oder Ordnerebene. Wenn Sie für einen Befehl mit Projektbereich 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 zeitaufwendigen synchronen Vorgängen (z.B. 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) einfügen, 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 „path“ (relativ zum aktuellen Verzeichnis) und „contents“ haben. Der „Inhalt“ muss Nur-Text 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).

Beispiele für gcloud-Befehle/Muster:

  1. Compute Engine-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. 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.
run_bq_command

Führt einen einzelnen BigQuery CLI-Befehl (bq) aus. Mit diesem Tool können Sie beliebige bq-Befehle im Projekt des Nutzers ausführen, einschließlich Befehle zum Erstellen, Aktualisieren oder Löschen von Google Cloud-Ressourcen (d.h. Mutationen).

KRITISCHE SICHERHEITSWARNUNG (POTENZIELL DESTRUKTIV): Mit diesem Tool können BigQuery-Ressourcen (z.B. bq rm, bq cancel, bq query) erstellt, aktualisiert oder gelöscht werden. Es ist NICHT auf schreibgeschützte Befehle beschränkt. Sei äußerst vorsichtig.

VERBOTENE BEFEHLE: Ein Agent darf die folgenden bq-Befehle NICHT ausführen: bq init, bq pyshell, bq shell.

STRENGE AUSFÜHRUNGSREGELN:

  1. Im Befehlsstring muss mindestens --project_id oder --quota_project_id angegeben werden.
  2. Projekt-ID im Vergleich zu Kontingentprojekt: Mit dem Flag „--project_id“ wird das Ressourcenprojekt angegeben, für das der Befehl ausgeführt wird. Es entspricht dem Flag „--project“ von gcloud. Mit dem Flag „--quota_project_id“ wird das Projekt angegeben, dem die Abrechnung/das Kontingent des Downstream-BigQuery API-Aufrufs in Rechnung gestellt wird (entspricht dem --billing-project-Flag von gcloud). Wenn --project_id im Befehl angegeben ist, wird es als Abrechnungs-/Kontingentprojekt verwendet. Wenn --project_id nicht angegeben ist ODER --quota_project_id zusätzlich angegeben ist, ist das Abrechnungs-/Kontingentprojekt das Projekt, das im Flag --quota_project_id festgelegt ist.
  3. 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: '--project_id=my-project' oder '--location=us'. Falsch: '--project_id my-project' oder '--location us'. Verwenden Sie keine Leerzeichen zwischen Flags und ihren Werten.
  4. Keine Standardkonfigurationen: Der bq-Befehl wird zustandslos ausgeführt. Es werden keine lokalen Konfigurationsdateien wie .bigqueryrc geladen. Daher MÜSSEN Sie für alle regionalen Vorgänge (z.B. zum Erstellen eines Datasets oder zum Abfragen eines regionalen Datasets) das Flag --location explizit angeben (z.B. --location=us oder --location=EU).
  5. Asynchrone Vorgänge: Einige Befehle initiieren synchrone Vorgänge mit langer Ausführungszeit, z.B. das Ausführen von Abfragejobs. Sie SOLLTEN für diese Befehle IMMER das Flag --nosync übergeben, um Agent-Timeouts zu vermeiden.
  6. Befehlseinschränkungen: Sie DÜRFEN die folgenden bq-Befehle NICHT verwenden: bq init, bq pyshell, bq shell. Die Weiterleitung oder Verkettung von Befehlen wird NICHT unterstützt.
  7. 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.

Beispiele für mutierende bq-Befehle sind: bq mk, bq rm, bq update, bq insert, bq query (ohne --dry_run) usw. Verwendung: RunBq(command="bq query --project_id=PROJECT_ID 'SELECT 1'", project="projects/PROJECT_ID", input_files=[{"path": "PATH", "contents": "CONTENTS"}]) Sie MÜSSEN den vollständigen bq-Befehl als einzelnen String im Parameter „command“ angeben. Sie MÜSSEN den Parameter „project“ (Format: projects/PROJECT_ID) als API-Ausführungsprojekt für Abrechnungs-, API-Aktivierungs- und Kontingentnutzungsprüfungen angeben.

Beispielhafte bq-Befehle/Muster:

  1. Abfrage ausführen: bq query --use_legacy_sql=false --project_id=PROJECT_ID 'SELECT * FROMproject.dataset.tableLIMIT 10'
  2. Dataset erstellen: bq mk --dataset --location=us --project_id=PROJECT_ID myDataset
  3. Tabelle erstellen: bq mk --table --project_id=PROJECT_ID myDataset.myTable name:string,value:integer
  4. Dataset entfernen: bq rm -f --dataset --project_id=PROJECT_ID myDataset
  5. Tabelle entfernen: bq rm -f -t --project_id=PROJECT_ID myDataset.myTable
  6. Tabellenbeschreibung aktualisieren: bq update --description="New description" --project_id=PROJECT_ID myDataset.myTable
  7. Datasets in einem Projekt auflisten: bq ls --datasets=true --project_id=PROJECT_ID

Spezifikationen für MCP-Tools abrufen

Wenn Sie die MCP-Tool-Spezifikationen für alle Tools auf einem MCP-Server abrufen möchten, verwenden Sie die Methode tools/list. Im folgenden Beispiel wird gezeigt, wie Sie mit curl alle Tools und ihre Spezifikationen auflisten, die derzeit auf dem MCP-Server verfügbar sind.

Curl-Anfrage 
curl --location 'https://cloudcli.googleapis.com/mcp' \
--header 'content-type: application/json' \
--header 'accept: application/json, text/event-stream' \
--data '{
    "method": "tools/list",
    "jsonrpc": "2.0",
    "id": 1
}'