MCP-Server bauen: Schritt-für-Schritt-Anleitung in Python und TypeScript (2026)

Du kannst einen MCP-Server bauen, den Claude tatsächlich aufruft, in etwa 15 Minuten. Wir haben es auf Node 20 und Python 3.11 gestoppt: ein funktionierendes add-Tool, das über stdio läuft und von Claude Desktop erkannt wird, hat beim ersten Mal 14 Minuten gedauert und unter 5, sobald man die Struktur kennt. Diese Anleitung baut denselben Server zweimal, einmal in Python mit FastMCP 2.x, einmal in TypeScript mit @modelcontextprotocol/sdk 1.x, damit du deinen Stack wählen und echten Code kopieren kannst. Wenn du zuerst die Architektur und Protokolltheorie möchtest, findest du sie in unserem Leitfaden zum Model Context Protocol; hier bauen wir einfach.

MCP-Server Schnellstart: Was du baust

Ein MCP-Server ist ein kleines Programm, das Tools, Daten und Prompt-Vorlagen für KI-Clients wie Claude, Cursor oder VS Code über das Model Context Protocol bereitstellt. Du schreibst den Server einmal, und jeder MCP-kompatible Client kann ihn aufrufen. In dieser Anleitung baust du einen Server mit zwei Tools (einem add-Rechner und einem fetch_url-Helfer), lässt ihn lokal über stdio laufen, testest ihn und verbindest ihn mit einem echten Client.

Hier ist alles, was du vorher brauchst.

Beide Wege erzeugen einen Server mit identischem Verhalten. Wähle die Sprache, in der dein Team ohnehin arbeitet. Wenn du keine Präferenz hast, beginne mit Python, da FastMCP den ersten Server kürzer macht.

Was stellt ein MCP-Server eigentlich bereit?

Bevor du Code schreibst, hilft es zu wissen, welche drei Dinge ein Server anbieten kann. Ein MCP-Server stellt Tools (Funktionen, die das Modell aufrufen kann, etwa "durchsuche die Datenbank"), Resources (schreibgeschützte Daten, die das Modell laden kann, etwa eine Datei oder einen Datensatz) und Prompts (wiederverwendbare Prompt-Vorlagen) bereit. Die meisten Server, die du baust, sind tool-lastig; Resources und Prompts sind optional.

MCP-Server, definiert: ein Prozess, der das Model Context Protocol spricht und eine Liste von Tools, Resources und Prompts ankündigt, die ein KI-Client zur Laufzeit erkennen und aufrufen kann.

Der Client (zum Beispiel Claude Desktop) fungiert als Host. Er startet deinen Server oder verbindet sich mit ihm, fragt "welche Tools hast du?" und ruft sie dann auf, wenn das Modell entscheidet, dass ein Tool nützlich ist. Du rufst das Modell niemals aus dem Server heraus auf. Der Ablauf läuft in die andere Richtung.

Diese Richtung ist wichtig. Dein Server ist ein passiver Anbieter. Er wartet darauf, dass der Client sich verbindet, beantwortet die Erkennungsanfrage und führt das aufgerufene Tool aus. Behalte dieses mentale Modell im Kopf, und der Rest dieser Anleitung erschließt sich von selbst.

Wie man einen MCP-Server in Python baut (Schritt für Schritt)

Python ist der schnellste Weg zu einem laufenden Server, weil FastMCP die Protokoll-Verkabelung übernimmt und einfache Funktionen mit einem Decorator in Tools verwandelt. Alles unten nutzt das offizielle Python-SDK. Hier sind die vier Schritte.

Schritt 1: Projekt einrichten. Nutze uv, das inzwischen Standard für MCP-Python-Projekte ist:

uv init mcp-demo
cd mcp-demo
uv add "mcp[cli]"

Wenn du pip bevorzugst: python -m venv .venv && source .venv/bin/activate && pip install "mcp[cli]".

Schritt 2: Server schreiben. Erstelle server.py:

from mcp.server.fastmcp import FastMCP
import httpx

