MCP Reference: cloudcli.googleapis.com

Der Cloud CLI MCP Server bietet Tools zum Ausführen von 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 Übersicht über Google Cloud-MCP-Server.

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. Er 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 einem LLM oder einer KI-Anwendung zur Verfügung stellt, um eine Aktion in der realen Welt auszuführen.

Tools

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

MCP-Tools
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. 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. 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 keine vorkonfigurierten Projekt- oder Abrechnungseinstellungen annehmen. Für Befehle ohne Projektbereich (z.B. auf Ordner- oder Organisationsebene) oder bestimmte Szenarien wie Cloud Storage Requester Pays 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 Flag „--project“ 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. Im Befehlsstring muss mindestens eines der Flags „--project“ oder „--billing-project“ angegeben werden.
  7. Asynchrone Vorgänge: Bei lang andauernden synchronen Vorgängen (z.B. Erstellen einer VM oder einer Datenbank) SOLLTEN Sie IMMER das Flag --async übergeben, um Agent-Time-outs zu vermeiden.
  8. Ratenbegrenzung für Logs: Wenn Sie gcloud logging read verwenden, MÜSSEN Sie IMMER ein Flag --limit angeben (z.B. --limit=100), um Time-outs für 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 Wert von „contents“ 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).

Beispiele 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. 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. Einen 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 (stdout oder stderr). 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 jeden bq-Befehl im Projekt des Nutzers ausführen, einschließlich Befehlen, die GCP-Ressourcen erstellen, aktualisieren oder löschen (d.h. Mutationen). WICHTIGER SICHERHEITSHINWEIS (POTENZIELL DESTRUKTIV): Mit diesem Tool können BigQuery-Ressourcen erstellt, aktualisiert oder gelöscht werden (z.B. bq rm, bq cancel, bq query). Es ist NICHT auf schreibgeschützte Befehle beschränkt. Seien Sie äußerst vorsichtig. VERBOTENE BEFEHLE: Ein Agent darf die folgenden bq-Befehle NICHT ausführen: bq init, bq load, bq pyshell, bq shell. STRENGE AUSFÜHRUNGSREGELN:

  1. Im Befehlsstring muss mindestens eines der Flags „--project_id“ oder „--quota_project_id“ angegeben werden.
  2. Projekt-ID im Vergleich zum Kontingentprojekt: Das Flag „--project_id“ gibt das Ressourcenprojekt an, in dem der Befehl ausgeführt wird (entspricht dem Flag „--project“ von gcloud). Das Flag „--quota_project_id“ gibt das Projekt an, das für die Abrechnung/das Kontingent des nachgelagerten BigQuery API-Aufrufs in Rechnung gestellt wird (entspricht dem Flag „--billing-project“ 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 die Flag-Schlüssel von ihren Werten zu trennen. 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. Erstellen eines Datasets oder Abfragen eines regionalen Datasets) das Flag „--location“ explizit angeben (z.B. „--location=us“ oder „--location=EU“).
  5. Asynchrone Vorgänge: Einige Befehle initiieren synchrone, lang andauernde Vorgänge (z.B. Ausführen von Abfragejobs). Sie SOLLTEN für diese Befehle IMMER das Flag „--nosync“ übergeben, um Agent-Time-outs zu vermeiden.
  6. Befehlseinschränkungen: Sie DÜRFEN die folgenden bq-Befehle NICHT verwenden: „bq init“, „bq pyshell“, „bq shell“. Die Befehlsverkettung 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 die Abrechnung, die API-Aktivierung und die Überprüfung des Kontingentverbrauchs angeben.

Beispiele für bq-Befehle/Muster:

  1. Eine Abfrage ausführen: bq query --use_legacy_sql=false --project_id=PROJECT_ID 'SELECT * FROM project.dataset.table LIMIT 10'
  2. Ein Dataset erstellen: bq mk --dataset --location=us --project_id=PROJECT_ID myDataset
  3. Eine Tabelle erstellen: bq mk --table --project_id=PROJECT_ID myDataset.myTable name:string,value:integer
  4. Ein Dataset entfernen: bq rm -f --dataset --project_id=PROJECT_ID myDataset
  5. Eine 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

MCP-Tool-Spezifikationen abrufen

Verwenden Sie die Methode tools/list, um die MCP-Tool-Spezifikationen für alle Tools auf einem MCP-Server abzurufen. 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
}'