Eigenen MCP-Server in Python schreiben: SDK-Tutorial mit MCPServer

Mit dem of­fi­zi­el­len Python-SDK und der Klasse MCPServer (früher FastMCP) lässt sich ein eigener MCP-Server mit wenigen Zeilen Code erstellen. Mithilfe von De­co­ra­tors können Python-Funk­tio­nen als Tools, Resources und Prompts be­reit­ge­stellt werden. Der Pa­ket­ma­na­ger uv er­leich­tert die Ein­rich­tung, während der MCP Inspector das Testen der Ser­ver­funk­tio­nen er­mög­licht. An­schlie­ßend lässt sich der Server in KI-An­wen­dun­gen wie Claude Desktop einbinden.

Was ist ein Python-MCP-Server?

Ein Python-MCP-Server ist eine Anwendung, die mit der Pro­gram­mier­spra­che Python ent­wi­ckelt wird und KI-Systemen über das Model Context Protocol (MCP) externe Daten, Funk­tio­nen und vor­de­fi­nier­te Prompts be­reit­stellt. Der Server ver­ar­bei­tet Anfragen von MCP-Clients und er­mög­licht Sprach­mo­del­len, über ihre Host-Anwendung auf Python-Funk­tio­nen, APIs und weitere Da­ten­quel­len zu­zu­grei­fen.

Das Model Context Protocol (MCP) definiert dafür eine stan­dar­di­sier­te Kom­mu­ni­ka­ti­on zwischen KI-An­wen­dun­gen und an­ge­bun­de­nen Servern. Ein MCP-Host wie Claude Desktop verwaltet die Ver­bin­dung zu einem oder mehreren MCP-Servern über ent­spre­chen­de Clients. Diese können be­reit­ge­stell­te Funk­tio­nen aufrufen, Res­sour­cen abrufen und Prompt-Vorlagen verwenden.

Für die Ent­wick­lung eines MCP-Servers mit Python steht das of­fi­zi­el­le Python-SDK des MCP-Projekts zur Verfügung. Es übernimmt we­sent­li­che Aufgaben der Pro­to­koll­kom­mu­ni­ka­ti­on.

Projekt-Setup: Wie richtet man einen MCP-Server mit Python ein?

Für die Ent­wick­lung eines eigenen MCP-Servers auf Python-Basis werden die Pro­gram­mier­spra­che, ein Pa­ket­ma­na­ger und das of­fi­zi­el­le MCP-SDK benötigt. In diesem Tutorial kommt der Pa­ket­ma­na­ger uv zum Einsatz. Er übernimmt die Pro­jekt­in­itia­li­sie­rung, die Ver­wal­tung der Python-Ab­hän­gig­kei­ten und die Aus­füh­rung des Servers.

Schritt 1: Vor­aus­set­zun­gen

• Python: Version 3.10 oder neuer
• Pa­ket­ma­na­ger: uv, in­stal­liert und über das Terminal aufrufbar. Das Werkzeug übernimmt die Ein­rich­tung des Python-Projekts und die Ver­wal­tung der be­nö­tig­ten Bi­blio­the­ken. Al­ter­na­tiv kann auch der Python-Pa­ket­ma­na­ger pip verwendet werden.
• Ent­wick­lungs­um­ge­bung: Terminal und Code-Editor zum Schreiben und Ausführen des Python-Codes.
• Ja­va­Script-Lauf­zeit­um­ge­bung und Pa­ket­ver­wal­tung: Node.js (ab Version 22.19.0) und der zu­ge­hö­ri­ge Pa­ket­ma­na­ger npm werden für das Test­werk­zeug MCP Inspector benötigt. Mit dem Kom­man­do­zei­len­werk­zeug npx, das zusammen mit npm be­reit­ge­stellt wird, lässt sich der Inspector direkt starten, ohne ihn vorher separat in­stal­lie­ren zu müssen.
• Um­ge­bungs­va­ria­blen: Für das lokale Beispiel sind keine API-Schlüssel er­for­der­lich. Bei der Anbindung externer Dienste können bei­spiels­wei­se API_KEY oder DATABASE_URL notwendig werden.

Schritt 2: Python-Projekt in­itia­li­sie­ren

Erstellen Sie zunächst ein neues Projekt mit uv:

uv init mcp-server-demo
cd mcp-server-demo