# Name shows up in the client's tool list
mcp = FastMCP("demo-server")

@mcp.tool()
def add(a: int, b: int) -> int:
    """Add two numbers and return the sum."""
    return a + b

@mcp.tool()
async def fetch_url(url: str) -> str:
    """Fetch a URL and return the first 2000 characters of the body."""
    async with httpx.AsyncClient(timeout=10) as client:
        resp = await client.get(url)
        return resp.text[:2000]

if __name__ == "__main__":
    mcp.run()  # defaults to stdio transport

Zwei Dinge sind zu beachten. Der Docstring wird zur Tool-Beschreibung, die das Modell liest, also schreibe ihn wie eine Anweisung. Und die Typ-Hinweise (a: int) werden automatisch zum Eingabeschema, sodass FastMCP das JSON-Schema für dich generiert.

Schritt 3: Ausführen. mcp.run() startet den Server über stdio, den Transport, den Clients lokal starten. Du führst das während der Entwicklung nicht direkt aus; der Client startet es. Für einen schnellen Test nutze den Dev-Runner:

uv run mcp dev server.py

Schritt 4: Saubere Ausgabe zurückgeben. Ein Stolperstein, der jetzt schon wichtig ist: gib einen String oder einen typisierten Wert zurück, kein verschachteltes Dict in der Hoffnung, dass es gerendert wird. Wir kommen im Produktionsteil darauf zurück, aber kurz gesagt können mehrdeutige Rückgabetypen in manchen Clients stillschweigend abgeschnitten werden.

Das ist ein vollständiger Python-MCP-Server. Zwei Tools, echte Netzwerkaufrufe, automatisches Schema. Als Nächstes dasselbe in TypeScript.

Wie man einen MCP-Server in TypeScript baut (Schritt für Schritt)

Der TypeScript-Weg nutzt das offizielle TypeScript-SDK direkt und zod für die Eingabevalidierung. Er ist etwas ausführlicher als FastMCP, aber die Typen sind exzellent und er lässt sich sauber auf Node-Hosts deployen.

Schritt 1: Projekt einrichten.

mkdir mcp-demo && cd mcp-demo
npm init -y
npm install @modelcontextprotocol/sdk zod
npm install -D typescript @types/node tsx

Schritt 2: Server schreiben. Erstelle server.ts:

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

const server = new McpServer({ name: "demo-server", version: "1.0.0" });

server.tool(
  "add",
  "Add two numbers and return the sum.",
  { a: z.number(), b: z.number() },
  async ({ a, b }) => ({
    content: [{ type: "text", text: String(a + b) }],
  }),
);

server.tool(
  "fetch_url",
  "Fetch a URL and return the first 2000 characters.",
  { url: z.string().url() },
  async ({ url }) => {
    const resp = await fetch(url);
    const body = await resp.text();
    return { content: [{ type: "text", text: body.slice(0, 2000) }] };
  },
);

const transport = new StdioServerTransport();
await server.connect(transport);

Schritt 3: Ausführen. Während der Entwicklung: npx tsx server.ts. Für die Produktion mit tsc kompilieren und die gebaute .js mit Node ausführen. Beachte die Rückgabeform: jedes Tool gibt { content: [{ type: "text", text: ... }] } zurück. Dieses explizite content-Array ist das TypeScript-Äquivalent zur Regel "gib einen sauberen String zurück" aus Python. Das SDK will typisierte Content-Blöcke, keine rohen Objekte.

Schritt 4: Eingaben mit zod validieren. Das Schema z.string().url() weist ungültige Eingaben ab, bevor dein Handler läuft, was genau das ist, was du willst, wenn ein Modell die Argumente generiert.

Dieselben zwei Tools, dasselbe Verhalten, idiomatisches TypeScript. Entscheiden wir jetzt, wie Clients deinen Server erreichen sollen.

stdio vs. Streamable HTTP: Welchen Transport solltest du nutzen?

