So baust du deinen ersten MCP-Server mit Python (und testest ihn ohne KI-App)

Schreib einen kleinen MCP-Server mit Python und zwei Tools, teste ihn ganz ohne KI-App, prüfe ihn mit dem MCP Inspector und verbinde ihn mit deinem Editor oder Assistenten.

Graphic of a small server box connected to a chat bubble and a code editor, for a guide to building an MCP server in Python

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.

Video: The Model Context Protocol (MCP) (Anthropic)

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.1 voraus.
  • Eine MCP-fähige App für Schritt 5 (optional).

uv unter macOS oder Linux installieren:

Terminal
curl -LsSf https://astral.sh/uv/install.sh | sh

Unter Windows, in der PowerShell:

Code
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

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

Terminal
uv run mcp version

Erwartete Ausgabe:

Code
MCP version 2.3.0

Schritt 2: Den Server schreiben

Lege im Projektordner eine Datei namens server.py an:

Code
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 aus mcp.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.
  • ToolError schickt 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.
Diagramm mit den Bestandteilen einer minimalen Python-MCP-Server-Datei und ihrer jeweiligen Aufgabe

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:

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

Terminal
uv run check.py

Erwartete Ausgabe:

Code
['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:

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

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

Code
{
  "content": [
    {
      "type": "text",
      "text": "47"
    }
  ],
  "structuredContent": {
    "result": 47
  },
  "isError": false
}

Das SDK kann auch die Weboberfläche des Inspectors starten:

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

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

Code
{
  "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.json in 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.py aus, 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:

Code
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.

Ablaufdiagramm: einen Python-MCP-Server bauen, testen, prüfen und mit einer KI-App verbinden

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 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.
  • TypeError: The @tool decorator was used incorrectly: Du hast @mcp.tool ohne 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 uv nicht findet, ersetze uv durch den vollständigen Pfad aus which uv (macOS und Linux) oder where 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-Modul logging, das nach stderr schreibt.
  • npm warn deprecated @modelcontextprotocol/inspector@0.15.0: v1 is deprecated oder ein Tool-Aufruf scheitert mit Field required: Dein Node.js ist zu alt für Inspector 2.x. In einem Test mit Node 20 hat npx stillschweigend das alte Release 0.15.0 installiert, das --tool-args-json ignoriert. Prüfe node --version und aktualisiere auf eine unterstützte Version.
  • npx not found beim Ausführen von mcp 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.

Von Mindloop Editorial

The Mindloop Experience editorial team writes clear, carefully sourced explainers and how-tos on tech, science, money and culture, for anyone who likes to know how things actually work.

Über Mindloop Experience

Kommentare

Kommentar schreiben

Mehr von Mindloop Experience

Alle Artikel von Mindloop Experience

Du kannst bis zu 50-mal applaudieren.