Zum Inhalt springen
Ömer Tiryaki (Startseite)
← Alle Notizen

Anleitunggeprüft

MCP-Server anbinden

Wie du Claude über das Model Context Protocol mit eigenen Daten und Werkzeugen verbindest, sicher und Schritt für Schritt.

Was MCP ist

MCP ist ein offener Standard, über den KI-Assistenten Werkzeuge und Daten nutzen. Ein MCP-Server stellt Funktionen bereit, zum Beispiel Dateien lesen, Mails suchen oder Aufgaben anlegen. Claude ruft sie auf, wenn sie zur Frage passen. Beteiligt sind drei Rollen: Der Host ist die KI-Anwendung, etwa Claude Code. Für jeden Server legt er einen eigenen Client an, der die Verbindung hält, und der Server ist das Programm mit den Werkzeugen. Ein Server kann drei Arten von Bausteinen anbieten:

  1. Tools: Funktionen, die etwas tun, zum Beispiel eine Datenbank abfragen oder eine API aufrufen.
  2. Resources: Daten zum Lesen, etwa ein Dateiinhalt oder das Schema einer Datenbank.
  3. Prompts: fertige Vorlagen für wiederkehrende Aufgaben.

Tipp:Ein einfaches Bild: MCP ist wie eine einheitliche Steckdose. Jedes Werkzeug mit dem passenden Stecker funktioniert in jeder Anwendung, die MCP spricht, ohne eigenes Kabel für jede Kombination.

Lokal oder entfernt: die Transporte

Der Transport legt fest, wie Client und Server ihre Nachrichten austauschen. Die Nachrichten selbst sind immer gleich, nämlich JSON-RPC 2.0. Bei stdio startet der Host den Server als Programm auf deinem Rechner und spricht über Standardeingabe und Standardausgabe mit ihm. Das ist schnell und braucht kein Netzwerk. Bei Streamable HTTP läuft der Server irgendwo im Netz, ist über eine URL erreichbar und kann viele Clients gleichzeitig bedienen.

Tipp:Ältere Anleitungen nennen noch SSE als Transport. SSE gilt als veraltet, nimm für entfernte Server Streamable HTTP.

Voraussetzungen

Viele fertige Server werden über npx gestartet, deshalb brauchst du fast immer Node.js. Prüfe die Versionen kurz im Terminal, bevor du etwas einträgst.

  1. Claude Code oder die Claude-Desktop-App in aktueller Version.
  2. Node.js als LTS-Version für Server, die mit npx starten.
  3. Für einen eigenen Server mit dem TypeScript-SDK: Node.js 20 oder neuer.
  4. Für entfernte Server: die URL und, falls nötig, ein Konto beim Anbieter.
node --version
npx --version

In Claude Code hinzufügen

Lokale Server startet Claude als Programm, entfernte Server erreicht es über eine URL. Bei lokalen Servern trennen zwei Bindestriche (--) die Optionen von Claude vom Startbefehl des Servers. Ohne diese Trennung würde Claude Optionen des Servers wie --port als eigene lesen. Schlüssel gibst du mit -e als Umgebungsvariable mit, bei entfernten Servern mit --header.

# lokal: Dateien in einem Ordner
claude mcp add dateien -- npx -y @modelcontextprotocol/server-filesystem ~/Documents

# lokal mit Schlüssel als Umgebungsvariable
claude mcp add -e API_KEY=DEIN_SCHLUESSEL --transport stdio mein-dienst -- npx -y @beispiel/mcp-server

# entfernt: über eine URL
claude mcp add --transport http mein-server https://example.com/mcp

# entfernt mit Token im Header
claude mcp add --transport http mein-server https://example.com/mcp --header "Authorization: Bearer DEIN_TOKEN"

Tipp:Setze zwischen -e und den Servernamen eine weitere Option wie --transport stdio. Sonst liest Claude den Namen als weiteres Schlüssel-Wert-Paar.

Scopes und .mcp.json fürs Team

Der Scope legt fest, wo ein Server gilt und wer ihn sieht. Ohne Angabe landet er im Scope local: nur für dich und nur in diesem Projekt. Mit --scope user steht er dir in allen Projekten zur Verfügung. Beide speichert Claude in ~/.claude.json. Mit --scope project schreibt Claude ihn in die Datei .mcp.json im Projektordner, die du ins Repo eincheckst, damit das ganze Team denselben Server nutzt.