MCP-Server kommunizieren über einen von zwei Transporten. stdio lässt den Server als lokalen Subprozess laufen, den der Client startet und über Standard-Ein-/Ausgabe anspricht. Streamable HTTP lässt den Server als Netzwerkdienst laufen, mit dem sich Clients über HTTP verbinden. Wähle danach, wo der Server leben muss.

Die Faustregel: baue und teste auf stdio, wechsle erst dann zu Streamable HTTP, wenn mehr als eine Person oder Maschine den Server braucht. Die meisten Server müssen stdio nie verlassen. Die obigen Aufrufe mcp.run() und StdioServerTransport() sind bereits stdio, also bist du für die Entwicklung startklar.

Wie man seinen MCP-Server mit dem Inspector testet

Bevor du deinen Server in Claude einbindest, teste ihn isoliert mit dem MCP Inspector. Es ist eine Browser-Oberfläche, die sich mit deinem Server verbindet, seine Tools auflistet und dich diese manuell aufrufen lässt. Führe ihn gegen deinen Server aus:

# Python
npx @modelcontextprotocol/inspector uv run server.py
# TypeScript
npx @modelcontextprotocol/inspector npx tsx server.ts

Der Inspector öffnet eine lokale Seite, auf der du deine Tools add und fetch_url sehen, einen Testaufruf abfeuern und die rohe Antwort lesen kannst. Das ist die beste Gewohnheit für die MCP-Entwicklung. Wenn das Schema eines Tools fehlerhaft oder ein Rückgabewert falsch ist, siehst du es hier in Sekunden statt vor einem stillen Fehler in Claude zu sitzen. Wir haben so ein fehlerhaftes Eingabeschema gefunden, das uns sonst eine volle Debugging-Runde durch den Client gekostet hätte. Teste jedes Mal zuerst im Inspector.

Wie man seinen MCP-Server mit Claude Desktop, Claude Code und Cursor verbindet

Sobald der Inspector zufrieden ist, richte einen echten Client auf deinen Server. Jeder Client liest eine Konfigurationsdatei, die ihm sagt, wie er deinen Server über stdio startet.

Claude Desktop. Bearbeite claude_desktop_config.json (auf macOS: ~/Library/Application Support/Claude/claude_desktop_config.json):

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

Starte Claude Desktop neu, und deine Tools erscheinen unter dem Connectors-Symbol.

Claude Code. Füge den Server mit einem Befehl aus deinem Projekt hinzu: claude mcp add demo-server -- uv run server.py. Claude Code speichert ihn in deiner Projektkonfiguration und lädt ihn beim Start. Wenn du auch Hooks nutzt, um Claude Code zu skripten, passt unser Leitfaden zu Claude Code Hooks gut zu eigenen MCP-Tools.

Cursor. Füge denselben mcpServers-Block zu .cursor/mcp.json im Projektstammverzeichnis hinzu. Die Form entspricht der von Claude Desktop. Für ein reales Beispiel eines MCP-Servers in Claude Code siehe, wie wir Higgsfield in Claude Code eingebunden haben.

Nutze in jeder Konfiguration absolute Pfade. Relative Pfade sind der häufigste Grund, warum ein Server nicht startet.

Einen MCP-Server in die Produktion deployen (Auth und Hosting)

Wenn dein Server geteilt werden muss, verschiebe ihn von stdio zu Streamable HTTP und füge drei Dinge hinzu: Authentifizierung, Fehlerbehandlung und einen Host.

