Wie man seinen ersten MCP-Server baut: Ein Praxis-Leitfaden

Inhaltsverzeichnis

Aktualisiert Juni 2026.

TL;DR: MCP (Model Context Protocol) ist der Weg, Claude strukturierten Zugang zu externen Tools und Daten zu geben — Datenbanken, Dateien, APIs — ohne das Kontextfenster zu überladen. Der Server ist einfacher als er aussieht: SDK installieren, Tools als JSON-Schema definieren, Handler implementieren, via stdio verbinden. In unter 30 Minuten kann Claude deine benutzerdefinierten Tools aufrufen.

[Operator-Perspektive] Ich verbinde regelmäßig neue Tools mit meinen Agenten, und MCP ist jetzt der Standardweg, dies sauber zu tun. Sobald der Server gebaut ist, kann jeder kompatible Client — Claude Desktop, Claude Code, jede App mit dem Anthropic SDK — ihn ohne Änderungen am aufrufenden Code nutzen. Das ist der Wert: einmal bauen, überall wiederverwenden.

Was MCP eigentlich ist

Das Model Context Protocol ist ein offenes Protokoll, das standardisiert, wie KI-Modelle sich mit externem Kontext und Tools verbinden. Stell dir das als USB-C-Standard für KI-Integrationen vor: Vorher musste jede App, die Claude eine Datenbank lesen oder eine API aufrufen lassen wollte, ihre eigene Lösung erfinden. Danach baust du einen MCP-Server und jeder konforme Host kann ihn nutzen.

MCP definiert drei Dinge, die ein Server anbieten kann:

• Tools — Funktionen, die Claude aufrufen kann (Datei lesen, DB abfragen, Slack-Nachricht senden)
• Ressourcen — Daten, die Claude lesen kann (Dokumente, Datenbankzeilen, Dateistrukturen)
• Prompts — Wiederverwendbare Prompt-Templates, die der Host injizieren kann

Für die meisten Operator-Anwendungsfälle baut man Tool-Server. Ressourcen und Prompts kommen später, sobald die Grundlagen funktionieren.

Die Architektur ist Client-Server, wobei der Client (Claude Desktop, Claude Code, deine benutzerdefinierte App) alles kontrolliert. Der Server ist passiv — er hört nur auf Tool-Aufruf-Anfragen und gibt Ergebnisse zurück.

Die drei Teile jedes MCP-Servers

Jeder MCP-Server, den du baust, hat dieselbe Struktur:

1. Das Server-Objekt — deklariert den Namen, die Version und die Fähigkeiten deines Servers (Tools, Ressourcen, Prompts)
2. Tool-Definitionen — eine Liste von Tools mit Namen, Beschreibungen und JSON-Schemas für ihre Eingaben
3. Request-Handler — die Funktionen, die laufen, wenn Claude ein Tool aufruft

Das war’s. Keine Datenbank, kein HTTP-Stack, keine Auth-Schicht zum Starten erforderlich. Der minimale Server hat unter 30 Zeilen TypeScript.

Voraussetzungen (2 Minuten)

• Node.js 18+ — prüfe mit node --version
• TypeScript 5+ (unten als Dev-Dependency enthalten)
• Ein MCP-Client zum Testen — Claude Desktop ist kostenlos und der einfachste Weg, deinen Server in Aktion zu sehen

Es wird kein Anthropic-API-Key benötigt, um einen MCP-Server auszuführen. Der API-Key lebt im Client (Claude Desktop), nicht in deinem Server.

Schritt 1: Das Projekt einrichten (3 Minuten)

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

Füge zu package.json hinzu:

{
  "type": "module",
  "scripts": {
    "build": "tsc",
    "dev": "tsx src/index.ts"
  }
}

Erstelle tsconfig.json:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "Node16",
    "moduleResolution": "Node16",
    "outDir": "./build",
    "strict": true
  },
  "include": ["src/**/*"]
}

Schritt 2: Den minimalen Server schreiben (5 Minuten)

Erstelle src/index.ts:

import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import {
  CallToolRequestSchema,
  ListToolsRequestSchema,
} from "@modelcontextprotocol/sdk/types.js";

const server = new Server(
  { name: "my-mcp-server", version: "1.0.0" },
  { capabilities: { tools: {} } }
);

// Deklariert, welche Tools dieser Server anbietet
server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: [
    {
      name: "get_word_count",
      description: "Zählt die Wörter in einem Textblock.",
      inputSchema: {
        type: "object",
        properties: {
          text: {
            type: "string",
            description: "Der Text, in dem Wörter gezählt werden sollen",
          },
        },
        required: ["text"],
      },
    },
  ],
}));

// Bearbeitet Tool-Aufrufe vom Client
server.setRequestHandler(CallToolRequestSchema, async (request) => {
  const { name, arguments: args } = request.params;

  if (name === "get_word_count") {
    const { text } = args as { text: string };
    const count = text.trim().split(/\s+/).filter(Boolean).length;
    return {
      content: [{ type: "text", text: `Wortanzahl: ${count}` }],
    };
  }

  throw new Error(`Unbekanntes Tool: ${name}`);
});

// Über stdio verbinden — so kommuniziert Claude Desktop mit dem Server
const transport = new StdioServerTransport();
await server.connect(transport);

Das ist der vollständige Server. Er registriert ein Tool (get_word_count) und implementiert es. Die Struktur ist das Wesentliche.

