Die meisten Anleitungen zum Model Context Protocol (MCP) zeigen dir, wie du einen Server installierst, den jemand anderes geschrieben hat. Diese hier zeigt dir, wie du deinen eigenen MCP-Server mit Python baust: einen kleinen Server mit zwei Tools, die jede MCP-fähige KI-App aufrufen kann. Du baust ihn, testest ihn ohne KI-App, prüfst ihn mit dem offiziellen MCP Inspector und verbindest ihn anschließend mit einem Editor oder Assistenten.
Das Wichtigste in Kürze
- Das offizielle MCP Python SDK 2.x hat die Server-Klasse in MCPServer umbenannt, deshalb laufen viele ältere Tutorials nicht mehr so, wie sie geschrieben sind.
- Versiehst du eine Funktion mit dem Decorator @mcp.tool(), wird sie zum Tool; Name, Beschreibung und Eingabeschema kommen aus deinem Code.
- Teste den Server im Speicher mit der Client-Klasse des SDK und danach über stdio mit dem offiziellen MCP Inspector.
- Verbinde ihn mit Cursor, VS Code oder Claude Desktop, indem du der App einen uv-Startbefehl mit absolutem Pfad gibst.
Stand 15. November 2026 ist das offizielle Python SDK bei Version 2.3.0 (veröffentlicht am 2. Oktober 2026) und der MCP Inspector bei Version 2.15.0 (veröffentlicht am 12. November 2026). SDK 2.x hat die zentrale Server-Klasse umbenannt, deshalb laufen viele ältere Tutorials nicht mehr so, wie sie geschrieben sind. Die Projekt-, Test- und Inspector-Befehle unten wurden mit genau diesen Versionen ausgeführt.
Was ein MCP-Server ist
MCP ist ein Open-Source-Standard, um KI-Anwendungen mit externen Systemen zu verbinden. Drei Begriffe aus der SDK-Dokumentation reichen, um mitzukommen:
- Ein Host ist die KI-App, mit der du sprichst, etwa ein Chat-Assistent oder ein Code-Editor.
- Ein Client steckt im Host und spricht MCP.
- Ein Server ist das, was du baust. Er kann Tools (Funktionen, die das Modell aufruft), Resources (Daten, die die App lädt) und Prompts (Vorlagen, die der Nutzer auswählt) anbieten.
Diese Anleitung beschränkt sich auf Tools. Die beiden, die du schreibst, ein Wortzähler und ein Datumsrechner, erledigen exakte Arbeit, die Code besser kann als die Schätzung eines Modells.
Was du brauchst
- uv, der Python-Projektmanager aus dem offiziellen MCP-Tutorial. Er lädt Python für dich herunter, falls keine passende Version vorhanden ist. Das SDK braucht Python 3.10 oder neuer.
- Node.js, nur für den Inspector in Schritt 4. Inspector 2.15.0 setzt Node
^22.23.4 || ^24.22.1 || >=26.12.1voraus. - Eine MCP-fähige App für Schritt 5 (optional).
uv unter macOS oder Linux installieren:
curl -LsSf https://astral.sh/uv/install.sh | sh
Unter Windows, in der PowerShell:
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
Starte dein Terminal danach neu, damit der Befehl uv gefunden wird.
In Zahlen
2.3.0verwendete Python-SDK-Version
2.15.0verwendete MCP-Inspector-Version
3.10Python-Mindestversion
Schritt 1: Das Projekt anlegen
uv init --bare handy-tools
cd handy-tools
uv add "mcp[cli]"
--bare legt nur eine pyproject.toml an, mehr braucht dieses Projekt nicht. Das Extra cli fügt das Kommandozeilen-Tool mcp hinzu. Prüfe die Installation:
uv run mcp version
Erwartete Ausgabe:
MCP version 2.3.0
Schritt 2: Den Server schreiben
Lege im Projektordner eine Datei namens server.py an:
from datetime import date
from mcp.server import MCPServer
from mcp.server.mcpserver.exceptions import ToolError
mcp = MCPServer("Handy Tools")
@mcp.tool()
def count_words(text: str) -> int:
"""Count the words in a piece of text."""
return len(text.split())
@mcp.tool()
def days_between(start: str, end: str) -> int:
"""Count the days from one date to another. Dates use YYYY-MM-DD format."""
try:
first = date.fromisoformat(start)
second = date.fromisoformat(end)
except ValueError:
raise ToolError("Dates must look like 2026-11-15 (YYYY-MM-DD).")
return (second - first).days
if __name__ == "__main__":
mcp.run()
Was die einzelnen Teile tun:
MCPServer("Handy Tools")erstellt den Server. In SDK 2.x importierst du ihn ausmcp.server.@mcp.tool()macht aus einer Funktion ein Tool. Das SDK liest den Namen des Tools aus dem Funktionsnamen, die Beschreibung aus dem Docstring und das Eingabeschema aus den Type Hints. Du schreibst kein JSON.ToolErrorschickt eine verständliche Meldung an das Modell zurück, damit es seine Argumente korrigieren und es noch einmal versuchen kann.mcp.run()ohne Argumente startet den Server über stdio: Der Host startet deine Datei als Unterprozess und kommuniziert mit ihr über stdin und stdout.