• Authentifizierung. Remote-MCP-Server müssen OAuth 2.1 gemäß der MCP-Autorisierungsspezifikation nutzen. Für interne Tools ist eine Bearer-Token-Prüfung am HTTP-Endpunkt das pragmatische Minimum. Liefere niemals einen öffentlichen, nicht authentifizierten Tool-Server aus, denn ein Tool, das SQL ausführt oder interne APIs trifft, ist eine aktive Angriffsfläche.
• Fehlerbehandlung. Umschließe Tool-Körper mit try/except (oder try/catch) und gib eine typisierte Fehlermeldung zurück, statt zu werfen. Das Modell verarbeitet "die Abfrage ist fehlgeschlagen, hier der Grund" weit besser als eine abgebrochene Verbindung.
• Hosting. Jede Plattform, die einen langlebigen Node- oder Python-Prozess ausführt, funktioniert: ein kleiner VPS, Fly.io, Railway oder ein Container auf deiner eigenen Infrastruktur. Halte den Prozess warm, da Kaltstarts dem ersten Tool-Aufruf Latenz hinzufügen.
• Nebenläufigkeit und Kosten. Wenn deine Tools nachgelagert ein LLM oder eine bezahlte API aufrufen, setze ein Gateway davor. Unsere Übersicht der LLM-Gateway-Tools behandelt Rate-Limiting und Fallback, und Context-Engineering-Tools helfen, Tool-Ausgaben aus dem Kontextfenster des Modells herauszuhalten.

Für Python ändere den Run-Aufruf zu mcp.run(transport="streamable-http"); für TypeScript tausche StdioServerTransport gegen den StreamableHTTPServerTransport des SDK. Die Tool-Definitionen ändern sich gar nicht. Das ist der Sinn der Transport-Abstraktion.

Was wir beim Ausliefern von MCP-Servern in der Produktion gelernt haben

Wir haben bei Techsy MCP-Server für den internen Einsatz gebaut, und einige Lektionen zeigen sich erst, wenn echter Traffic darauf trifft. Hier ist, was wir gemessen haben und wo wir gebissen wurden.

Der erste Server, den wir ausgeliefert haben, war ein nur-lesendes Postgres-Abfrage-Tool, gebaut mit FastMCP 2.x auf dem Python-mcp-SDK 1.x, später in @modelcontextprotocol/sdk 1.x neu geschrieben, um zu vergleichen. Auf einem Stack von 2026 (Node 20, Python 3.11) fügten lokale stdio-Tool-Aufrufe etwa 8 bis 12 ms Transport-Overhead pro Aufruf hinzu. Als wir denselben Server zu Streamable HTTP auf einem VPS verschoben, stiegen die Kosten pro Aufruf auf 40 bis 70 ms, fast ausschließlich Netzwerk-Roundtrip statt Protokollkosten. Der FastMCP-Kaltstart lag bei etwa 300 ms für den Prozess, weshalb wir den Produktionsprozess warm halten.

Der Stolperstein, der uns etwa zwei Stunden kostete: ein Tool, das ein rohes Python-Dict zurückgab, wurde im Inspector gut gerendert, kam aber in Claude Desktop abgeschnitten zurück. Den Rückgabewert als typisierten Text-String zu umschließen, behob es sofort. Deshalb gibt diese Anleitung überall Strings und content-Text-Blöcke zurück statt verschachtelter Objekte. Die andere Gewohnheit, die sich sofort auszahlte, war, jeden Server durch npx @modelcontextprotocol/inspector laufen zu lassen, bevor man eine Client-Konfiguration anfasst, was ein fehlerhaftes Eingabeschema im TypeScript-Rewrite aufdeckte, das sonst still in Cursor fehlgeschlagen wäre.

Wenn du auswählst, welche Tools du überhaupt in Server bauen sollst, ist unsere Liste der besten MCP-Server 2026 ein guter Ideen-Speicher.

Wie Techsy MCP-Entwicklung angeht

Bei Techsy bauen wir MCP-Server als Teil der KI-Agentensysteme, die wir für Kunden ausliefern, indem wir Agenten über eine typisierte Tool-Schicht mit internen Datenbanken, CRMs und APIs verbinden. Unser Ansatz ist, eng zu beginnen (ein gut getestetes Tool über stdio), es im Inspector zu validieren und es erst dann zu einem authentifizierten HTTP-Dienst zu befördern, wenn mehr als ein Agent es braucht. Wir kombinieren eigene Server mit dem Claude Agent SDK, wenn die Agentenlogik komplex wird.

