Dateisystem, GitHub, DB, Slack über Model Context Protocol für KI-Agenten verfügbar machen. Einrichtung, Debugging, Sicherheit.

Model Context Protocol (MCP) ist der Standard, um externe Tools und Daten für KI-Agenten verfügbar zu machen. Anthropics offene Spezifikation wurde von Claude Code, Cursor, Continue und anderen übernommen — alle teilen dieselbe Schnittstelle.

Kurzgefasst: „Ich möchte, dass Claude oder ein anderes Modell direkt mein Dateisystem / meine DB / GitHub anfassen kann, ohne jedes Mal eigene API-Wrapper schreiben zu müssen."

Ich denke, was MCP so bedeutsam macht, ist nicht die technische Cleverness des Protokolls, sondern was es bedeutet: dass externe Tools nicht mehr als separate API-Schichten gebaut werden müssen, sondern als erste Fähigkeit des Agenten erscheinen — weil das der eigentliche Übergang von Agenten als Wrapper zu Agenten als eigenständige Akteure ist. Ursprünglich musste jede Tool-Integration separat implementiert werden; heute reicht ein standardisierter MCP-Server, den alle kompatiblen Hosts teilen.

Dieser Leitfaden behandelt die Kernkonzepte, gängige Server-Konfigurationen, Debugging und Sicherheit.

TL;DR

MCP ist JSON-RPC über stdio/SSE — exponiert Tools über ein standardisiertes RPC-Protokoll
Offizielle Server: Dateisystem, GitHub, Slack, Postgres, Puppeteer u. a. — @modelcontextprotocol/server-*
Eine gemeinsame Client-Konfiguration: Claude Code nutzt ~/.claude/settings.json, Cursor seine Einstellungs-UI — gleiches JSON-Schema
Sicherheitsregel Nr. 1: Read-Only-Server bevorzugen; schreibbaren Servern nur explizite Whitelist-Verzeichnisse erlauben

Voraussetzungen

Node.js 20+ (für npx)
Ein MCP-kompatibler Client — Claude Code oder Cursor
API-Tokens für alle zu exponierenden Dienste (GitHub PAT, Slack usw.)

1. MCP-Konzepte in 30 Sekunden

Begriff	Bedeutung
Host	KI-Agent (Claude Code, Cursor)
Server	Ein Prozess, der Tools/Ressourcen exponiert (Dateisystem, GitHub)
Client	Der Adapter, den der Host für jeden Server startet
Transport	stdio (lokaler Kindprozess) oder SSE (HTTP-Remote)
Tool	Eine Funktion, die der Server exponiert — KI kann sie aufrufen
Resource	Daten, die der Server exponiert — KI kann sie lesen
Prompt	Ein Prompt-Template, das der Server bereitstellt

2. MCP in Claude Code hinzufügen

2.1 Einstellungsdatei

~/.claude/settings.json:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/me/projects",
        "/Users/me/notes"
      ]
    }
  }
}

Befehlsargumente = freizugebende Verzeichnisse als Whitelist — nichts anderes ist erreichbar.
Absolute Pfade verwenden. ~/ wird nicht expandiert.

2.2 Claude Code neustarten

# Nach dem Beenden der vorherigen Sitzung
claude

2.3 Überprüfen

In Claude Code:

Welche Tools sind verfügbar?

Wenn read_file, write_file, list_directory vom Dateisystem-MCP erscheinen, ist die Einrichtung erfolgreich.

3. MCP in Cursor hinzufügen

Einstellungen (⌘,) → Funktionen → MCP → Server hinzufügen. JSON:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me/projects"]
    }
  }
}

Gleiches Schema. Die Konfiguration kann mit Claude Code geteilt werden — ~/.claude/settings.json kopieren und importieren.

4. Sechs häufige Server

4.1 Dateisystem

"filesystem": {
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-filesystem", "/pfad/zum/erlaubten/verzeichnis"]
}

Dateien lesen / schreiben / suchen. Erzwingt eine Pfad-Whitelist.

4.2 GitHub

"github": {
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-github"],
  "env": {
    "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_..."
  }
}

Issues, PRs, Code-Suche. PAT-Berechtigungen auf das Minimum beschränken (repo, read:user).

4.3 Slack

"slack": {
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-slack"],
  "env": {
    "SLACK_BOT_TOKEN": "xoxb-...",
    "SLACK_TEAM_ID": "T..."
  }
}

Kanäle lesen und senden. Bot-Token gegenüber User-Token bevorzugen.

4.4 PostgreSQL (Read-Only)

"postgres": {
  "command": "npx",
  "args": [
    "-y",
    "@modelcontextprotocol/server-postgres",
    "postgresql://readonly_user:pass@localhost/mydb"
  ]
}

Als Read-Only-Benutzer verbinden — die KI kann beliebige Queries ausführen, daher Datenbankberechtigungen strikt aufteilen.

4.5 Puppeteer

"puppeteer": {
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-puppeteer"]
}

Echte Browser-Automatisierung: Screenshots, DOM-Manipulation, JavaScript-Ausführung.

4.6 SQLite

"sqlite": {
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-sqlite", "/pfad/zur/db.sqlite"]
}

Ideal für lokale SQLite-Analyse.

5. Secrets via 1Password verwalten

Tokens niemals im Klartext in JSON-Dateien schreiben. Das Muster aus multi-os/password-manager verwenden:

