Dein erster MCP-Server in 90 Minuten

MCP-Server sind das eine Ding, das Deinen Claude oder Codex aus "Chatbot mit Wissen" zu "verlängerter Arm auf mein System" macht. Die meisten Einsteiger-Tutorials versuchen Dir zuerst das Protokoll zu erklären. Das führt dazu dass niemand jemals einen baut. Hier gehts umgekehrt: wir bauen etwas, es funktioniert, dann verstehst Du warum.

Wenn Du das hier komplett durchziehst, hast Du in 90 Minuten einen eigenen MCP-Server der eine konkrete Aufgabe macht (Dateien in einem Ordner zusammenfassen), den Du in Claude Desktop eingebunden hast und der auf Deinem Rechner läuft. Das ist die Basis für alles was in Level 6 dann komplexer wird.

1. Voraussetzungen klären

Du brauchst: Node.js 20 oder neuer (node --version in einem Terminal), einen Texteditor (VS Code, Sublime, was Du hast), und Claude Desktop installiert (claude.ai/download). Das ist alles. Kein Cloud-Account, kein Docker, kein TypeScript-Vorwissen nötig.

Ein Tipp: Wenn Du Node noch nie installiert hast, nimm nvm oder den Installer von nodejs.org. Nicht „brew install node" wenn Du später noch Node-Versionen wechseln willst, das führt sonst zu Versions-Chaos.

2. Projekt-Ordner anlegen

Leg irgendwo einen neuen Ordner an, zum Beispiel ~/code/mein-erster-mcp. In dem Ordner:

npm init -y
npm install @modelcontextprotocol/sdk

Das installiert das offizielle SDK von Anthropic. Mehr brauchst Du nicht.

Ein Tipp: Wenn Du den Ordner-Pfad aufschreibst, schreib ihn absolut (mit /Users/DeinName/... auf Mac oder C:\Users\DeinName\... auf Windows). Claude Desktop braucht das später absolut, nicht relativ.

3. Die Server-Datei schreiben

Leg eine Datei server.js im Projekt-Ordner an. Hier der komplette Inhalt:

import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { readdir, readFile } from "node:fs/promises";
import { join } from "node:path";

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

server.setRequestHandler("tools/list", async () => ({
  tools: [
    {
      name: "folder_summary",
      description: "Zaehlt Dateien in einem Ordner und zeigt die ersten Zeilen jeder Datei",
      inputSchema: {
        type: "object",
        properties: {
          path: { type: "string", description: "Absoluter Pfad zum Ordner" }
        },
        required: ["path"]
      }
    }
  ]
}));

server.setRequestHandler("tools/call", async (request) => {
  if (request.params.name !== "folder_summary") {
    throw new Error("Unbekanntes Tool");
  }
  const path = request.params.arguments.path;
  const files = await readdir(path);
  const summaries = await Promise.all(
    files.slice(0, 10).map(async (file) => {
      try {
        const content = await readFile(join(path, file), "utf8");
        const firstLines = content.split("\n").slice(0, 3).join("\n");
        return `## ${file}\n${firstLines}`;
      } catch {
        return `## ${file}\n(kann nicht gelesen werden)`;
      }
    })
  );
  return {
    content: [
      { type: "text", text: `Ordner: ${path}\nDateien: ${files.length}\n\n${summaries.join("\n\n")}` }
    ]
  };
});

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

Das ist ein kompletter MCP-Server. Er kann eine einzige Sache: einen Ordner-Pfad nehmen, die Dateien auflisten, und die ersten drei Zeilen jeder Datei zeigen.

Ein Tipp: Kopier das 1:1 rein. Keine Änderungen beim ersten Mal. Wenn es läuft, verstehst Du was jede Zeile tut und kannst Dinge hinzufügen.

4. Package.json ergänzen

Öffne die package.json die npm init erzeugt hat. Füge ganz oben bei der JSON-Struktur die Zeile "type": "module" ein, damit die import-Statements funktionieren. Das sollte dann etwa so aussehen:

{
  "name": "mein-erster-mcp",
  "version": "1.0.0",
  "type": "module",
  "main": "server.js",
  "dependencies": {
    "@modelcontextprotocol/sdk": "^1.0.0"
  }
}

Ein Tipp: Wenn Du später JSON-Fehler siehst, liegt es oft an einem fehlenden Komma. Ein Online-JSON-Validator spart fünf Minuten Rätseln.

5. Lokalen Test

Bevor wir Claude anbinden, prüfen wir ob der Server überhaupt startet. Terminal auf im Projekt-Ordner:

node server.js

Wenn nichts passiert und der Cursor einfach blinkt: gut. MCP-Server warten auf Input über stdin. Drück Ctrl+C zum Abbrechen. Wenn eine Fehlermeldung kommt, lies sie — meistens ist es eine fehlende Import-Zeile oder ein Typo.

Ein Tipp: Fehlermeldungen von Node sind oft lang, aber die erste Zeile ist die wichtige. Die anderen sind nur der Stack-Trace der Dir sagt wo genau es passiert ist.

6. Claude Desktop finden lassen

