# Eigenen MCP-Server in Python schreiben: SDK-Tutorial mit MCPServer Mit dem offiziellen Python-SDK und der Klasse MCPServer (früher FastMCP) lässt sich ein eigener MCP-Server mit wenigen Zeilen Code erstellen. Mithilfe von Decorators können Python-Funktionen als Tools, Resources und Prompts bereitgestellt werden. Der Paketmanager uv erleichtert die Einrichtung, während der MCP Inspector das Testen der Serverfunktionen ermöglicht. Anschließend lässt sich der Server in KI-Anwendungen wie Claude Desktop einbinden. ## Was ist ein Python-MCP-Server? Ein Python-MCP-Server ist eine Anwendung, die mit der Programmiersprache [Python](https://www.ionos.at/digitalguide/websites/web-entwicklung/python-tutorial/) entwickelt wird und KI-Systemen über das [Model Context Protocol (MCP)](https://www.ionos.at/digitalguide/server/knowhow/model-context-protocol/) **externe Daten, Funktionen und vordefinierte Prompts bereitstellt**. Der Server verarbeitet Anfragen von MCP-Clients und ermöglicht Sprachmodellen, über ihre Host-Anwendung auf Python-Funktionen, [APIs](https://www.ionos.at/digitalguide/websites/web-entwicklung/was-ist-eine-api/) und weitere Datenquellen zuzugreifen. Das Model Context Protocol (MCP) definiert dafür eine **standardisierte Kommunikation** zwischen KI-Anwendungen und angebundenen Servern. Ein MCP-Host wie Claude Desktop verwaltet die Verbindung zu einem oder mehreren MCP-Servern über entsprechende Clients. Diese können bereitgestellte Funktionen aufrufen, Ressourcen abrufen und Prompt-Vorlagen verwenden. Für die Entwicklung eines MCP-Servers mit Python steht das offizielle **Python-SDK des MCP-Projekts** zur Verfügung. Es übernimmt wesentliche Aufgaben der Protokollkommunikation. ## Projekt-Setup: Wie richtet man einen MCP-Server mit Python ein? Für die Entwicklung eines eigenen MCP-Servers auf Python-Basis werden die Programmiersprache, ein Paketmanager und das offizielle MCP-SDK benötigt. In diesem Tutorial kommt der **Paketmanager uv** zum Einsatz. Er übernimmt die Projektinitialisierung, die Verwaltung der Python-Abhängigkeiten und die Ausführung des Servers. ### Schritt 1: Voraussetzungen - **Python**: Version 3.10 oder neuer - **Paketmanager**: uv, installiert und über das Terminal aufrufbar. Das Werkzeug übernimmt die Einrichtung des Python-Projekts und die Verwaltung der benötigten Bibliotheken. Alternativ kann auch der Python-Paketmanager pip verwendet werden. - **Entwicklungsumgebung**: Terminal und [Code-Editor](https://www.ionos.at/digitalguide/websites/web-entwicklung/code-editoren/) zum Schreiben und Ausführen des Python-Codes. - **JavaScript-Laufzeitumgebung und Paketverwaltung**: [Node.js](https://www.ionos.at/digitalguide/websites/web-entwicklung/einfuehrung-in-nodejs/) (ab Version 22.19.0) und der zugehörige Paketmanager npm werden für das Testwerkzeug MCP Inspector benötigt. Mit dem Kommandozeilenwerkzeug `npx`, das zusammen mit npm bereitgestellt wird, lässt sich der Inspector direkt starten, ohne ihn vorher separat installieren zu müssen. - **Umgebungsvariablen**: Für das lokale Beispiel sind keine API-Schlüssel erforderlich. Bei der Anbindung externer Dienste können beispielsweise `API_KEY` oder `DATABASE_URL` notwendig werden. ### Schritt 2: Python-Projekt initialisieren Erstellen Sie zunächst ein neues Projekt mit uv: ```bash uv init mcp-server-demo cd mcp-server-demo ``` Der erste Befehl legt das Projektverzeichnis und die grundlegenden Projektdateien an. Anschließend wechseln Sie in das neue Verzeichnis. ### Schritt 3: MCP-SDK installieren Installieren Sie die MCP-Bibliothek mit dem folgenden Befehl: ```bash uv add "mcp[cli]" ``` Das Paket mcp enthält die Funktionen für die Entwicklung von MCP-Servern und -Clients. Mit der Erweiterung [cli] werden zusätzlich die Kommandozeilenwerkzeuge installiert, die später für das Testen und die Einbindung des Servers benötigt werden. Wenn Sie ausschließlich das SDK benötigen, genügt auch folgendes Kommando: ```bash uv add mcp ``` Für dieses Tutorial empfiehlt sich die Variante mit [cli], da Sie den Server anschließend mit uv run mcp dev testen können. ## Tools, Resources und Prompts mit `MCPServer` implementieren: Python-Codebeispiel Die Serverklasse `MCPServer` des offiziellen Python-SDK vereinfacht die Entwicklung eines MCP-Servers. Mithilfe von [Python Decorators](https://www.ionos.at/digitalguide/websites/web-entwicklung/python-decorators/) lassen sich Funktionen als Tools, Resources oder Prompts registrieren. Die Klasse übernimmt dabei unter anderem die Bereitstellung über das MCP-Protokoll und die automatische Erstellung von Eingabeschemata anhand der Python-Typannotationen. MCP unterscheidet **drei zentrale serverseitige Bausteine** (Server Primitives): Tools, Resources und Prompts. Sie erfüllen unterschiedliche Aufgaben, wie die folgende Tabelle zeigt.
Baustein (Server Primitive) Steuerung Funktion Typischer Use Case
Tools Modellgesteuert Führen Funktionen und Aktionen aus Berechnungen, API-Abfragen, Datenbearbeitung
Resources Anwendungsgesteuert Stellen Daten und Kontext bereit Dokumente, Konfigurationsdaten, Datenbankinhalte
Prompts Nutzergesteuert Liefern wiederverwendbare Prompt-Vorlagen Slash-Commands, Menüeinträge, Zusammenfassungen
Welche dieser Bausteine zum Einsatz kommen, hängt somit davon ab, ob das Sprachmodell, die Host-Anwendung oder die nutzende Person die Interaktion auslöst. ### Schritt 1: MCP-Server mit `MCPServer` erstellen Erstellen Sie im Projektverzeichnis eine Datei namens `server.py`. Das folgende Beispiel implementiert einen einfachen MCP-Server mit einem Berechnungstool, einer dynamischen Ressource und einer Prompt-Vorlage: ```python from mcp.server import MCPServer # MCP-Server initialisieren mcp = MCPServer("PythonDemo") # Tool: Zwei Zahlen addieren @mcp.tool() def add(a: int, b: int) -> int: """Addiert zwei ganze Zahlen.""" return a + b # Resource: Personalisierte Begrüßung bereitstellen @mcp.resource("greeting://{name}") def get_greeting(name: str) -> str: """Gibt eine personalisierte Begrüßung zurück.""" return f"Hallo, {name}!" # Prompt: Vorlage für eine Zusammenfassung @mcp.prompt() def summarize_topic(topic: str) -> str: """Erstellt eine Prompt-Vorlage für ein Thema.""" return ( f"Fasse das Thema '{topic}' in fünf " "verständlichen Sätzen zusammen." ) # MCP-Server über stdio starten if __name__ == "__main__": mcp.run(transport="stdio") ``` Hinweis Im offiziellen Python-SDK 1.x hieß die Serverklasse noch FastMCP und wurde über mcp.server.fastmcp importiert. In SDK 2.x wurde sie in MCPServer umbenannt. Der bisherige Import führt deshalb zu einem ModuleNotFoundError. Für bestehende Projekte mit SDK 1.x kann die Abhängigkeit auf mcp<2 begrenzt werden. Unabhängig davon existiert das eigenständige Framework fastmcp, das weiterhin über from fastmcp import FastMCP eingebunden wird. ### Schritt 2: Tools registrieren Mit dem Decorator `@mcp.tool()` wird eine Python-Funktion als MCP-Tool registriert: ```python @mcp.tool() def add(a: int, b: int) -> int: """Addiert zwei ganze Zahlen.""" return a + b ``` MCPServer liest die Funktionssignatur und erstellt daraus die benötigten Metadaten. Die Parameter a und b sind als Ganzzahlen definiert. Der Rückgabewert ist ebenfalls eine Ganzzahl. Ein MCP-Client kann die Funktion über den Namen add aufrufen und zwei Werte übergeben. Bei den Argumenten a=5 und b=3 liefert die Funktion das Ergebnis 8. ### Schritt 3: Resources bereitstellen Mit `@mcp.resource()` können Sie Daten über einen URI zugänglich machen. Enthält der URI wie im folgenden Beispiel einen Platzhalter, registriert `MCPServer` ein sogenanntes Resource Template: ```python @mcp.resource("greeting://{name}") def get_greeting(name: str) -> str: """Gibt eine personalisierte Begrüßung zurück.""" return f"Hallo, {name}!" ``` Der [URI](https://www.ionos.at/digitalguide/websites/web-entwicklung/uniform-resource-identifier/) greeting://{name} enthält einen Platzhalter. Beim Abruf wird dieser durch einen konkreten Namen ersetzt. Beispielsweise liefert greeting://Anna die Antwort Hallo, Anna!. Nach demselben Prinzip können MCP-Server beispielsweise Konfigurationsdaten, Dokumenteninhalte oder Informationen aus angebundenen Systemen bereitstellen. Anders als bei einem Tool steht dabei die **Bereitstellung von Kontext** im Vordergrund. ### Schritt 4: Prompts definieren Mit dem Decorator `@mcp.prompt()` lässt sich eine wiederverwendbare Prompt-Vorlage registrieren: ```python @mcp.prompt() def summarize_topic(topic: str) -> str: """Erstellt eine Prompt-Vorlage für ein Thema.""" return ( f"Fasse das Thema '{topic}' in fünf " "verständlichen Sätzen zusammen." ) ``` Wird der Prompt mit dem Argument topic="Python" abgerufen, entsteht die folgende Anweisung: ```txt Fasse das Thema 'Python' in fünf verständlichen Sätzen zusammen. ``` Die Funktion erzeugt lediglich die Prompt-Vorlage. Die eigentliche Zusammenfassung übernimmt das Sprachmodell in der angebundenen KI-Anwendung. ## MCP-Server mit dem MCP Inspector testen und debuggen Der MCP Inspector ist ein offizielles Entwicklerwerkzeug zur Überprüfung von MCP-Servern. Es ermöglicht, verfügbare Tools, Resources und Prompts anzuzeigen, einzelne Funktionen aufzurufen und die Kommunikation zwischen Client und Server zu untersuchen. Der Inspector bietet eine grafische Weboberfläche, einen CLI-Modus für automatisierte Tests und eine interaktive Terminaloberfläche. ### Schritt 1: MCP Inspector starten Für den lokalen Test starten Sie den Inspector aus dem Projektverzeichnis: ```bash uv run mcp dev server.py ``` Der Befehl startet den Entwicklungsmodus und stellt den MCP Inspector bereit. Öffnen Sie die im Terminal angezeigte URL im Browser. Alternativ können Sie den Inspector direkt mit `npx` aufrufen: ```bash npx @modelcontextprotocol/inspector uv run server.py ``` Der Befehl startet den MCP Inspector mit dem angegebenen Python-Server. Öffnen Sie die im Terminal angezeigte URL im Browser und stellen Sie die Verbindung zum Server her. Anschließend können Sie die registrierten Tools, Resource Templates und Prompts überprüfen. ### Schritt 2: Tools, Resources und Prompts überprüfen Nach dem Verbindungsaufbau können die registrierten Funktionen getestet werden: 1. **Tools**: Öffnen Sie den Bereich „Tools“, wählen Sie `add` und übergeben Sie die Werte `5` und `3`. Als Ergebnis sollte `8` zurückgegeben werden. 2. **Resource Templates**: Öffnen Sie den Bereich „Resource Templates“ und wählen Sie `greeting://{name}` aus. Ersetzen Sie den Platzhalter durch `Anna` und rufen Sie die Ressource über `greeting://Anna` ab. Der Server sollte `Hallo, Anna!` zurückgeben. 3. **Prompts**: Wählen Sie `summarize_topic` und übergeben Sie `Python` als Argument. Der Server sollte die definierte Prompt-Vorlage zurückgeben. Damit lässt sich feststellen, ob die Funktionen korrekt registriert wurden und über das MCP-Protokoll erreichbar sind. ### Schritt 3: JSON-RPC-Kommunikation über die CLI prüfen Für Tests ohne grafische Oberfläche bietet der Inspector einen CLI-Modus. Dabei übernimmt er die Rolle eines MCP-Clients und kommuniziert über JSON-RPC mit dem Python-Server. Um die verfügbaren Tools aufzulisten, führen Sie im Projektverzeichnis folgenden Befehl aus: ```bash npx @modelcontextprotocol/inspector --cli uv run server.py --method tools/list ``` Für einen gezielten Funktionsaufruf verwenden Sie: ```bash npx @modelcontextprotocol/inspector --cli uv run server.py --method tools/call --tool-name add --tool-arg a=5 --tool-arg b=3 ``` Der Inspector startet den Server als Unterprozess, baut die MCP-Verbindung auf und sendet die entsprechende Anfrage. Anschließend gibt er die Antwort im Terminal aus. Die CLI unterstützt unter anderem die folgenden Methoden: - `initialize`: Stellt die Verbindung zwischen MCP-Client und Server her und handelt die unterstützten Protokollfunktionen aus. - `tools/list`: Listet alle verfügbaren Tools des MCP-Servers auf. - `tools/call`: Ruft ein bestimmtes Tool mit den angegebenen Parametern auf. - `resources/list`: Listet die verfügbaren Ressourcen des MCP-Servers auf. - `resources/templates/list`: Listet verfügbare Resource Templates wie `greeting://{name}` auf. - `resources/read`: Liest eine konkrete Ressource, beispielsweise `greeting://Anna`. - `prompts/list`: Listet alle bereitgestellten Prompt-Vorlagen auf. - `prompts/get`: Ruft eine Prompt-Vorlage mit den angegebenen Argumenten ab. Mit der Option `--format json` lässt sich die Ausgabe maschinenlesbar weiterverarbeiten. Hinweis Wenn der Inspector keine Verbindung herstellen kann, sollten Sie zunächst den Python-Pfad, die installierten Abhängigkeiten und das Projektverzeichnis prüfen. Außerdem muss sichergestellt sein, dass der Server über stdio startet und keine zusätzlichen Ausgaben auf stdout schreibt. ## Python-MCP-Server in KI-Clients einbinden – am Beispiel von Claude Desktop Nach dem erfolgreichen Test kann der MCP-Server in einen lokalen KI-Client eingebunden werden. Als Beispiel dient nachfolgend Claude Desktop. Die Anwendung unterstützt lokale MCP-Server, die über `stdio` gestartet und über eine [JSON](https://www.ionos.at/digitalguide/server/knowhow/was-ist-json/)-Konfigurationsdatei registriert werden. Hinweis Alternativ lässt sich der MCP-Server mit uv run mcp install server.py automatisch in Claude Desktop registrieren. Der Befehl trägt den Server mit den erforderlichen absoluten Pfaden in die Konfigurationsdatei ein. Eine manuelle Einrichtung ist dann nicht notwendig. ### Schritt 1: Konfigurationsdatei öffnen Die Datei [claude\_desktop\_config.json](https://www.ionos.at/digitalguide/server/konfiguration/claude-mcp/) befindet sich je nach Betriebssystem an einem anderen Speicherort:
Betriebssystem Speicherort
Windows %APPDATA%\Claude\claude_desktop_config.json
macOS ~/Library/Application Support/Claude/claude_desktop_config.json
Linux ~/.config/Claude/claude_desktop_config.json (Beta; nicht in der offiziellen MCP-Dokumentation ausgewiesen)
Die Konfigurationsdatei lässt sich auch über die Entwicklereinstellungen von Claude Desktop aufrufen. Falls sie noch nicht existiert, kann sie am vorgesehenen Speicherort erstellt werden. ### Schritt 2: MCP-Server konfigurieren Fügen Sie der Konfigurationsdatei einen Eintrag unter `mcpServers` hinzu: ```json { "mcpServers": { "python-demo": { "command": "uv", "args": [ "--directory", "/SERVERPFAD/mcp-server-demo", "run", "server.py" ] } } } ``` Ersetzen Sie /SERVERPFAD/mcp-server-demo durch den tatsächlichen absoluten Pfad des Projektverzeichnisses. Unter Windows können Sie beispielsweise C:\\Projekte\\mcp-server-demo verwenden. Die wichtigsten Bestandteile der Konfiguration sind: - `mcpServers`: Enthält die registrierten MCP-Server. - `python-demo`: Legt einen frei wählbaren Namen für den Server fest. - `command`: Gibt das ausführbare Programm an, mit dem der Server gestartet wird. - `args`: Enthält die Argumente für den Paketmanager uv, einschließlich des Projektverzeichnisses und der Python-Datei. Falls Claude Desktop uv nicht findet, muss unter `command` der absolute Pfad zur ausführbaren Datei eingetragen werden. Dieser lässt sich unter Windows mit `where uv` und unter macOS mit `which uv` ermitteln. Hinweis Benötigt ein MCP-Server Zugangsdaten für externe APIs oder Datenbanken, können diese über den Konfigurationsschlüssel env bereitgestellt werden. Sensible Zugangsdaten sollten nicht fest im Python-Quellcode hinterlegt werden. Für produktive Anwendungen empfiehlt sich eine geeignete Secret-Verwaltung. ### Schritt 3: Claude Desktop neu starten und Server testen Nach dem Speichern der Konfigurationsdatei muss Claude Desktop vollständig beendet und neu gestartet werden, damit die Anwendung den neuen MCP-Server lädt. Prüfen Sie anschließend, ob `python-demo` in der Übersicht der verfügbaren MCP-Server erscheint. Starten Sie danach eine neue Unterhaltung und geben Sie beispielsweise folgende Anfrage ein: ```txt Addiere die Zahlen 15 und 27 mit dem verfügbaren Python-Tool. ``` Claude kann daraufhin das registrierte Tool add verwenden und das Ergebnis 42 zurückgeben. Je nach Einstellungen muss der Tool-Aufruf zuvor bestätigt werden. Wird der Server nicht erkannt, sollten die JSON-Syntax, die angegebenen Pfade und die Startberechtigungen kontrolliert werden. Bei Problemen können die MCP-Logs von Claude Desktop zusätzliche Hinweise liefern. Für die Fehleranalyse im eigenen Python-Code kann außerdem [Python-Logging](https://www.ionos.at/digitalguide/websites/web-entwicklung/python-logging/) eingesetzt werden. This is a markdown version of: [https://www.ionos.at/digitalguide/server/konfiguration/mcp-server-python/](https://www.ionos.at/digitalguide/server/konfiguration/mcp-server-python/) for AI/LLM consumption.