{
  "mcpServers": {
    "team-api": {
      "type": "http",
      "url": "https://example.com/mcp",
      "headers": { "Authorization": "Bearer ${API_KEY}" }
    }
  }
}

Tipp:In .mcp.json kannst du ${VARIABLE} schreiben, auch mit Standardwert als ${VARIABLE:-wert}. So steht der echte Schlüssel nie im Repo, jede Person setzt ihn lokal. Bevor Claude Code Server aus einer .mcp.json nutzt, fragt es einmal nach deiner Zustimmung.

In der Claude-Desktop-App

Die Desktop-App liest lokale Server aus der Datei claude_desktop_config.json. Unter macOS liegt sie in ~/Library/Application Support/Claude/, unter Windows in %APPDATA%\Claude\. Jeder Eintrag unter mcpServers hat einen Namen, einen Befehl (command) und dessen Argumente (args).

  1. In der App die Einstellungen öffnen, links „Developer“ wählen und auf „Edit Config“ klicken.
  2. Den Server unter mcpServers eintragen und die Datei speichern.
  3. Die App vollständig beenden und neu starten. Das Fenster zu schließen reicht nicht.
  4. Im Eingabefeld unter „Connectors“ prüfen, ob der Server und seine Werkzeuge erscheinen.
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/name/Documents"]
    }
  }
}

Achtung:Gib Pfade vollständig und absolut an, nicht relativ. Der Server läuft mit deinen Benutzerrechten und kann in den freigegebenen Ordnern alles, was du auch kannst.

Prüfen und verwalten

In einer laufenden Sitzung zeigt /mcp, welche Server verbunden sind und welche Werkzeuge sie anbieten. Dort meldest du dich auch bei entfernten Servern an, die OAuth verlangen: Claude öffnet den Browser, speichert das Token und erneuert es selbst. Im Terminal helfen drei Befehle.

claude mcp list            # alle Server und ihr Status
claude mcp get dateien     # Details zu einem Server
claude mcp remove dateien  # Server entfernen

Tipp:Werkzeuge eines Servers heißen in Claude Code mcp__server__werkzeug. Mit diesem Namen erlaubst oder sperrst du sie gezielt in den Berechtigungen.

Sicher bleiben

Ein MCP-Server kann alles, was du ihm erlaubst. Lokale Server laufen mit deinen Benutzerrechten, entfernte Server sehen alle Daten, die Claude ihnen schickt. Deshalb gelten ein paar feste Regeln.

  1. Nur Server aus vertrauenswürdigen Quellen installieren und den Code kurz ansehen.
  2. So wenig Rechte wie möglich: nur den Ordner freigeben, der gebraucht wird.
  3. Schlüssel und Tokens als Umgebungsvariablen übergeben, nie in den Code schreiben.
  4. Bei Werkzeugen, die etwas ändern oder senden, jede Aktion bestätigen lassen.
  5. Bei Servern, die fremde Inhalte laden, etwa Webseiten, Mails oder Tickets, mit Prompt Injection rechnen.

Achtung:Prompt Injection heißt: Text in den geladenen Daten versucht, Claude Anweisungen zu geben. Kombiniere deshalb nie ungeprüft einen Server, der fremde Texte liest, mit einem, der ohne Bestätigung sendet oder löscht.

Eigenen Server bauen

Mit dem offiziellen TypeScript-SDK beschreibst du jedes Werkzeug mit Namen, Beschreibung und Eingabeschema. Das Schema prüft die Eingaben, bevor dein Code läuft, und sagt Claude zugleich, welche Felder es füllen muss. Die Beschreibung ist wichtig, denn danach entscheidet Claude, wann es das Werkzeug nutzt. So habe ich mein Life OS an Claude angebunden: Aufgaben, Termine und Belege sind direkt im Chat abrufbar. Ältere Beispiele nutzen noch das Paket @modelcontextprotocol/sdk aus Version 1.

  1. Projekt anlegen und als ES-Modul markieren, weil das SDK nur ES-Module liefert.
  2. SDK, zod und tsx installieren. tsx führt TypeScript ohne Build-Schritt aus.
  3. Den Server in src/index.ts schreiben und mit npx tsx src/index.ts starten.
  4. In Claude Code eintragen, mit dem vollständigen Pfad zur Datei.
npm init -y
npm pkg set type=module
npm install @modelcontextprotocol/server zod tsx

// src/index.ts
import { McpServer } from '@modelcontextprotocol/server';
import { StdioServerTransport } from '@modelcontextprotocol/server/stdio';
import * as z from 'zod/v4';

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