Option A — chezmoi-Template

~/.claude/settings.json unter chezmoi platzieren und {{ onepasswordRead "op://..." }} verwenden.

Option B — Wrapper-Skript

# ~/bin/mcp-github.sh
#!/bin/bash
export GITHUB_PERSONAL_ACCESS_TOKEN="$(op item get GitHub --fields token --reveal)"
exec npx -y @modelcontextprotocol/server-github

settings.json:

"github": {
  "command": "/Users/me/bin/mcp-github.sh"
}

Die op-CLI entsperrt automatisch per Biometrik — nahtlos in den Workflow integriert.

6. Eigenen MCP-Server schreiben

In zehn Minuten ein eigenes Tool exponieren. Node.js (my-server.js):

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-tools", version: "0.1.0" },
  { capabilities: { tools: {} } }
);
 
server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: [
    {
      name: "echo",
      description: "Eingabe zurückgeben",
      inputSchema: {
        type: "object",
        properties: { msg: { type: "string" } },
        required: ["msg"],
      },
    },
  ],
}));
 
server.setRequestHandler(CallToolRequestSchema, async (req) => {
  if (req.params.name === "echo") {
    return { content: [{ type: "text", text: req.params.arguments.msg }] };
  }
  throw new Error(`Unbekanntes Tool: ${req.params.name}`);
});
 
await server.connect(new StdioServerTransport());

"my-tools": {
  "command": "node",
  "args": ["/Users/me/code/my-server.js"]
}

Offizielle MCP SDK-Beispiele ansehen.

7. Debugging

Tools erscheinen nicht

Client (Claude Code / Cursor) vollständig neu starten
Prüfen, ob npx ausführbar ist — which npx / Node 20+
Server-Logs prüfen — bei Claude Code: System-Logs oder stderr

MCP Inspector

Offizielles Debug-Tool:

npx @modelcontextprotocol/inspector npx -y @modelcontextprotocol/server-filesystem /tmp

Browser-UI für direkte RPC-Aufrufe — visualisiert Tool-Definitionen und Antworten.

Langsame Antworten

Erster Aufruf: npx -y lädt das Paket herunter — einmalig langsam, danach durch Caching schnell
Dauerhafte Installation: npm i -g @modelcontextprotocol/server-filesystem, dann command: "mcp-server-filesystem"

8. Sicherheit

Nur Whitelist-Verzeichnisse

Für das Dateisystem-MCP immer explizite Pfadargumente übergeben. Ohne Argumente wird das gesamte Home-Verzeichnis exponiert.

Read-Only-Datenbankbenutzer

Für Postgres/SQLite einen separaten Read-Only-Benutzer anlegen. Die KI darf kein DROP TABLE ausführen können.

Minimale Token-Berechtigungen

GitHub PAT: repo + read:user. Kein admin:org.

Env-Leaks vermeiden

settings.json nicht in git einchecken. Falls nötig, chezmoi oder Secret-Integration verwenden (§5).

Unbekannten MCP-Servern nicht vertrauen

Nur offizielle @modelcontextprotocol/*-Pakete oder geprüfte Open-Source-Pakete verwenden. Tokens keinen unbekannten npm-Paketen übergeben.

Überprüfung

Nach Änderungen an settings.json Claude Code neu starten → „Verfügbare Tools anzeigen" → neue Server-Tools erscheinen
„Zeige Dateien im Stammverzeichnis" (mit Dateisystem-Server)
„Fasse die letzten 5 PRs zusammen" (GitHub-Server)
Tool-Definitionen mit MCP Inspector prüfen
Einen Pfad außerhalb der Whitelist versuchen → abgelehnt

Fehlerbehebung

`npx -y` findet das Paket nicht

Tippfehler bei @modelcontextprotocol/server-XXX sind häufig. Die offizielle Liste prüfen
Bei unternehmensinternen npm-Registries: die öffentliche Registry als Fallback in .npmrc setzen

Pfad unter Windows funktioniert nicht

\ escapen oder / in JSON verwenden:

"args": ["-y", "@modelcontextprotocol/server-filesystem", "C:/Users/me/projects"]

Claude Code erkennt den Server nicht

~/.claude/settings.json-Syntax validieren: jq . ~/.claude/settings.json
Mögliche Verwechslung mit anderen settings.json-Speicherorten (~/.claude.json, .claude/settings.json im Projekt)

Einige Tools fehlen in der Antwort

Server mit nicht-deterministischem Tool-Listing können nach Neustart variieren. Den listTools-Handler deterministisch implementieren.

Token versehentlich eingecheckt

Sofort rotieren (GitHub → Personal access tokens → Widerrufen + neu ausstellen). Git-History mit git filter-repo bereinigen.

Referenzen

Claude Code einrichten — Host-Einrichtung
Cursor einrichten — Host-Einrichtung
Multi-Agenten-Workflow — Haupt/Sub-Aufteilung
Passwort-Manager — Token-Sicherheit
Model Context Protocol (offiziell)
Offizieller Server-Pool

Changelog

2026-05-12: Erster Entwurf. Konzepte + Client-Einrichtung + 6 Server + Secrets-Management + eigener Server + Debugging + Sicherheit + fünf Fehlerbehebungsfälle.

MCP-Server — externe Tools mit Claude Code / Cursor verbinden