# MCP-Server und Claude Code: Ein praktischer Leitfaden zur Integration und Entwicklung > Erweitern Sie die Funktionen von Claude Code mit dem Model Context Protocol: Anbindung an Dateisysteme, GitHub, PostgreSQL und Brave Search sowie die Entwicklung eigener Server in TypeScript. Claude Code kann „out of the box“ lokale Dateien lesen, Befehle im Terminal ausführen und den Quellcode eines Projekts bearbeiten. In der Praxis reicht dies jedoch oft nicht aus: Es besteht Bedarf an Informationen aus einer PostgreSQL-Datenbank, der Prüfung offener Pull Requests auf GitHub, dem Abrufen aktueller Dokumentation aus der Cloud oder dem Senden von Anfragen an interne Unternehmens-APIs. Genau für diese Herausforderung wurde das **Model Context Protocol (MCP)** entwickelt – ein offener Standard, der Claude Code von einem einfachen lokalen Assistenten in eine vollwertige Orchestrierungsplattform für externe Systeme und Dienste verwandelt. In diesem praktischen Leitfaden analysieren wir die MCP-Architektur, lernen offizielle vorgefertigte Server zu integrieren, erstellen einen eigenen Server in TypeScript und festigen unsere Kenntnisse durch reale Übungsaufgaben. --- ## 1. Was ist ein MCP-Server? Das **Model Context Protocol (MCP)** ist ein von Anthropic entwickeltes offenes Kommunikationsprotokoll, das die Interaktion zwischen Sprachmodellen (LLMs) und externen Tools oder Datenquellen standardisiert. Anstatt für jeden Dienst individuelle, einzigartige Plugins zu schreiben, führt MCP eine einheitliche Client-Server-Schnittstelle ein. ```text ┌─────────────────────────────────────────────────────────────┐ │ Claude Code (Клієнт) │ └──────────────────────────────┬──────────────────────────────┘ │ JSON-RPC 2.0 (stdio / SSE) ▼ ┌─────────────────────────────────────────────────────────────┐ │ MCP Server (Адаптер) │ └──────┬───────────────────────┼───────────────────────┬──────┘ │ │ │ ▼ ▼ ▼ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ Файлова │ │ GitHub API │ │ PostgreSQL │ │ система │ │ та Issues │ │ база даних │ └─────────────┘ └─────────────┘ └─────────────┘ ``` Jeder MCP-Server stellt dem Modell drei grundlegende Primitiven zur Verfügung: - **Tools (Werkzeuge)** – ausführbare Funktionen mit typisierter JSON-Schema-Parameterdefinition, die Claude Code während der Problemlösung autonom aufrufen kann (z. B. `create_issue`, `execute_query`). - **Resources (Ressourcen)** – passive Daten oder Schemata, die der Assistent als Eingabekontext lesen kann (Dateien, DB-Schemata, Logs). - **Prompts (Prompt-Vorlagen)** – vordefinierte Kontextszenarien, die die Ausführung häufiger, wiederkehrender Aufgaben vereinfachen. ### Vergleich der Fähigkeiten von Claude Code | Arbeitsszenario | Ohne MCP (Basis-Claude Code) | Mit verbundenen MCP-Servern | | :--- | :--- | :--- | | **Dateiverarbeitung** | Nur innerhalb des aktuellen Projektverzeichnisses | Zugriff auf alle freigegebenen Verzeichnisse und Notizen | | **Repository-Daten** | Lokale Dateien via `git diff` / `git log` | Lesen von Issues, PRs, Code Reviews und GitHub-API | | **Datenbanken** | Nur wenn lokaler CLI-Client installiert ist | Direktes Lesen von Schemata, Tabellen und Ausführen von SQL | | **Informationssuche** | Lokales grep / ripgrep in Dateien | Echtzeit-Websuche über Brave/Tavily | | **Interne Services** | Nicht verfügbar ohne komplexe Bash-Skripte | Aufruf interner API-Funktionen via typisiertes SDK | --- ## 2. Architektur und Funktionsweise von MCP Die Interaktionsarchitektur basiert auf dem Standardprotokoll **JSON-RPC 2.0**. In den meisten lokalen Szenarien erfolgt die Kommunikation über Standard-Ein-/Ausgabeströme (`stdio`), während für Remote-Server Server-Sent Events (`SSE`) oder HTTP verwendet werden. ### Schrittweiser Lebenszyklus einer Anfrage 1. **Initialisierung und Handshake:** Beim Start einer Session liest Claude Code die Konfigurationsdatei, startet die angegebenen Serverprozesse und fragt die Liste der unterstützten Tools ab (`tools/list`). 2. **Veröffentlichung der Fähigkeiten:** Jeder MCP-Server gibt eine Liste seiner Methoden zusammen mit JSON-Schemas der Parameter und detaillierten Beschreibungen zurück. 3. **Absichtserkennung:** Wenn Sie eine Aufgabe in natürlicher Sprache formulieren, gleicht Claude Ihre Anfrage mit den verfügbaren Tools ab. 4. **Tool-Aufruf:** Erfordert die Aufgabe externe Daten, sendet das Modell eine strukturierte Anfrage `tools/call` an den Server mit validen Argumenten. 5. **Ausführung auf Serverseite:** Der Server verbindet sich mit der externen API, Datenbank oder dem Dateisystem und gibt das Ergebnis an den Client zurück. 6. **Generierung der Antwort:** Nach Erhalt der Rohdaten interpretiert Claude diese und liefert Ihnen eine finale, strukturierte Antwort. > [!NOTE] > Die Interaktion ist für Entwickler transparent: Sie müssen sich keine Funktionsnamen oder API-Syntax merken. Claude wählt basierend auf dem Aufgabenkontext selbstständig das am besten geeignete Tool aus. --- ## 3. Wie man einen MCP-Server in Claude Code integriert Die Anbindung der Server erfolgt über die JSON-Konfiguration im Block `mcpServers`. Claude Code unterstützt zwei Konfigurationsebenen: 1. **Projekt-Konfiguration (`.claude/settings.json`)** – gilt ausschließlich für das aktuelle Verzeichnis und kann im Repository für das gesamte Team gespeichert werden. 2. **Globale Konfiguration (`~/.claude/settings.json`)** – steht allen Projekten des aktuellen Benutzers auf dem Computer zur Verfügung. :::tabs === Projekt (.claude/settings.json) ```json { "mcpServers": { "filesystem": { "command": "npx", "args": [ "-y", "@anthropic-ai/mcp-filesystem", "./docs" ] } } } ``` === Global (~/.claude/settings.json) ```json { "mcpServers": { "github": { "command": "npx", "args": [ "-y", "@anthropic-ai/mcp-github" ], "env": { "GITHUB_TOKEN": "ghp_your_token_here" } } } } ``` ::: ### Struktur der Konfigurationsparameter Jeder Servereintrag im Abschnitt `mcpServers` besteht aus drei Schlüsselfeldern: | Parameter | Typ | Pflichtfeld | Beschreibung und Zweck | Beispielwerte | | :--- | :--- | :--- | :--- | :--- | | `command` | `string` | Ja | Ausführbarer Befehl zum Starten des Serverprozesses | `"npx"`, `"node"`, `"uvx"`, `"docker"` | | `args` | `string[]` | Ja | Array der Startargumente (Paketname, Pfade, Optionen) | `["-y", "@anthropic-ai/mcp-filesystem", "/path"]` | | `env` | `object` | Nein | Dictionary der Umgebungsvariablen für Authentifizierung und API-Keys | `{"GITHUB_TOKEN": "ghp_...", "DEBUG": "1"}` | > [!TIP] > Wenn Sie Python-basierte Tools nutzen, können Sie statt `npx` auch `uvx` (aus dem Paketmanager `uv`) verwenden, z. B.: `"command": "uvx", "args": ["mcp-server-git"]`. --- ## 4. Katalog fertiger MCP-Server Anthropic und die Open-Source-Community haben vorgefertigte Server für die populärsten Tools entwickelt. Sie müssen keinen Code von Grund auf neu schreiben – es genügt, das entsprechende npm- oder python-Paket zu installieren. | Server | Offizielles Paket | Zugang / Authentifizierung | Hauptfunktionen | | :--- | :--- | :--- | :--- | | **Filesystem** | `@anthropic-ai/mcp-filesystem` | Pfade zu erlaubten lokalen Ordnern | Lesen, Schreiben und Suchen in externen Verzeichnissen | | **GitHub** | `@anthropic-ai/mcp-github` | Personal Access Token (`GITHUB_TOKEN`) | Suche in Repositories, Analyse von Issues, Erstellen von PRs | | **PostgreSQL** | `@anthropic-ai/mcp-postgres` | Verbindungszeichenkette (`connectionString`) | Inspektion von Schemata, Lesen von Tabellen, Ausführen von SQL-Abfragen | | **Brave Search** | `@anthropic-ai/mcp-brave-search` | API-Key für Suche (`BRAVE_API_KEY`) | Zugriff auf aktuelle Internetinformationen ohne Halluzinationen | ### 1. Filesystem Server Gewährt Claude Code Zugriff auf Verzeichnisse außerhalb des aktuellen Repositorys (z. B. globale Dokumentationsordner oder Obsidian-Notizen). ```json { "mcpServers": { "docs": { "command": "npx", "args": [ "-y", "@anthropic-ai/mcp-filesystem", "/Users/username/Developer/knowledge-base" ] } } } ``` ### 2. GitHub Server Ermöglicht dem Assistenten die direkte Arbeit mit Organisations-Repositories: Lesen von Issues, Hinterlassen von Kommentaren in PRs und Prüfen des Pipeline-Status. ```json { "mcpServers": { "github": { "command": "npx", "args": [ "-y", "@anthropic-ai/mcp-github" ], "env": { "GITHUB_TOKEN": "ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" } } } } ``` ### 3. PostgreSQL Server Erlaubt Claude, analytische oder diagnostische Abfragen direkt gegen Ihre lokale oder remote Datenbank auszuführen. ```json { "mcpServers": { "postgres": { "command": "npx", "args": [ "-y", "@anthropic-ai/mcp-postgres", "postgresql://postgres:password@localhost:5432/my_app_db" ] } } } ``` ### 4. Brave Search Server Integriert eine Web-Suchmaschine, sodass der Assistent aktuelle Dokumentation, Lösungen für kürzlich aufgetretene Bugs oder Änderungen in Bibliotheken finden kann. ```json { "mcpServers": { "brave-search": { "command": "npx", "args": [ "-y", "@anthropic-ai/mcp-brave-search" ], "env": { "BRAVE_API_KEY": "BSAu_your_brave_search_api_key" } } } } ``` --- ## 5. Wie Claude Code MCP im Dialog nutzt Nachdem der Server in der Konfiguration hinzugefügt wurde, müssen Sie keine speziellen Befehle oder Präfixe eingeben. Claude Code analysiert Ihre Anfrage in natürlicher Sprache und entscheidet selbstständig, wann ein Tool aufgerufen werden soll. ### Beispielszenario: Arbeit mit GitHub **Benutzeranfrage:** > „Prüfe, welche offenen Issues mir im Repository acme/platform zugewiesen sind, und gib eine kurze Liste der wichtigsten aus.“ **Interner Prozess von Claude Code:** 1. Das Modell erkennt, dass lokale Dateien für die Antwort nicht ausreichen. 2. Es formuliert einen Aufruf `mcp__github__search_issues` mit den Filtern `repo:acme/platform state:open assignee:@me`. 3. Es erhält eine strukturierte JSON-Antwort vom GitHub-Server. 4. Es formatiert die Antwort in einem benutzerfreundlichen Layout. ```markdown Знайдено 3 відкриті завдання, призначені на вас: 1. **#42 — Fix login redirect loop** (Пріоритет: High, Створено: 2 дні тому) 2. **#38 — Add rate limiting to auth API** (Пріоритет: Medium, Створено: 5 днів тому) 3. **#35 — Update user profile settings page** (Пріоритет: Low, Створено: 1 тиждень тому) Бажаєте детальніше розібрати код для виправлення помилки у #42? ``` --- ## 6. Erstellung eines eigenen MCP-Servers in TypeScript Wenn vorgefertigte Lösungen nicht ausreichen und Sie spezifische Tools für Geschäftslogik oder interne Microservices benötigen, lässt sich ein MCP-Server in wenigen Minuten mit dem offiziellen SDK `@modelcontextprotocol/sdk` erstellen. ### Schritt 1. Initialisierung und Installation der Abhängigkeiten Erstellen Sie ein separates Verzeichnis und installieren Sie die Bibliotheken: ```bash mkdir my-mcp-server && cd my-mcp-server npm init -y npm install @modelcontextprotocol/sdk zod npm install -D typescript @types/node tsx ``` ### Schritt 2. Implementierung des Servers (`server.ts`) Erstellen Sie die Datei `server.ts` mit der Definition des Servers und eines benutzerdefinierten Tools: ```typescript import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"; import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"; import { z } from "zod"; // 1. Ініціалізуємо сервер з метаданими const server = new McpServer({ name: "internal-crm-server", version: "1.0.0", }); // 2. Реєструємо інструмент пошуку користувача server.tool( "lookup-user", "Отримати профіль клієнта за його адресою електронної пошти", { email: z.string().email().describe("Email адреса зареєстрованого користувача"), }, async ({ email }) => { // Тут може бути реальний запит до CRM, Redis чи внутрішнього API const mockUser = { id: "usr_99812", email, name: "Олександр Коваленко", plan: "Enterprise", status: "active", createdAt: "2024-03-15T10:00:00Z", }; return { content: [ { type: "text", text: JSON.stringify(mockUser, null, 2), }, ], }; } ); // 3. Запускаємо сервер через стандартний stdio транспорт async function run() { const transport = new StdioServerTransport(); await server.connect(transport); console.error("Internal CRM MCP server started on stdio"); } run().catch((error) => { console.error("Server startup error:", error); process.exit(1); }); ``` ### Schritt 3. Anbindung des Servers an Claude Code Fügen Sie den erstellten Server in die `.claude/settings.json` Ihres Projekts ein: ```json { "mcpServers": { "crm": { "command": "npx", "args": [ "tsx", "/Users/username/Developer/my-mcp-server/server.ts" ] } } } ``` > [!TIP] > Die Verwendung des Utilities `tsx` ermöglicht die direkte Ausführung von TypeScript-Dateien, ohne dass eine vorherige Kompilierung via `tsc` erforderlich ist. --- ## 7. Sicherheit und Isolation bei der Arbeit mit MCP MCP erhöht die Autonomie von Claude Code erheblich, gibt dem Code aber auch die Möglichkeit, mit Ihrem Betriebssystem und externen Diensten zu interagieren. Um die Sicherheit Ihrer Arbeitsumgebung zu gewährleisten, halten Sie sich an folgende Regeln: ### 1. Der Server läuft mit Ihren Systemrechten Ein MCP-Server operiert im Kontext des aktuellen Betriebssystems-Benutzers. Falls der Server Fehler enthält oder schädlichen Code besitzt, kann er auf Dateien zugreifen, die Ihr Benutzer lesen darf. ### 2. Schutz von Secrets und API-Keys Speichern Sie niemals produktive Keys im Repository. Nutzen Sie die globale Konfiguration `~/.claude/settings.json` für sensible Tokens oder übergeben Sie Umgebungsvariablen über `.env`-Dateien, die in der `.gitignore` stehen. ### 3. Überprüfung fremder Pakete vor der Integration Auditen Sie stets das Repository oder npm-Paket eines Drittanbieter-MCP-Servers, bevor Sie ihn konfigurieren: - Stellen Sie sicher, dass der Quellcode offen liegt. - Prüfen Sie Download-Zahlen und Aktivität des Repositories. - Achten Sie auf Netzwerkrequests, die der Server beim Start ausführt. ### 4. Trennung der Konfigurationsebenen ```text ┌─────────────────────────────────────────────────────────────┐ │ ~/.claude/settings.json │ │ Глобальні інструменти: GitHub, Web Search, Браузер │ └──────────────────────────────┬──────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────┐ │ .claude/settings.json │ │ Локальні інструменти: Dev PostgreSQL, специфічні скрипти │ └─────────────────────────────────────────────────────────────┘ ``` > [!WARNING] > Vermeiden Sie die Anbindung von Servern mit Schreibrechten auf Produktionsdatenbanken (Production DB) im Entwicklungsmodus. Nutzen Sie für Tests separate Read-Only-Replikate oder lokale Docker-Container. --- ## 8. Praktischer Workshop: Schritt-für-Schritt-Setup Führen Sie zwei praktische Aufgaben durch, um den Stoff zu festigen und die korrekte Server-Anbindung zu überprüfen. ### Aufgabe 1. Anbindung des GitHub MCP Servers 1. Erstellen Sie einen neuen Personal Access Token (classic oder fine-grained) auf GitHub unter `Settings` → `Developer settings` mit den Berechtigungen `repo` und `read:org`. 2. Öffnen oder erstellen Sie die Konfigurationsdatei `~/.claude/settings.json`: ```json { "mcpServers": { "github": { "command": "npx", "args": [ "-y", "@anthropic-ai/mcp-github" ], "env": { "GITHUB_TOKEN": "ghp_ваш_токен_тут" } } } } ``` 3. Starten Sie eine neue Claude Code Session und führen Sie den Verifikations-Prompt aus: ```bash claude ``` > **Test-Prompt:** > „Zeige meine 5 zuletzt aktualisierten Repositories auf GitHub und deren Status.“ - [ ] Claude Code hat das GitHub-Tool erfolgreich ohne Authentifizierungsfehler aufgerufen. - [ ] Eine aktuelle Liste der Repositories wurde erhalten. --- ### Aufgabe 2. Anbindung des Filesystem Servers für externe Notizen Gewähren Sie Claude Zugriff auf einen externen Ordner mit Dokumentation oder Architektur-Notizen: 1. Fügen Sie den Server `filesystem` in die `.claude/settings.json` ein: ```json { "mcpServers": { "external-docs": { "command": "npx", "args": [ "-y", "@anthropic-ai/mcp-filesystem", "/шлях/до/вашої/папки/з_документами" ] } } } ``` 2. Testen Sie die Funktion mit einer Anfrage an Claude: > **Test-Prompt:** > „Finde im Ordner external-docs alle Markdown-Dateien, die die API-Architektur beschreiben, und erstelle eine kurze Übersicht.“ - [ ] Claude hat Dateien außerhalb des Projektarbeitsverzeichnisses gelesen. - [ ] Die gefundenen Informationen wurden ohne Kontextverlust zusammengefasst. --- ## 9. Schnelle Wissensüberprüfung Überprüfen Sie, wie gut Sie die fundamentalen Prinzipien der Model Context Protocol-Architektur verstanden haben. ### Frage 1. Was ist der Kernzweck eines MCP-Servers? - **A.** Eine Cloud-VM zum Hosting von Claude-Modellen - **B.** Ein Adapterprogramm, das dem Sprachmodell standardisierten Zugriff auf externe Tools und Daten bietet - **C.** Eine Bibliothek zur automatischen Komprimierung von Vektor-Embeddings - **D.** Ein Webserver zur Veröffentlichung kompilierten Projektcodes > [!TIP] > **Richtige Antwort: B.** > Ein MCP-Server ist ein lokaler oder entfernter Prozess, der als Brücke zwischen dem Modell und Drittdiensten fungiert und dem Modell standardisierte Tools, Resources und Prompts bereitstellt. --- ### Frage 2. In welcher Datei wird die Konfiguration für Server gespeichert, die nur für ein bestimmtes Repository gedacht sind? - **A.** `~/.claude/settings.json` - **B.** `package.json` - **C.** `.claude/settings.json` im Projektstammverzeichnis - **D.** `CLAUDE.md` > [!TIP] > **Richtige Antwort: C.** > Für die Konfiguration auf Ebene eines einzelnen Projekts wird `.claude/settings.json` verwendet. Die Datei im Home-Verzeichnis `~/.claude/settings.json` ist für die globalen Entwickler-Tools zuständig. --- ### Frage 3. Wie weiß Claude Code, welches Tool zur Beantwortung einer Frage genutzt werden soll? - **A.** Der Nutzer muss explizit den Flag `--tool=name` vor jeder Anfrage setzen - **B.** Es muss zuvor der Befehl `/mcp select` ausgeführt werden - **C.** Das Modell analysiert die Semantik der Anfrage und die Beschreibungen der JSON-Schemas der Tools und wählt das relevante Tool selbstständig aus - **D.** Alle Tools werden gleichzeitig aufgerufen, unnötige Ergebnisse verworfen > [!TIP] > **Richtige Antwort: C.** > Dank standardisierter Beschreibungen und Parameterschemas bewertet Claude die Absicht des Nutzers und ruft autonom das benötigte Tool mit validen Argumenten auf. --- ## 10. Zusammenfassung und Architektur-Checkliste Das Model Context Protocol macht Claude Code zu einer flexiblen agentischen Umgebung. Statt Inhalte von Dateien oder Datenbankschemata manuell in den Dialog zu kopieren, richten Sie einmalig permanente Kommunikationskanäle ein. ### Checkliste für die Bereitschaft Ihrer Umgebung - [x] **Konfigurationsebenen:** Globale Services (GitHub, Web Search) sind in `~/.claude/settings.json` ausgelagert, projektspezifische (DB, Doku) in `.claude/settings.json`. - [x] **Sicherheit:** Tokens und Passwörter werden nicht in öffentliche Repos committet; Datenbanken sind mit minimal notwendigen Rechten verbunden (Read-Only für Analysen). - [x] **Tool-Testing:** Die Funktionalität der Server wurde nach Sessionstart durch gezielte Anfragen verifiziert. - [x] **Erweiterbarkeit:** Für spezifische interne Aufgaben wurde ein Template für einen eigenen Server in TypeScript via `@modelcontextprotocol/sdk` erstellt.