server.registerTool(
  'begruessen',
  {
    description: 'Begrüßt eine Person mit Namen',
    inputSchema: z.object({ name: z.string() }),
  },
  async ({ name }) => ({
    content: [{ type: 'text', text: `Hallo, ${name}!` }],
  }),
);

async function main() {
  await server.connect(new StdioServerTransport());
}
main();

# eintragen
claude mcp add gruss -- npx tsx /voller/pfad/src/index.ts

Achtung:Bei stdio ist die Standardausgabe der Protokollkanal. Schon ein einziges console.log bringt die Nachrichten durcheinander. Logge deshalb immer mit console.error, das landet auf stderr.

Testen mit dem MCP Inspector

Bevor du einen Server in Claude einträgst, testest du ihn am besten mit dem MCP Inspector. Das ist eine lokale Weboberfläche, die deinen Server startet und dich jedes Werkzeug von Hand aufrufen lässt. So siehst du sofort, ob Schema, Eingaben und Antworten stimmen, ohne dass ein Modell dazwischensteht.

npx @modelcontextprotocol/inspector npx tsx src/index.ts

Tipp:Der Inspector funktioniert mit jedem stdio-Server, auch mit fremden. So prüfst du vor dem Eintragen, welche Werkzeuge ein Server wirklich mitbringt.

Entfernt betreiben

Soll ein Server von mehreren Geräten oder für mehrere Personen erreichbar sein, läuft er entfernt über Streamable HTTP. Cloudflare Workers eignen sich dafür: Cloudflare bietet eine Vorlage, die einen Server unter dem Pfad /mcp bereitstellt. Ohne Anmeldung kann ihn jede Person mit der URL nutzen. Für private Daten gehört deshalb eine Anmeldung davor. MCP empfiehlt dafür OAuth, und Claude Code führt dich über /mcp durch den Login.

# Vorlage ohne Anmeldung anlegen
npm create cloudflare@latest -- remote-mcp-server-authless --template=cloudflare/ai/demos/remote-mcp-authless

# lokal testen unter http://localhost:8788/mcp
npm start

# veröffentlichen
npx wrangler@latest deploy

# in Claude Code eintragen
claude mcp add --transport http mein-server https://remote-mcp-server-authless.DEIN-KONTO.workers.dev/mcp

Achtung:Die Vorlage „authless“ hat keine Anmeldung. Nutze sie zum Lernen, aber hänge keine echten Daten daran, bevor OAuth oder ein anderer Schutz eingebaut ist.

Häufige Fehler und Lösungen

Die meisten Probleme haben wenige Ursachen. Ein guter erster Schritt ist immer, den Startbefehl des Servers selbst im Terminal auszuführen. Fehler, die dort erscheinen, verhindern auch in Claude den Start.

  1. Server startet nicht: Befehl im Terminal testen und prüfen, ob node und npx gefunden werden.
  2. Falsche Pfade: in Konfigurationsdateien immer absolute Pfade verwenden.
  3. Fehlende Variablen: claude mcp list warnt, wenn eine ${VARIABLE} aus .mcp.json nicht gesetzt ist.
  4. Kaputtes JSON: Ein fehlendes Komma reicht, damit die Desktop-App keinen Server lädt.
  5. Änderung greift nicht: die Desktop-App komplett beenden und neu starten.
  6. Langsamer Start: Wartezeit erhöhen, zum Beispiel mit MCP_TIMEOUT=10000 claude für zehn Sekunden.

Tipp:Die Desktop-App schreibt Logs unter macOS nach ~/Library/Logs/Claude und unter Windows nach %APPDATA%\Claude\logs. In mcp-server-NAME.log steht die Fehlerausgabe des jeweiligen Servers.

Kurze Checkliste

Bevor du einen neuen Server dauerhaft nutzt, gehe diese Punkte durch.

  1. Quelle geprüft und Code oder Doku gelesen.
  2. Nur die nötigen Ordner und Rechte freigegeben.
  3. Schlüssel als Umgebungsvariable gesetzt, nichts davon im Repo.
  4. Passenden Scope gewählt: local, project oder user.
  5. Mit dem Inspector oder /mcp geprüft, dass Server und Werkzeuge funktionieren.
  6. Schreibende Werkzeuge nur mit Bestätigung erlaubt.

Weitere Notizen

Datenschutz

Keine Tracking-Cookies

Hier wird nichts über dich gesammelt.

Das merkt sich dein Browser

Nichts davon dient der Analyse.

Zur Datenschutzerklärung