Schritt 3: Bauen und in Claude Desktop registrieren (5 Minuten)

TypeScript kompilieren:

npm run build

Jetzt in der Config-Datei von Claude Desktop registrieren.

Auf macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Auf Windows: %APPDATA%\Claude\claude_desktop_config.json

Wenn die Datei nicht existiert, erstelle sie:

{
  "mcpServers": {
    "my-mcp-server": {
      "command": "node",
      "args": ["/absoluter/pfad/zu/my-mcp-server/build/index.js"]
    }
  }
}

Verwende den absoluten Pfad. Starte Claude Desktop nach dem Speichern neu. Du siehst ein Hammer-Symbol (🔨) in der Nachrichteneingabe — das bedeutet, Claude hat deine Tools entdeckt.

Schritt 4: Ein nützliches Tool bauen

Das Wortzählen ist zur Veranschaulichung. Hier ein nützlicheres Tool: Dateien aus einem Projektverzeichnis lesen — was ich für Kontext-Injektions-Agenten nutze, die Codebasen, Changelogs oder Config-Dateien zusammenfassen.

import { readFileSync, readdirSync } from "fs";
import { join, extname } from "path";

const ALLOWED_EXTENSIONS = [".md", ".txt", ".ts", ".json", ".yaml"];
const PROJECT_DIR = process.env.PROJECT_DIR ?? process.cwd();

Die Logik ist dieselbe: Tools mit präzisen JSON-Schemas definieren, Handler implementieren, Eingaben validieren, um Path-Traversal zu verhindern, und Text an den Client zurückgeben.

Fehler, die ich gemacht habe (damit du sie nicht machst)

Der Pfad muss absolut sein. Relative Pfade in der Claude Desktop-Config lösen sich nicht so auf, wie man es erwartet. Verwende immer den vollständigen Pfad /home/benutzer/....

Stdio bedeutet kein console.log in deinem Server. Claude Desktop kommuniziert mit deinem Server über stdin/stdout. Ein console.log für Debugging korrumpiert den JSON-RPC-Stream. Logge stattdessen nach stderr:

process.stderr.write(`Debug: ${message}\n`);

Claude Desktop nach jeder Config-Änderung neu starten. MCP-Server werden beim Start geladen. Eine bearbeitete Config-Datei tut nichts, bis du die App schließt und wieder öffnest.

Tool-Beschreibungen sind das Produkt. Claude entscheidet, ob es dein Tool aufruft, basierend auf dem description-Feld. Eine vage Beschreibung bedeutet, dass Claude nicht weiß, wann es das Tool verwenden soll. Eine präzise Beschreibung bedeutet, dass Claude im richtigen Moment darauf zurückgreift. Investiere mehr Zeit in Beschreibungen als in die Implementierung.

Wie ich MCP-Server in der Produktion verwende

Das stdio-Muster funktioniert hervorragend für Claude Desktop und Claude Code (lokal). Für Produktions-Agenten — die 30+, die ich auf Cloudflare Workers betreibe — verwende ich die Tool-Use-API des Anthropic SDK direkt, da ich die Flexibilität benötige, pro Schritt zu Haiku vs Sonnet zu routen.

Muster, die ich tatsächlich einsetze:

1. Lokales Dev-Tooling — MCP-Server für Claude Code, die projektspezifische Tools exponieren
2. Kontext-Injektion — MCP-Server, die relevante Docs vorladen, ohne manuell zu kopieren
3. Prototyp-zu-API-Brücke — ich baue zuerst MCP (schneller zu iterieren), dann portiere ich die Logik zur SDK Tool-Use für Produktion

Was als nächstes bauen

Sobald die Server-Struktur klar ist, sind die nützlichen Tools diejenigen, die auf Claudes externen Kontext zugreifen:

• Datenbankleser — führt eine schreibgeschützte SQL-Abfrage aus und gibt Ergebnisse als JSON zurück
• Slack-Leser — ruft die letzten N Nachrichten eines Channels ab
• GitHub-Leser — listet offene PRs auf, liest eine Datei bei einem bestimmten Commit
• Interner API-Wrapper — ruft deine eigene REST-API mit eingebauten Auth-Headern auf

Häufige Fragen

Benötige ich einen Anthropic API-Key, um einen MCP-Server zu bauen?

Nein. Dein MCP-Server ruft die Anthropic API nicht auf. Er antwortet nur auf Tool-Aufruf-Anfragen vom Client. Der API-Key lebt im Client, nicht im Server.

Kann mein MCP-Server externe APIs aufrufen?

Ja — der Handler ist nur asynchroner TypeScript-Code. Eine Wetter-API abrufen, eine Datenbank abfragen, in eine Datei schreiben. Dem Server ist es egal, was der Handler intern tut.

Was ist der Unterschied zwischen stdio- und HTTP-Transport?

Stdio ist für lokale Server — gleiche Maschine wie Claude Desktop oder Claude Code. HTTP mit SSE ist für Remote-Server, die du als Webservice deployen kannst. Beginne mit stdio; es ist einfacher zu debuggen.

Wie weiß Claude, wann es mein Tool aufrufen soll?

Claude entscheidet basierend auf dem description-Feld des Tools und dem Konversationskontext. Wenn Claude dein Tool weiterhin ignoriert, verfeinere die Beschreibung.