Der erste Befehl legt das Pro­jekt­ver­zeich­nis und die grund­le­gen­den Pro­jekt­da­tei­en an. An­schlie­ßend wechseln Sie in das neue Ver­zeich­nis.

Schritt 3: MCP-SDK in­stal­lie­ren

In­stal­lie­ren Sie die MCP-Bi­blio­thek mit dem folgenden Befehl:

uv add "mcp[cli]"

Das Paket mcp enthält die Funk­tio­nen für die Ent­wick­lung von MCP-Servern und -Clients. Mit der Er­wei­te­rung [cli] werden zu­sätz­lich die Kom­man­do­zei­len­werk­zeu­ge in­stal­liert, die später für das Testen und die Ein­bin­dung des Servers benötigt werden.

Wenn Sie aus­schließ­lich das SDK benötigen, genügt auch folgendes Kommando:

uv add mcp

Für dieses Tutorial empfiehlt sich die Variante mit [cli], da Sie den Server an­schlie­ßend mit uv run mcp dev testen können.

Tools, Resources und Prompts mit MCPServer im­ple­men­tie­ren: Python-Code­bei­spiel

Die Ser­ver­klas­se MCPServer des of­fi­zi­el­len Python-SDK ver­ein­facht die Ent­wick­lung eines MCP-Servers. Mithilfe von Python De­co­ra­tors lassen sich Funk­tio­nen als Tools, Resources oder Prompts re­gis­trie­ren. Die Klasse übernimmt dabei unter anderem die Be­reit­stel­lung über das MCP-Protokoll und die au­to­ma­ti­sche Er­stel­lung von Ein­ga­be­sche­ma­ta anhand der Python-Typ­an­no­ta­tio­nen.

MCP un­ter­schei­det drei zentrale ser­ver­sei­ti­ge Bausteine (Server Pri­mi­ti­ves): Tools, Resources und Prompts. Sie erfüllen un­ter­schied­li­che Aufgaben, wie die folgende Tabelle zeigt.

Welche dieser Bausteine zum Einsatz kommen, hängt somit davon ab, ob das Sprach­mo­dell, die Host-Anwendung oder die nutzende Person die In­ter­ak­ti­on auslöst.

Schritt 1: MCP-Server mit MCPServer erstellen

Erstellen Sie im Pro­jekt­ver­zeich­nis eine Datei namens server.py. Das folgende Beispiel im­ple­men­tiert einen einfachen MCP-Server mit einem Be­rech­nungs­tool, einer dy­na­mi­schen Ressource und einer Prompt-Vorlage:

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")

Schritt 2: Tools re­gis­trie­ren

Mit dem Decorator @mcp.tool() wird eine Python-Funktion als MCP-Tool re­gis­triert:

@mcp.tool()
def add(a: int, b: int) -> int:
    """Addiert zwei ganze Zahlen."""
    return a + b

MCPServer liest die Funk­ti­ons­si­gna­tur und erstellt daraus die be­nö­tig­ten Metadaten. Die Parameter a und b sind als Ganz­zah­len definiert. Der Rück­ga­be­wert ist ebenfalls eine Ganzzahl. Ein MCP-Client kann die Funktion über den Namen add aufrufen und zwei Werte übergeben. Bei den Ar­gu­men­ten a=5 und b=3 liefert die Funktion das Ergebnis 8.

Schritt 3: Resources be­reit­stel­len

Mit @mcp.resource() können Sie Daten über einen URI zu­gäng­lich machen. Enthält der URI wie im folgenden Beispiel einen Platz­hal­ter, re­gis­triert MCPServer ein so­ge­nann­tes Resource Template:

@mcp.resource("greeting://{name}")
def get_greeting(name: str) -> str:
    """Gibt eine personalisierte Begrüßung zurück."""
    return f"Hallo, {name}!"

Der URI greeting://{name} enthält einen Platz­hal­ter. Beim Abruf wird dieser durch einen konkreten Namen ersetzt. Bei­spiels­wei­se liefert greeting://Anna die Antwort Hallo, Anna!. Nach demselben Prinzip können MCP-Server bei­spiels­wei­se Kon­fi­gu­ra­ti­ons­da­ten, Do­ku­men­ten­in­hal­te oder In­for­ma­tio­nen aus an­ge­bun­de­nen Systemen be­reit­stel­len. Anders als bei einem Tool steht dabei die Be­reit­stel­lung von Kontext im Vor­der­grund.