Jetzt das eigentliche Anbinden. Öffne Claude Desktop, geh in die Einstellungen, dann "Developer", dann "Edit Config". Das öffnet eine Datei claude_desktop_config.json. Füge den Server hinzu, sodass die Datei etwa so aussieht:

{
  "mcpServers": {
    "mein-erster-mcp": {
      "command": "node",
      "args": ["/Users/DeinName/code/mein-erster-mcp/server.js"]
    }
  }
}

Den Pfad musst Du auf Deinen eigenen anpassen. Absolut, nicht relativ. Datei speichern, Claude Desktop komplett beenden (nicht nur Fenster zu, Cmd+Q auf Mac, Rechtsklick → Beenden auf Windows), neu starten.

Ein Tipp: Wenn Claude den Server nicht findet, liegt das zu 90 Prozent am Pfad. Kopier ihn aus dem Terminal mit pwd im Projekt-Ordner, dann weisst Du dass er stimmt.

7. Erster echter Aufruf in Claude

Öffne in Claude Desktop einen neuen Chat. Frag etwas wie: „Kannst Du mir zusammenfassen was in meinem Ordner /Users/DeinName/Documents/notizen liegt?" (Pfad auf einen echten Ordner bei Dir anpassen.) Claude sollte erkennen dass folder_summary das richtige Tool ist und es aufrufen.

Du siehst in Claude ein kleines Tool-Call-Icon, kurzen Status, dann das Ergebnis. Wenn das funktioniert, hast Du gerade Deinen ersten MCP-Server in Produktion.

Ein Tipp: Das erste Mal fühlt sich das wie Magie an. Das ist normal. Du hast gerade Claude ein neues Fähigkeit gegeben, die OpenAI und Anthropic selbst nicht ausliefern.

8. Was kaputt gehen kann und wie Du es repariert

Die üblichen Fehler: Pfad in der Config falsch, Node-Version zu alt, Claude Desktop nicht neu gestartet nach Config-Änderung, Datei-Berechtigungen auf dem Ordner den Du zusammenfassen willst. Claude Desktop hat eine Log-Datei, sie liegt auf Mac unter ~/Library/Logs/Claude/mcp*.log und zeigt Dir was der Server beim Start sagt.

Ein Tipp: Wenn was nicht geht, erste Frage: steht der Server überhaupt in der Config an der richtigen Stelle? Zweite Frage: siehst Du den Server im Claude Developer-Einstellungen-Tab? Wenn beides ja und es geht trotzdem nicht, liegt der Fehler im Code. Logs lesen, nicht raten.

9. Warum Du das jetzt verstehst

Du hast gerade ohne Protokoll-Theorie gelernt was ein MCP-Server wirklich ist: ein lokales Programm, das auf stdin wartet, JSON-Requests beantwortet, und Tools meldet die Claude aufrufen kann. Das ist die gesamte Spec in einem Satz.

Alles was in Produktions-Servern drum herum gebaut wird (OAuth, HTTP-Transport, Datenbank-Anbindung, TypeScript-Types, Tests, Logging, Error-Handling, Rate-Limiting) ist Deko über diesem Kern. Wenn Du den Kern verstanden hast, verstehst Du den Rest durch Lesen.

Ein Tipp: Bau keinen "schönen" Server als nächstes. Bau einen der für Dich eine echte Aufgabe löst. Ein MCP-Server der Deine Notion-Seite der Woche zusammenfasst. Einer der Deine letzten drei Kalendertermine liest. Einer der Deine lokalen Markdown-Notizen durchsucht. Der Wert von MCP ist was er Dir persönlich nützt, nicht wie professionell er aussieht.

10. Weiterbauen

Wenn Du nach diesen 90 Minuten einen laufenden Server hast, hast Du die Hürde überwunden die 95 Prozent aller Interessierten stoppt. Ab hier wirds einfach. Neue Tools dazu packen (tools/list erweitern, tools/call entsprechend), zweite Tool dazubauen. Tiefergehen in TypeScript und die SDK-Typen. Später einen HTTP-Server statt stdio damit andere ihn auch nutzen können. Noch später: OAuth damit Fremde sicher ran dürfen. Alles schrittweise, jedes für sich überschaubar.

Ein Tipp: Schreib Dir nach den 90 Minuten drei Tool-Ideen auf die Du als nächstes in Deinen Server einbauen willst. Das hält das Momentum. Wenn Du nur "ich muss mal wieder MCP machen" sagst, kommt es nie wieder.

Wie es weitergeht

Level 6 der Academy geht diesen Weg strukturell durch: eigenen Server planen, TypeScript-Skelett, Tool-Design, Deployment auf eigene Domain, Verkauf über Marketplaces. Wenn Du diesen 90-Minuten-Sprint hinter Dir hast, bist Du ready für Level 6.

Und wenn Du Dein Setup danach noch sauberer haben willst: Playbook „Memory portabel nutzen" zeigt wie Deine selbstgebauten Server parallel zu bestehenden Memory-Servern laufen, und wie alles zusammen in Claude, Codex und Cursor gleichzeitig verfügbar wird.

Für jetzt: Server läuft, Claude redet mit ihm. Das ist der Beweis. Alles andere ist nur noch mehr davon.