Schritt 3: Aus Python heraus testen
Das SDK enthält eine Klasse Client, die sich im Speicher mit deinem Server-Objekt verbinden kann, ohne Unterprozess, ohne Port und ohne KI. Lege check.py neben server.py an:
import asyncio
from mcp import Client
from server import mcp
async def main() -> None:
async with Client(mcp) as client:
tools = await client.list_tools()
print([tool.name for tool in tools.tools])
result = await client.call_tool("count_words", {"text": "the quick brown fox"})
print(result.structured_content)
result = await client.call_tool("days_between", {"start": "2026-11-15", "end": "2027-01-01"})
print(result.structured_content)
result = await client.call_tool("days_between", {"start": "tomorrow", "end": "2027-01-01"})
print(result.is_error, result.content[0].text)
asyncio.run(main())
Führ es aus:
uv run check.py
Erwartete Ausgabe:
['count_words', 'days_between']
{'result': 4}
{'result': 47}
True Error executing tool days_between: Dates must look like 2026-11-15 (YYYY-MM-DD).
Außerdem siehst du eine INFO-Logzeile zum fehlgeschlagenen Aufruf: Das ist der Server, der den ToolError protokolliert. Beachte, dass das ungültige Datum im Client keine Exception ausgelöst hat: Ein fehlgeschlagener Tool-Aufruf kommt als normales Ergebnis zurück, bei dem is_error auf True gesetzt ist.
Schon gewusst?
Ein fehlgeschlagener Tool-Aufruf löst im Client keine Exception aus. Er kommt als normales Ergebnis zurück, bei dem is_error auf True gesetzt ist, und enthält die Meldung des ToolError.
Schritt 4: Mit dem MCP Inspector prüfen
Der MCP Inspector ist das hauseigene Testwerkzeug des MCP-Projekts. Im CLI-Modus startet er deinen Server so, wie es ein echter Host tun würde, und gibt aus, was zurückkommt. Im Projektordner:
npx @modelcontextprotocol/inspector --cli uv run server.py --method tools/list
Beim ersten Start wirst du gefragt, ob das Paket heruntergeladen werden darf. Danach solltest du JSON sehen, das count_words und days_between auflistet, jeweils mit dem Eingabeschema, das das SDK aus deinen Type Hints erzeugt hat.
Jetzt ruf ein Tool auf:
npx @modelcontextprotocol/inspector --cli uv run server.py \
--method tools/call --tool-name days_between \
--tool-args-json '{"start":"2026-11-15","end":"2027-01-01"}'
Erwartete Ausgabe:
{
"content": [
{
"type": "text",
"text": "47"
}
],
"structuredContent": {
"result": 47
},
"isError": false
}
Das SDK kann auch die Weboberfläche des Inspectors starten:
uv run mcp dev server.py
Es gibt eine lokale Adresse wie http://127.0.0.1:6274?MCP_INSPECTOR_API_TOKEN=... aus und öffnet sie in deinem Browser. Schalte auf dem Bildschirm „Servers“ den Verbindungsschalter neben deinem Server ein, öffne Tools, wähle count_words, gib etwas Text ein und klick auf Execute Tool (Tool ausführen). Drück Strg+C im Terminal, wenn du fertig bist.
Schritt 5: Mit einer KI-App verbinden
Einen Host anzubinden heißt, ihm den Befehl mitzuteilen, der deinen Server startet. Für dieses Projekt lautet er:
uv --directory /ABSOLUTE/PATH/TO/handy-tools run server.py
Führ pwd im Projektordner aus, um den echten Pfad zu bekommen. Probier den Befehl zuerst selbst aus. Es wird nichts ausgegeben und er kehrt nicht zurück, und das ist richtig so: Der Server wartet darauf, dass ein Host mit ihm spricht. Drück Strg+C, um ihn zu beenden.
Viele Apps akzeptieren für diesen Befehl denselben JSON-Block:
{
"mcpServers": {
"handy-tools": {
"command": "uv",
"args": ["--directory", "/ABSOLUTE/PATH/TO/handy-tools", "run", "server.py"]
}
}
}
Wohin er gehört, hängt von der App ab:
- Cursor: Speichere ihn laut der MCP-Dokumentation von Cursor als
.cursor/mcp.jsonin einem Projekt oder als~/.cursor/mcp.json, um ihn überall zu nutzen. Diese Doku nennt für lokale Server außerdem ein Feld"type": "stdio", auch wenn ihre eigenen Beispiele es weglassen. - VS Code: Führ laut der VS-Code-Dokumentation in der Befehlspalette MCP: Add Server aus, wähle Command (stdio) und gib den Startbefehl ein.
- Claude Desktop: Führ
uv run mcp install server.pyaus, das schreibt den Eintrag für dich. Es ist der einzige Host, den das SDK automatisch konfiguriert.
Starte die App neu und frag dann zum Beispiel:
Use the days_between tool: how many days from 2026-11-15 to 2027-01-01?
Die Antwort sollte 47 lauten. Denk daran, dass Tools auf deinem Computer mit den Rechten deines Benutzerkontos laufen, gib also nur Aktionen frei, bei denen es für dich okay ist, dass ein Modell sie auslöst. Ein Beispiel für einen größeren, fertigen Server findest du in unserer Anleitung zu Chrome DevTools MCP.