Schritt 4: Prompts de­fi­nie­ren

Mit dem Decorator @mcp.prompt() lässt sich eine wie­der­ver­wend­ba­re Prompt-Vorlage re­gis­trie­ren:

@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:

Fasse das Thema 'Python' in fünf verständlichen Sätzen zusammen.

Die Funktion erzeugt lediglich die Prompt-Vorlage. Die ei­gent­li­che Zu­sam­men­fas­sung übernimmt das Sprach­mo­dell in der an­ge­bun­de­nen KI-Anwendung.

MCP-Server mit dem MCP Inspector testen und debuggen

Der MCP Inspector ist ein of­fi­zi­el­les Ent­wick­ler­werk­zeug zur Über­prü­fung von MCP-Servern. Es er­mög­licht, ver­füg­ba­re Tools, Resources und Prompts an­zu­zei­gen, einzelne Funk­tio­nen auf­zu­ru­fen und die Kom­mu­ni­ka­ti­on zwischen Client und Server zu un­ter­su­chen. Der Inspector bietet eine grafische Web­ober­flä­che, einen CLI-Modus für au­to­ma­ti­sier­te Tests und eine in­ter­ak­ti­ve Ter­mi­nal­ober­flä­che.

Schritt 1: MCP Inspector starten

Für den lokalen Test starten Sie den Inspector aus dem Pro­jekt­ver­zeich­nis:

uv run mcp dev server.py

Der Befehl startet den Ent­wick­lungs­mo­dus und stellt den MCP Inspector bereit. Öffnen Sie die im Terminal an­ge­zeig­te URL im Browser.

Al­ter­na­tiv können Sie den Inspector direkt mit npx aufrufen:

npx @modelcontextprotocol/inspector uv run server.py

Der Befehl startet den MCP Inspector mit dem an­ge­ge­be­nen Python-Server. Öffnen Sie die im Terminal an­ge­zeig­te URL im Browser und stellen Sie die Ver­bin­dung zum Server her. An­schlie­ßend können Sie die re­gis­trier­ten Tools, Resource Templates und Prompts über­prü­fen.

Schritt 2: Tools, Resources und Prompts über­prü­fen

Nach dem Ver­bin­dungs­auf­bau können die re­gis­trier­ten Funk­tio­nen 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 zu­rück­ge­ge­ben werden.
2. Resource Templates: Öffnen Sie den Bereich „Resource Templates“ und wählen Sie greeting://{name} aus. Ersetzen Sie den Platz­hal­ter durch Anna und rufen Sie die Ressource über greeting://Anna ab. Der Server sollte Hallo, Anna! zu­rück­ge­ben.
3. Prompts: Wählen Sie summarize_topic und übergeben Sie Python als Argument. Der Server sollte die de­fi­nier­te Prompt-Vorlage zu­rück­ge­ben.

Damit lässt sich fest­stel­len, ob die Funk­tio­nen korrekt re­gis­triert wurden und über das MCP-Protokoll er­reich­bar sind.

Schritt 3: JSON-RPC-Kom­mu­ni­ka­ti­on über die CLI prüfen

Für Tests ohne grafische Ober­flä­che bietet der Inspector einen CLI-Modus. Dabei übernimmt er die Rolle eines MCP-Clients und kom­mu­ni­ziert über JSON-RPC mit dem Python-Server. Um die ver­füg­ba­ren Tools auf­zu­lis­ten, führen Sie im Pro­jekt­ver­zeich­nis folgenden Befehl aus:

npx @modelcontextprotocol/inspector --cli uv run server.py --method tools/list

Für einen gezielten Funk­ti­ons­auf­ruf verwenden Sie:

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 Un­ter­pro­zess, baut die MCP-Ver­bin­dung auf und sendet die ent­spre­chen­de Anfrage. An­schlie­ßend gibt er die Antwort im Terminal aus. Die CLI un­ter­stützt unter anderem die folgenden Methoden:

• initialize: Stellt die Ver­bin­dung zwischen MCP-Client und Server her und handelt die un­ter­stütz­ten Pro­to­koll­funk­tio­nen aus.
• tools/list: Listet alle ver­füg­ba­ren Tools des MCP-Servers auf.
• tools/call: Ruft ein be­stimm­tes Tool mit den an­ge­ge­be­nen Pa­ra­me­tern auf.
• resources/list: Listet die ver­füg­ba­ren Res­sour­cen des MCP-Servers auf.
• resources/templates/list: Listet ver­füg­ba­re Resource Templates wie greeting://{name} auf.
• resources/read: Liest eine konkrete Ressource, bei­spiels­wei­se greeting://Anna.
• prompts/list: Listet alle be­reit­ge­stell­ten Prompt-Vorlagen auf.
• prompts/get: Ruft eine Prompt-Vorlage mit den an­ge­ge­be­nen Ar­gu­men­ten ab.

Mit der Option --format json lässt sich die Ausgabe ma­schi­nen­les­bar wei­ter­ver­ar­bei­ten.

Python-MCP-Server in KI-Clients einbinden – am Beispiel von Claude Desktop

Nach dem er­folg­rei­chen Test kann der MCP-Server in einen lokalen KI-Client ein­ge­bun­den werden. Als Beispiel dient nach­fol­gend Claude Desktop. Die Anwendung un­ter­stützt lokale MCP-Server, die über stdio gestartet und über eine JSON-Kon­fi­gu­ra­ti­ons­da­tei re­gis­triert werden.

Schritt 1: Kon­fi­gu­ra­ti­ons­da­tei öffnen

Die Datei claude_desktop_config.json befindet sich je nach Be­triebs­sys­tem an einem anderen Spei­cher­ort:

Die Kon­fi­gu­ra­ti­ons­da­tei lässt sich auch über die Ent­wick­ler­ein­stel­lun­gen von Claude Desktop aufrufen. Falls sie noch nicht existiert, kann sie am vor­ge­se­he­nen Spei­cher­ort erstellt werden.

Schritt 2: MCP-Server kon­fi­gu­rie­ren

Fügen Sie der Kon­fi­gu­ra­ti­ons­da­tei einen Eintrag unter mcpServers hinzu:

{
    "mcpServers": {
        "python-demo": {
            "command": "uv",
            "args": [
                "--directory",
                "/SERVERPFAD/mcp-server-demo",
                "run",
                "server.py"
            ]
        }
    }
}

Ersetzen Sie /SERVERPFAD/mcp-server-demo durch den tat­säch­li­chen absoluten Pfad des Pro­jekt­ver­zeich­nis­ses. Unter Windows können Sie bei­spiels­wei­se C:\\Projekte\\mcp-server-demo verwenden.

Die wich­tigs­ten Be­stand­tei­le der Kon­fi­gu­ra­ti­on sind:

• mcpServers: Enthält die re­gis­trier­ten MCP-Server.
• python-demo: Legt einen frei wählbaren Namen für den Server fest.
• command: Gibt das aus­führ­ba­re Programm an, mit dem der Server gestartet wird.
• args: Enthält die Argumente für den Pa­ket­ma­na­ger uv, ein­schließ­lich des Pro­jekt­ver­zeich­nis­ses und der Python-Datei.

Falls Claude Desktop uv nicht findet, muss unter command der absolute Pfad zur aus­führ­ba­ren Datei ein­ge­tra­gen werden. Dieser lässt sich unter Windows mit where uv und unter macOS mit which uv ermitteln.

Schritt 3: Claude Desktop neu starten und Server testen

Nach dem Speichern der Kon­fi­gu­ra­ti­ons­da­tei muss Claude Desktop voll­stän­dig beendet und neu gestartet werden, damit die Anwendung den neuen MCP-Server lädt. Prüfen Sie an­schlie­ßend, ob python-demo in der Übersicht der ver­füg­ba­ren MCP-Server erscheint. Starten Sie danach eine neue Un­ter­hal­tung und geben Sie bei­spiels­wei­se folgende Anfrage ein:

Addiere die Zahlen 15 und 27 mit dem verfügbaren Python-Tool.

Claude kann daraufhin das re­gis­trier­te Tool add verwenden und das Ergebnis 42 zu­rück­ge­ben. Je nach Ein­stel­lun­gen muss der Tool-Aufruf zuvor bestätigt werden.

Wird der Server nicht erkannt, sollten die JSON-Syntax, die an­ge­ge­be­nen Pfade und die Start­be­rech­ti­gun­gen kon­trol­liert werden. Bei Problemen können die MCP-Logs von Claude Desktop zu­sätz­li­che Hinweise liefern. Für die Feh­ler­ana­ly­se im eigenen Python-Code kann außerdem Python-Logging ein­ge­setzt werden.