Das ist die ehrliche Version: Die meisten Teams überbauen ihren ersten Server. Du brauchst selten HTTP, OAuth und ein Dutzend Tools am ersten Tag. Wenn du ein zweites Paar Augen auf eine MCP-Integration möchtest, hol dir eine kostenlose Beratung, und wir sagen dir, ob es ein Ein-Tool-stdio-Job ist oder etwas, das wirklich Infrastruktur braucht.

Häufig gestellte Fragen

Soll ich meinen MCP-Server in Python oder TypeScript bauen?

Nutze die Sprache, in der dein Team ohnehin arbeitet. Python mit FastMCP ist der kürzeste Weg zu einem ersten laufenden Server, weil ein Decorator eine Funktion in ein Tool verwandelt. TypeScript mit dem offiziellen SDK ist etwas ausführlicher, gibt dir aber exzellente Typen und deployt sauber auf Node-Hosts. Beide erzeugen Server, die sich für den Client identisch verhalten.

Brauche ich ein Framework wie FastMCP, um einen MCP-Server zu bauen?

Nein, aber es hilft. FastMCP ist im offiziellen Python-mcp-SDK enthalten und entfernt den Großteil des Protokoll-Boilerplates. Du kannst die tiefere Server-API für feingranulare Kontrolle nutzen, aber für fast jeden Server ist FastMCP (Python) oder McpServer (TypeScript) das richtige Werkzeug und weit weniger Code.

Wie debugge ich einen MCP-Server, der nicht funktioniert?

Lass ihn zuerst durch den MCP Inspector laufen: npx @modelcontextprotocol/inspector gefolgt von deinem Run-Befehl. Der Inspector listet deine Tools auf und lässt dich sie direkt aufrufen, sodass du bestätigen kannst, dass der Server funktioniert, bevor du den Client beschuldigst. Wenn der Inspector in Ordnung ist, der Client aber nicht, prüfe, ob deine Konfiguration absolute Pfade nutzt und du den Client neu gestartet hast.

Ist FastMCP ein offizieller Teil von MCP?

Ja. FastMCP ist als hochrangige Server-Schnittstelle im offiziellen Model-Context-Protocol-Python-SDK gebündelt. Der @mcp.tool()-Decorator, den du nutzt, ist der empfohlene Weg, Python-Server zu bauen, kein Drittanbieter-Add-on.

Was ist der Unterschied zwischen einem lokalen und einem Remote-MCP-Server?

Ein lokaler Server läuft auf deiner Maschine über stdio, vom Client als Subprozess gestartet, am besten für persönliche Tools und Entwicklung. Ein Remote-Server läuft als Webdienst über Streamable HTTP und ist von mehreren Clients erreichbar, was OAuth-2.1-Authentifizierung erfordert. Baue zuerst lokal, geh nur remote, wenn du teilst.

In welchen Sprachen kann ich einen MCP-Server bauen?

Das Model Context Protocol hat offizielle SDKs für Python, TypeScript, Java, Kotlin und C#, mit Community-SDKs in weiteren Sprachen. Da MCP ein Wire-Protokoll ist, kann jede Sprache, die JSON-RPC über stdio oder HTTP lesen und schreiben kann, einen Server implementieren, aber die offiziellen SDKs ersparen dir diese Arbeit.

Funktioniert ein MCP-Server mit ChatGPT und Gemini oder nur mit Claude?

MCP ist ein offener Standard, der im gesamten agentischen KI-Ökosystem übernommen wird, einschließlich ChatGPT, Gemini, Cursor und VS Code Copilot. Ein einzelner Server, den du baust, funktioniert mit jedem kompatiblen Client. Du schreibst keine separate Integration pro Modell, was der ganze Sinn des Protokolls ist.

Wie lange dauert es, einen funktionierenden MCP-Server zu bauen?

Ein erster Server mit ein oder zwei Tools über stdio dauert etwa 15 Minuten, sobald deine Laufzeitumgebung installiert ist. Wir haben 14 Minuten für einen Erstanwender auf Node 20 und unter 5 Minuten für einen wiederholten Aufbau gemessen. Authentifizierung, HTTP-Transport und Produktions-Hosting sind das, was echte Zeit kostet, nicht der Server selbst.