Häufige Fehler und Lösungen
ModuleNotFoundError: No module named 'mcp.server.fastmcp': Der Code wurde für SDK 1.x geschrieben. In 2.x heißt die KlasseMCPServerund wird mitfrom mcp.server import MCPServerimportiert. Passe den Import an oder pinnemcp<2, um alten Code weiter auszuführen.TypeError: The @tool decorator was used incorrectly: Du hast@mcp.toolohne Klammern geschrieben. Verwende@mcp.tool().- Die App zeigt deinen Server nicht an: Meist liegt es an einem relativen Pfad. Verwende den absoluten Pfad zum Projekt, und wenn die App
uvnicht findet, ersetzeuvdurch den vollständigen Pfad auswhich uv(macOS und Linux) oderwhere uv(Windows). Beende die App vollständig und öffne sie neu, nachdem du ihre Konfiguration bearbeitet hast. - Die Verbindung bricht ab oder die Tool-Liste ist leer: Über stdio transportiert stdout das Protokoll selbst. Ein verirrtes
print()kann es beschädigen. Nutze das Python-Modullogging, das nach stderr schreibt. npm warn deprecated @modelcontextprotocol/inspector@0.15.0: v1 is deprecatedoder ein Tool-Aufruf scheitert mitField required: Dein Node.js ist zu alt für Inspector 2.x. In einem Test mit Node 20 hatnpxstillschweigend das alte Release 0.15.0 installiert, das--tool-args-jsonignoriert. Prüfenode --versionund aktualisiere auf eine unterstützte Version.npx not foundbeim Ausführen vonmcp dev: Der Inspector ist eine Node.js-App. Installiere zuerst Node.js.Error executing tool <name>ohne Meldung: Das Tool ist mit einer Exception abgestürzt, die du nicht eingeplant hattest. Den Traceback findest du im Log des Servers, nicht im Ergebnis.
Schon gewusst?
Über stdio transportiert stdout das Protokoll selbst, deshalb kann ein verirrtes print() in deinem Server die Verbindung beschädigen. Das Python-Modul logging schreibt stattdessen nach stderr.
Fazit
Ein funktionierender MCP-Server ist eine Python-Datei mit ein paar dekorierten Funktionen. Schreib das Tool, prüf es im Speicher mit Client(mcp), bestätige es über stdio mit dem Inspector und gib dann einem beliebigen Host den Startbefehl. Von hier aus kannst du Resources und Prompts ergänzen oder denselben Code mit mcp.run(transport="streamable-http") über HTTP bereitstellen. Wenn dein Agent eher schriftliche Anweisungen als neue Funktionen braucht, deckt unsere Anleitung zu Agent Skills in Claude Code diese Seite ab.
Häufig gestellte Fragen
Was ist der Unterschied zwischen MCP-Host, -Client und -Server?
Der Host ist die KI-App, mit der du sprichst, etwa ein Chat-Assistent oder ein Code-Editor. Der Client steckt im Host und spricht MCP. Der Server ist das, was du baust, und er kann Tools, Resources und Prompts anbieten.
Warum bekomme ich „No module named mcp.server.fastmcp“?
Dieser Code wurde für SDK 1.x geschrieben. In 2.x heißt die Klasse MCPServer und wird mit from mcp.server import MCPServer importiert. Passe den Import an oder pinne mcp<2, um alten Code weiter auszuführen.
Kann ich einen MCP-Server ohne KI-App testen?
Ja. Die Client-Klasse des SDK verbindet sich im Speicher mit deinem Server-Objekt, ohne Unterprozess, Port oder KI. Der CLI-Modus des MCP Inspector startet den Server danach über stdio, so wie es ein echter Host tun würde.
Welche Node.js-Version braucht der MCP Inspector?
Inspector 2.15.0 setzt Node ^22.23.4, ^24.22.1 oder >=26.12.1 voraus. Mit älterem Node installiert npx unter Umständen stillschweigend das alte Release 0.15.0, das –tool-args-json ignoriert.
Kurzes Quiz
Welche Klasse erstellt in SDK 2.x einen MCP-Server?
- FastMCP
- ToolError
- MCPServer
SDK 2.x hat die zentrale Server-Klasse in MCPServer umbenannt; importiert wird sie aus mcp.server.
Was kann ein verirrtes print() bei einem stdio-MCP-Server anrichten?
- Den Protokollstrom beschädigen
- Nichts, die Ausgabe wird ignoriert
- Den Server neu starten
Über stdio transportiert stdout das Protokoll selbst, deshalb kann zusätzliche Ausgabe es beschädigen.
Woher bezieht das SDK das Eingabeschema eines Tools?
- Aus einer JSON-Datei, die du schreibst
- Aus den Type Hints der Funktion
- Aus der Konfigurationsdatei des Hosts
Das SDK liest das Eingabeschema aus den Type Hints, du schreibst also kein JSON.
Quellen
Links zuletzt geprüft am 15. November 2026.
- Build an MCP server (official tutorial)
- What is the Model Context Protocol?
- MCP Python SDK README, v2.3.0
- Python SDK: First steps
- Python SDK: Connect to a real host
- Python SDK: Testing
- Python SDK: Running your server
- Python SDK: Handling errors
- Python SDK: Troubleshooting
- mcp on PyPI
- MCP Inspector README, 2.15.0
- Inspector: smoke-testing an MCP server from the shell
- Installing uv
- uv: creating projects
- Cursor: Model Context Protocol
- VS Code: add and manage MCP servers





Kommentar schreiben