1. Einführung
Übersicht
In diesem Lab erstellen und stellen Sie einen MCP-Server (Model Context Protocol) bereit. MCP-Server sind nützlich, um LLMs Zugriff auf externe Tools und Dienste zu ermöglichen. Sie konfigurieren ihn als sicheren, produktionsbereiten Dienst in Cloud Run, auf den von mehreren Clients aus zugegriffen werden kann. Anschließend stellen Sie über die Gemini CLI eine Verbindung zum Remote-MCP-Server her.
Aufgaben
Wir verwenden FastMCP, um einen Zoo-MCP-Server mit zwei Tools zu erstellen: get_animals_by_species und get_animal_details. FastMCP bietet eine schnelle, Python-basierte Möglichkeit, MCP-Server und ‑Clients zu erstellen.
Lerninhalte
- Stellen Sie den MCP-Server in Cloud Run bereit.
- Sichern Sie den Endpunkt Ihres Servers, indem Sie für alle Anfragen eine Authentifizierung verlangen. So können nur autorisierte Clients und Agents mit ihm kommunizieren.
- Über die Gemini CLI eine Verbindung zu Ihrem sicheren MCP-Serverendpunkt herstellen
2. Projekt einrichten
- Wenn Sie noch kein Google-Konto haben, müssen Sie ein Google-Konto erstellen.
- Verwenden Sie stattdessen ein privates Konto. Bei Arbeitskonten und Konten von Bildungseinrichtungen kann es Einschränkungen geben, die verhindern, dass Sie die für dieses Lab erforderlichen APIs aktivieren.
- Melden Sie sich in der Google Cloud Console an.
- Aktivieren Sie die Abrechnung in der Cloud Console.
- Die Kosten für Cloud-Ressourcen für dieses Lab sollten weniger als 1 $betragen.
- Sie können die Schritte am Ende dieses Labs ausführen, um Ressourcen zu löschen und so weitere Kosten zu vermeiden.
- Neuen Nutzern steht die kostenlose Testversion mit einem Guthaben von 300$ zur Verfügung.
- Erstellen Sie ein neues Projekt oder wählen Sie ein vorhandenes Projekt aus.
3. Cloud Shell-Editor öffnen
- Klicken Sie auf diesen Link, um direkt zum Cloud Shell-Editor zu gelangen.
- Wenn Sie heute an irgendeinem Punkt zur Autorisierung aufgefordert werden, klicken Sie auf Autorisieren, um fortzufahren.
- Wenn das Terminal nicht unten auf dem Bildschirm angezeigt wird, öffnen Sie es:
- Klicken Sie auf Ansehen.
- Klicken Sie auf Terminal
.
- Legen Sie im Terminal Ihr Projekt mit diesem Befehl fest:
- Format:
gcloud config set project [PROJECT_ID] - Beispiel:
gcloud config set project lab-project-id-example - Wenn Sie sich nicht an Ihre Projekt-ID erinnern können:
- Sie können alle Ihre Projekt-IDs mit folgendem Befehl auflisten:
gcloud projects list | awk '/PROJECT_ID/{print $2}'
- Sie können alle Ihre Projekt-IDs mit folgendem Befehl auflisten:
- Format:
- Es sollte folgende Meldung angezeigt werden:
Updated property [core/project].
WARNINGsehen undDo you want to continue (Y/n)?gefragt werden, haben Sie die Projekt-ID wahrscheinlich falsch eingegeben. Drücken Sien, dannEnterund versuchen Sie, den Befehlgcloud config set projectnoch einmal auszuführen.
4. APIs aktivieren
Aktivieren Sie die APIs im Terminal:
gcloud services enable \
run.googleapis.com \
artifactregistry.googleapis.com \
cloudbuild.googleapis.com
Wenn Sie zur Autorisierung aufgefordert werden, klicken Sie auf Autorisieren, um fortzufahren.
Es kann einige Minuten dauern, bis dieser Befehl ausgeführt wird. Wenn die Ausführung erfolgreich war, erhalten Sie eine Meldung, die ungefähr so aussieht:
Operation "operations/acf.p2-73d90d00-47ee-447a-b600" finished successfully.
5. Python-Projekt vorbereiten
- Erstellen Sie einen Ordner mit dem Namen
mcp-on-cloudrun, um den Quellcode für die Bereitstellung zu speichern:mkdir mcp-on-cloudrun && cd mcp-on-cloudrun - Erstellen Sie mit dem Tool
uvein Python-Projekt, um einepyproject.toml-Datei zu generieren:uv init --description "Example of deploying an MCP server on Cloud Run" --bare --python 3.13uv initwird einepyproject.toml-Datei für Ihr Projekt erstellt.Führen Sie Folgendes aus, um den Inhalt der Datei aufzurufen:cat pyproject.toml[project] name = "mcp-on-cloudrun" version = "0.1.0" description = "Example of deploying an MCP server on Cloud Run" requires-python = ">=3.13" dependencies = []
6. MCP-Server für den Zoo erstellen
Um wertvollen Kontext für die Verbesserung der Verwendung von LLMs mit MCP bereitzustellen, richten Sie einen Zoo-MCP-Server mit FastMCP ein. Das ist ein Standard-Framework für die Arbeit mit dem Model Context Protocol. FastMCP bietet eine schnelle Möglichkeit, MCP-Server und ‑Clients mit Python zu erstellen. Dieser MCP-Server stellt Daten zu Tieren in einem fiktiven Zoo bereit. Der Einfachheit halber speichern wir die Daten im Arbeitsspeicher. Für einen Produktions-MCP-Server sollten Sie wahrscheinlich Daten aus Quellen wie Datenbanken oder APIs bereitstellen.
- Führen Sie den folgenden Befehl aus, um FastMCP als Abhängigkeit in der Datei
pyproject.tomlhinzuzufügen:uv add fastmcp==2.11.1 --no-syncuv.lock-Datei hinzugefügt. - Erstellen Sie eine neue
server.py-Datei für den MCP-Server-Quellcode und öffnen Sie sie:cloudshell edit server.pycloudshell editwird die Dateiserver.pyim Editor über dem Terminal geöffnet. - Fügen Sie der Datei
server.pyden folgenden MCP-Server-Quellcode für den Zoo hinzu:import asyncio import logging import os from typing import List, Dict, Any from fastmcp import FastMCP logger = logging.getLogger(__name__) logging.basicConfig(format="[%(levelname)s]: %(message)s", level=logging.INFO) mcp = FastMCP("Zoo Animal MCP Server 🦁🐧🐻") # Dictionary of animals at the zoo ZOO_ANIMALS = [ { "species": "lion", "name": "Leo", "age": 7, "enclosure": "The Big Cat Plains", "trail": "Savannah Heights" }, { "species": "lion", "name": "Nala", "age": 6, "enclosure": "The Big Cat Plains", "trail": "Savannah Heights" }, { "species": "lion", "name": "Simba", "age": 3, "enclosure": "The Big Cat Plains", "trail": "Savannah Heights" }, { "species": "lion", "name": "King", "age": 8, "enclosure": "The Big Cat Plains", "trail": "Savannah Heights" }, { "species": "penguin", "name": "Waddles", "age": 2, "enclosure": "The Arctic Exhibit", "trail": "Polar Path" }, { "species": "penguin", "name": "Pip", "age": 4, "enclosure": "The Arctic Exhibit", "trail": "Polar Path" }, { "species": "penguin", "name": "Skipper", "age": 5, "enclosure": "The Arctic Exhibit", "trail": "Polar Path" }, { "species": "penguin", "name": "Chilly", "age": 3, "enclosure": "The Arctic Exhibit", "trail": "Polar Path" }, { "species": "penguin", "name": "Pingu", "age": 6, "enclosure": "The Arctic Exhibit", "trail": "Polar Path" }, { "species": "penguin", "name": "Noot", "age": 1, "enclosure": "The Arctic Exhibit", "trail": "Polar Path" }, { "species": "elephant", "name": "Ellie", "age": 15, "enclosure": "The Pachyderm Sanctuary", "trail": "Savannah Heights" }, { "species": "elephant", "name": "Peanut", "age": 12, "enclosure": "The Pachyderm Sanctuary", "trail": "Savannah Heights" }, { "species": "elephant", "name": "Dumbo", "age": 5, "enclosure": "The Pachyderm Sanctuary", "trail": "Savannah Heights" }, { "species": "elephant", "name": "Trunkers", "age": 10, "enclosure": "The Pachyderm Sanctuary", "trail": "Savannah Heights" }, { "species": "bear", "name": "Smokey", "age": 10, "enclosure": "The Grizzly Gulch", "trail": "Polar Path" }, { "species": "bear", "name": "Grizzly", "age": 8, "enclosure": "The Grizzly Gulch", "trail": "Polar Path" }, { "species": "bear", "name": "Barnaby", "age": 6, "enclosure": "The Grizzly Gulch", "trail": "Polar Path" }, { "species": "bear", "name": "Bruin", "age": 12, "enclosure": "The Grizzly Gulch", "trail": "Polar Path" }, { "species": "giraffe", "name": "Gerald", "age": 4, "enclosure": "The Tall Grass Plains", "trail": "Savannah Heights" }, { "species": "giraffe", "name": "Longneck", "age": 5, "enclosure": "The Tall Grass Plains", "trail": "Savannah Heights" }, { "species": "giraffe", "name": "Patches", "age": 3, "enclosure": "The Tall Grass Plains", "trail": "Savannah Heights" }, { "species": "giraffe", "name": "Stretch", "age": 6, "enclosure": "The Tall Grass Plains", "trail": "Savannah Heights" }, { "species": "antelope", "name": "Speedy", "age": 2, "enclosure": "The Tall Grass Plains", "trail": "Savannah Heights" }, { "species": "antelope", "name": "Dash", "age": 3, "enclosure": "The Tall Grass Plains", "trail": "Savannah Heights" }, { "species": "antelope", "name": "Gazelle", "age": 4, "enclosure": "The Tall Grass Plains", "trail": "Savannah Heights" }, { "species": "antelope", "name": "Swift", "age": 5, "enclosure": "The Tall Grass Plains", "trail": "Savannah Heights" }, { "species": "polar bear", "name": "Snowflake", "age": 7, "enclosure": "The Arctic Exhibit", "trail": "Polar Path" }, { "species": "polar bear", "name": "Blizzard", "age": 5, "enclosure": "The Arctic Exhibit", "trail": "Polar Path" }, { "species": "polar bear", "name": "Iceberg", "age": 9, "enclosure": "The Arctic Exhibit", "trail": "Polar Path" }, { "species": "walrus", "name": "Wally", "age": 10, "enclosure": "The Walrus Cove", "trail": "Polar Path" }, { "species": "walrus", "name": "Tusker", "age": 12, "enclosure": "The Walrus Cove", "trail": "Polar Path" }, { "species": "walrus", "name": "Moby", "age": 8, "enclosure": "The Walrus Cove", "trail": "Polar Path" }, { "species": "walrus", "name": "Flippers", "age": 9, "enclosure": "The Walrus Cove", "trail": "Polar Path" } ] @mcp.tool() def get_animals_by_species(species: str) -> List[Dict[str, Any]]: """ Retrieves all animals of a specific species from the zoo. Can also be used to collect the base data for aggregate queries of animals of a specific species - like counting the number of penguins or finding the oldest lion. Args: species: The species of the animal (e.g., 'lion', 'penguin'). Returns: A list of dictionaries, where each dictionary represents an animal and contains details like name, age, enclosure, and trail. """ logger.info(f">>> 🛠️ Tool: 'get_animals_by_species' called for '{species}'") return [animal for animal in ZOO_ANIMALS if animal["species"].lower() == species.lower()] @mcp.tool() def get_animal_details(name: str) -> Dict[str, Any]: """ Retrieves the details of a specific animal by its name. Args: name: The name of the animal. Returns: A dictionary with the animal's details (species, name, age, enclosure, trail) or an empty dictionary if the animal is not found. """ logger.info(f">>> 🛠️ Tool: 'get_animal_details' called for '{name}'") for animal in ZOO_ANIMALS: if animal["name"].lower() == name.lower(): return animal return {} if __name__ == "__main__": logger.info(f"🚀 MCP server started on port {os.getenv('PORT', 8080)}") asyncio.run( mcp.run_async( transport="http", host="0.0.0.0", port=os.getenv("PORT", 8080), ) )
Dein Code ist fertig! Jetzt ist es an der Zeit, den MCP-Server in Cloud Run bereitzustellen.
7. In Cloud Run bereitstellen
Stellen Sie nun einen MCP-Server direkt aus dem Quellcode in Cloud Run bereit.
- Erstellen und öffnen Sie ein neues
Dockerfilefür die Bereitstellung in Cloud Run:cloudshell edit Dockerfile - Fügen Sie der Dockerfile den folgenden Code hinzu, um das Tool
uvzum Ausführen der Dateiserver.pyzu verwenden:# Use the official Python image FROM python:3.13-slim # Install uv COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/ # Install the project into /app COPY . /app WORKDIR /app # Allow statements and log messages to immediately appear in the logs ENV PYTHONUNBUFFERED=1 # Install dependencies RUN uv sync EXPOSE $PORT # Run the FastMCP server CMD ["uv", "run", "server.py"] - Führen Sie den Befehl
gcloudaus, um die Anwendung in Cloud Run bereitzustellen.gcloud run deploy zoo-mcp-server \ --no-allow-unauthenticated \ --region=europe-west1 \ --source=. \ --labels=dev-tutorial=codelab-mcp--no-allow-unauthenticated, um eine Authentifizierung zu erzwingen. Das ist aus Sicherheitsgründen wichtig. Wenn Sie keine Authentifizierung benötigen, kann jeder Ihren MCP-Server aufrufen und möglicherweise Ihr System beschädigen. - Bestätigen Sie die Erstellung eines neuen Artifact Registry-Repositorys. Da Sie zum ersten Mal aus Quellcode in Cloud Run bereitstellen, wird Folgendes angezeigt:
Deploying from source requires an Artifact Registry Docker repository to store built containers. A repository named [cloud-run-source-deploy] in region [europe-west1] will be created. Do you want to continue (Y/n)?
Yein und drücken Sie dieEnter-Taste. Dadurch wird ein Artifact Registry-Repository für Ihr Deployment erstellt. Dies ist erforderlich, um den Docker-Container des MCP-Servers für den Cloud Run-Dienst zu speichern. - Nach einigen Minuten wird eine Meldung wie die folgende angezeigt:
Service [zoo-mcp-server] revision [zoo-mcp-server-12345-abc] has been deployed and is serving 100 percent of traffic.
Sie haben Ihren MCP-Server bereitgestellt. Jetzt können Sie es verwenden.
8. Remote-MCP-Server zur Gemini CLI hinzufügen
Nachdem Sie einen Remote-MCP-Server erfolgreich bereitgestellt haben, können Sie mit verschiedenen Anwendungen wie Google Code Assist oder der Gemini CLI eine Verbindung zu ihm herstellen. In diesem Abschnitt stellen wir mit der Gemini CLI eine Verbindung zu Ihrem neuen Remote-MCP-Server her.
- Gewähren Sie Ihrem Nutzerkonto die Berechtigung, den Remote-MCP-Server aufzurufen.
gcloud projects add-iam-policy-binding $GOOGLE_CLOUD_PROJECT \ --member=user:$(gcloud config get-value account) \ --role='roles/run.invoker' - Speichern Sie Ihre Google Cloud-Anmeldedaten und Ihre Projektnummer in Umgebungsvariablen, damit Sie sie in der Datei „Gemini-Einstellungen“ verwenden können:
export PROJECT_NUMBER=$(gcloud projects describe $GOOGLE_CLOUD_PROJECT --format="value(projectNumber)") export ID_TOKEN=$(gcloud auth print-identity-token) - Gemini CLI-Einstellungsdatei öffnen
cloudshell edit ~/.gemini/settings.json - Gemini CLI-Einstellungsdatei ersetzen, um den Cloud Run-MCP-Server hinzuzufügen
{ "mcpServers": { "zoo-remote": { "httpUrl": "https://zoo-mcp-server-$PROJECT_NUMBER.europe-west1.run.app/mcp/", "headers": { "Authorization": "Bearer $ID_TOKEN" } } }, "selectedAuthType": "cloud-shell", "hasSeenIdeIntegrationNudge": true }
- Gemini CLI in Cloud Shell starten
geminiEnterdrücken, um einige Standardeinstellungen zu akzeptieren.
- Gemini soll die MCP-Tools auflisten, die im Kontext verfügbar sind.
/mcp - Gemini bitten, etwas im Zoo zu finden
Where can I find penguins?zoo-remote-MCP-Server verwendet werden soll, und Sie fragen, ob Sie die Ausführung von MCP zulassen möchten. - Verwenden Sie den Abwärtspfeil und drücken Sie dann
Enter, um eine Option auszuwählen.Yes, always allow all tools from server "zoo-remote"
In der Ausgabe sollte die richtige Antwort und ein Feld angezeigt werden, das darauf hinweist, dass der MCP-Server verwendet wurde.
Sie haben es geschafft! Sie haben einen Remote-MCP-Server erfolgreich in Cloud Run bereitgestellt und mit der Gemini CLI getestet.
Wenn Sie die Sitzung beenden möchten, geben Sie /quit ein und drücken Sie dann Enter, um Gemini CLI zu beenden.
Debugging
Wenn Sie einen Fehler wie diesen sehen:
🔍 Attempting OAuth discovery for 'zoo-remote'... ❌ 'zoo-remote' requires authentication but no OAuth configuration found Error connecting to MCP server 'zoo-remote': MCP server 'zoo-remote' requires authentication. Please configure OAuth or check server settings.
Wahrscheinlich ist das ID-Token abgelaufen und muss noch einmal festgelegt werden.ID_TOKEN
- Geben Sie
/quitein und drücken Sie dannEnter, um Gemini CLI zu beenden. - Projekt im Terminal festlegen
gcloud config set project [PROJECT_ID] - Bei Schritt 2 oben neu beginnen
9. (Optional) Tool-Aufrufe in Serverlogs prüfen
Prüfen Sie die Dienstlogs, um zu sehen, ob Ihr Cloud Run-MCP-Server aufgerufen wurde.
gcloud run services logs read zoo-mcp-server --region europe-west1 --limit=5
Sie sollten ein Ausgabeprotokoll sehen, das bestätigt, dass ein Toolaufruf erfolgt ist. 🛠️
2025-08-05 19:50:31 INFO: 169.254.169.126:39444 - "POST /mcp/ HTTP/1.1" 200 OK 2025-08-05 19:50:31 [INFO]: Processing request of type CallToolRequest 2025-08-05 19:50:31 [INFO]: >>> 🛠️ Tool: 'get_animals_by_species' called for 'penguin'
10. Optional: MCP-Aufforderung zum Server hinzufügen
Mit einem MCP-Prompt können Sie Ihren Workflow für Prompts, die Sie häufig ausführen, beschleunigen, indem Sie eine Kurzform für einen längeren Prompt erstellen.
In der Gemini CLI werden MCP-Prompts automatisch in benutzerdefinierte Slash-Befehle umgewandelt. Sie können einen MCP-Prompt also aufrufen, indem Sie /prompt_name eingeben, wobei prompt_name der Name Ihres MCP-Prompts ist.
Erstellen Sie einen MCP-Prompt, damit Sie schnell ein Tier im Zoo finden können, indem Sie /find animal in die Gemini CLI eingeben.
- Fügen Sie diesen Code in Ihre
server.py-Datei über dem Hauptschutz (if __name__ == "__main__":) ein.@mcp.prompt() def find(animal: str) -> str: """ Find which exhibit and trail a specific animal might be located. """ return ( f"Please find the exhibit and trail information for {animal} in the zoo. " f"Respond with '[animal] can be found in the [exhibit] on the [trail].'" f"Example: Penguins can be found in The Arctic Exhibit on the Polar Path." ) - Anwendung in Cloud Run neu bereitstellen
gcloud run deploy zoo-mcp-server \ --no-allow-unauthenticated \ --region=europe-west1 \ --source=. \ --labels=dev-tutorial=codelab-mcp - ID_TOKEN für Ihren Remote-MCP-Server aktualisieren
export ID_TOKEN=$(gcloud auth print-identity-token) - Starten Sie die Gemini-Befehlszeile, nachdem die neue Version Ihrer Anwendung bereitgestellt wurde.
gemini - Verwenden Sie im Prompt den neuen benutzerdefinierten Befehl, den Sie erstellt haben:
/find --animal="lions"
Sie sollten sehen, dass Gemini CLI das get_animals_by_species-Tool aufruft und die Antwort gemäß dem MCP-Prompt formatiert.
╭───────────────────────────╮
│ > /find --animal="lion" │
╰───────────────────────────╯
╭───────────────────────────────────────────────────────────────────────────────────────────────────╮
│ ✔ get_animals_by_species (zoo-remote MCP Server) get_animals_by_species (zoo-remote MCP Server) │
│ │
│ [{"species":"lion","name":"Leo","age":7,"enclosure":"The Big Cat │
│ Plains","trail":"Savannah │
│ Heights"},{"species":"lion","name":"Nala","age":6,"enclosure":"The Big Cat │
│ Plains","trail":"Savannah │
│ Heights"},{"species":"lion","name":"Simba","age":3,"enclosure":"The Big Cat │
│ Plains","trail":"Savannah │
│ Heights"},{"species":"lion","name":"King","age":8,"enclosure":"The Big Cat │
│ Plains","trail":"Savannah Heights"}] │
╰───────────────────────────────────────────────────────────────────────────────────────────────────╯
✦ Lions can be found in The Big Cat Plains on the Savannah Heights.
Hochgesteckte Ziele, um dich selbst herauszufordern
Als zusätzliche Herausforderung können Sie versuchen, mit denselben Schritten einen Prompt zu erstellen, mit dem Sie interessante Fakten über bestimmte Tierarten im Zoo erhalten.
Oder Sie können sich noch weiter aus Ihrer Komfortzone wagen und ein Tool entwickeln, das Sie häufig verwenden würden, und einen zweiten Remote-MCP-Server bereitstellen. Fügen Sie sie dann Ihren Gemini-Befehlszeileneinstellungen hinzu, um zu sehen, ob sie funktioniert.
11. Fazit
Glückwunsch! Sie haben einen sicheren Remote-MCP-Server erfolgreich bereitgestellt und eine Verbindung dazu hergestellt.
Mit dem nächsten Lab fortfahren
Dieses Lab ist das erste Lab einer dreiteiligen Reihe. Im zweiten Lab verwenden Sie den MCP-Server, den Sie mit einem ADK-Agenten erstellt haben.
MCP-Server in Cloud Run mit einem ADK-Agent verwenden
Optional: Bereinigen
Wenn Sie nicht mit dem nächsten Lab fortfahren und die erstellten Ressourcen bereinigen möchten, können Sie Ihr Cloud-Projekt löschen, um zusätzliche Gebühren zu vermeiden.
Während für Cloud Run keine Kosten anfallen, wenn der Dienst nicht verwendet wird, wird Ihnen dennoch das Speichern des Container-Images in Artifact Registry möglicherweise in Rechnung gestellt. Durch das Löschen des Cloud-Projekts wird die Abrechnung für alle in diesem Projekt verwendeten Ressourcen beendet.
Wenn Sie möchten, können Sie das Projekt löschen:
gcloud projects delete $GOOGLE_CLOUD_PROJECT
Möglicherweise möchten Sie auch unnötige Ressourcen von Ihrer Cloud Shell-Festplatte löschen. Sie haben folgende Möglichkeiten:
- Löschen Sie das Codelab-Projektverzeichnis:
rm -rf ~/mcp-on-cloudrun - Warnung! Diese Aktion kann nicht rückgängig gemacht werden. Wenn Sie alles in Cloud Shell löschen möchten, um Speicherplatz freizugeben, können Sie Ihr gesamtes Basisverzeichnis löschen. Achten Sie darauf, dass alles, was Sie behalten möchten, an einem anderen Ort gespeichert ist.
sudo rm -rf $HOME