Das Model Context Protocol (MCP) ermöglicht Claude Code die Verwendung von Tools über seinen integrierten Satz hinaus, wie z. B. die Suche in einem Issue-Tracker, das Abfragen einer Datenbank oder die Steuerung eines Webbrowsers. Diese Tools stammen von MCP-Servern, die auf Ihrem Computer oder als gehostete Dienste ausgeführt werden. Diese Anleitung führt Sie durch die End-to-End-Verbindung eines MCP-Servers mit der Claude Code CLI. Am Ende haben Sie einen verbundenen und reagierenden Server, wissen, wo seine Konfiguration auf der Festplatte gespeichert ist, und wissen, wie Sie die häufigsten Verbindungsfehler beheben.Documentation Index
Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt
Use this file to discover all available pages before exploring further.
Bevor Sie beginnen
Stellen Sie sicher, dass Sie haben:- Claude Code installiert und authentifiziert
- Ein Terminal in einem Projektverzeichnis geöffnet. Jedes Verzeichnis funktioniert, auch ein leeres.
Einen Server hinzufügen und überprüfen
Das folgende Beispiel verbindet sich mit dem Claude Code-Dokumentations-MCP-Server, einem gehosteten Server mit Volltextsuche über die Claude Code-Dokumentation. Er erfordert keine Authentifizierung oder spezielle Konfiguration, daher funktioniert er gut als erster Server zum Testen des Setup-Ablaufs. Die Schritte sind für jeden Server gleich: fügen Sie ihn hinzu, überprüfen Sie den Verbindungsstatus, verwenden Sie ihn dann in einer Sitzung, mit einem optionalen Bereinigungsschritt am Ende. Einige Server fügen einen Schritt hinzu, wie z. B. eine Browser-Anmeldung, die in Zusätzliche MCP-Server-Beispiele gezeigt wird. Weitere Server zum Verbinden finden Sie im Anthropic-Verzeichnis.Fügen Sie den MCP-Server hinzu
claude-Sitzung: Sie konfigurieren den Server vor dem Starten einer Konversation.claude mcp add: registriert einen Server bei Claude Code.--transport http: Der Server wird unter einer URL gehostet, anstatt als lokaler Prozess ausgeführt zu werden.claude-code-docs: ein Name, den Sie sich ausdenken. Das Aufrufen desselben Servers alsdocswürde identisch funktionieren. Claude Code verwendet den Namen, den Sie wählen, um die Tools des Servers in Claudes Ausgabe zu kennzeichnen und um auf den Server in Befehlen wieclaude mcp removezu verweisen.https://code.claude.com/docs/mcp: die URL, unter der der Server gehostet wird.
Added HTTP MCP server claude-code-docs with URL: https://code.claude.com/docs/mcp to local config aus. Der Teil local config bedeutet, dass der Server bei Ihnen in diesem Projekt registriert ist: Wenn Sie Claude Code in einem anderen Projekt starten, ist dieser Server dort nicht aktiv. Um einen Server einmal für alle Ihre Projekte zu registrieren, fügen Sie ihn im Benutzerbereich hinzu, was in Server-Bereich ändern behandelt wird.Überprüfen Sie den Verbindungsstatus
| Status | Bedeutung |
|---|---|
✓ Connected | Einsatzbereit. Das sollten Sie für claude-code-docs sehen |
! Needs authentication | Der Server ist erreichbar, benötigt aber eine Browser-Anmeldung oder ein Token, das mit --header übergeben wird. Siehe Verbinden Sie einen Server, der eine Anmeldung erfordert |
✗ Failed to connect | Server hat nicht reagiert. Siehe Fehlerbehebung |
✗ Connection error | Der Verbindungsversuch hat einen Fehler ausgelöst. Siehe Fehlerbehebung |
⏸ Pending approval | Ein projektbezogener Server, den Sie noch nicht genehmigt haben. Siehe Bearbeiten Sie .mcp.json direkt |
Verwenden Sie den Server
Entfernen Sie den Server
Wo Server gespeichert werden
Der Befehlclaude mcp add schreibt die Details des Servers in eine Konfigurationsdatei. Standardmäßig registriert er den Server im local-Bereich: privat für Sie, aktiv nur im aktuellen Projekt. Übergeben Sie --scope user, um ihn einmal für alle Ihre Projekte zu registrieren, oder --scope project, um ihn mit Ihrem Team zu teilen. Server-Bereich ändern führt Sie durch beide.
claude mcp add funktioniert in jeder Shell gleich, einschließlich PowerShell und Command Prompt. Verwenden Sie in einer claude-Sitzung den Befehl /mcp, um bereits hinzugefügte Server zu überprüfen und zu verwalten.- Fügen Sie einen lokalen Server hinzu: Führen Sie ein Programm auf Ihrem Computer aus, anstatt sich mit einer URL zu verbinden.
- Bearbeiten Sie
.mcp.jsondirekt: Schreiben Sie den JSON-Eintrag selbst, anstatt den Befehl zu verwenden. - Verbinden Sie einen Server, der eine Anmeldung erfordert: Fügen Sie einen gehosteten Server hinzu, der eine Browser-Anmeldung benötigt, bevor seine Tools funktionieren.
Finden Sie Ihre Konfiguration auf der Festplatte
Der Befehlclaude mcp add schreibt den Server in einen von drei Bereichen, die über zwei Dateien verteilt sind, je nach dem Flag --scope. Sie müssen diese Dateien nicht direkt bearbeiten, aber zu wissen, wo sie sich befinden, hilft beim Debuggen und bei der Versionskontrolle.
| Bereich | Datei | Verfügbar für |
|---|---|---|
local | ~/.claude.json, unter dem Eintrag für dieses Projekt | Nur Sie, nur dieses Projekt. Der Standard |
project | .mcp.json im Projektstammverzeichnis | Jeder, der das Projekt klont |
user | ~/.claude.json, unter dem Top-Level-Schlüssel mcpServers | Nur Sie, alle Projekte |
~/.claude.json zu %USERPROFILE%\.claude.json, typischerweise C:\Users\YourName\.claude.json. Wenn Sie CLAUDE_CONFIG_DIR gesetzt haben, liest Claude Code .claude.json stattdessen aus diesem Verzeichnis.
Führen Sie claude mcp get claude-code-docs aus, um zu sehen, welcher Bereich die Definition eines Servers enthält. Wie die Bereiche interagieren, wenn derselbe Server in mehr als einem definiert ist, siehe MCP-Installationsbereiche.
Server-Bereich ändern
Der Bereich eines Servers ist beim Hinzufügen festgelegt, daher bedeutet das Ändern des Bereichs, den Eintrag zu entfernen und ihn im neuen Bereich erneut hinzuzufügen. Beide Fälle unten beginnen damit, den lokalen Eintrag aus der ersten Anleitung zu entfernen, damit der Server nur eine Definition hat. Wenn Sie ihn bereits am Ende dieser Anleitung entfernt haben, überspringen Sie diesen Befehl:Verwenden Sie einen Server in allen Ihren Projekten
Fügen Sie den Server imuser-Bereich erneut hinzu, um ihn in jedem Projekt aktiv zu machen, das Sie öffnen, immer noch privat für Sie:
Teilen Sie einen Server mit Ihrem Team
Fügen Sie den Server improject-Bereich erneut hinzu, der in .mcp.json im Projektstammverzeichnis schreibt:
.mcp.json zur Versionskontrolle. Teamkollegen, die das Repository klonen und Claude Code starten, sehen eine Aufforderung zur Genehmigung des Servers, dann verbindet er sich auch für sie.
Zusätzliche MCP-Server-Beispiele
Die erste Anleitung verwendete einen gehosteten Server, der sich ohne Anmeldung verbindet. Die folgenden Beispiele behandeln die anderen zwei häufigen Formen mit dem gleichen Hinzufügen-, Überprüfen-, Verwenden-Ablauf.Fügen Sie einen lokalen Server hinzu
Ein lokaler stdio-Server ist ein Programm, das Claude Code als Unterprozess auf Ihrem Computer startet, anstatt es über eine URL zu erreichen. Verwenden Sie einen für Tools, die Zugriff auf lokale Ressourcen wie einen Browser, Ihr Dateisystem oder einen Datenbanksocket benötigen. Der Playwright MCP-Server ist ein guter zum Ausprobieren: Er gibt Claude einen Browser, den er navigieren, klicken und lesen kann, und benötigt kein Konto. Er läuft übernpx, daher benötigt er Node.js 18 oder später.
Fügen Sie den Playwright-Server hinzu
- Es gibt kein
--transport-Flag, da lokale Server das Standard-stdio-Transport verwenden. - Alles nach dem
---Trennzeichen ist der Befehl, den Claude Code ausführt, um den Server zu starten. -yteiltnpxmit, das Paket ohne Aufforderung zu installieren.
--browser mit dem Browser-Namen an, z. B. --browser firefox, nach @playwright/mcp@latest.Überprüfen Sie die Verbindung
Added-Bestätigung bedeutet, dass der Eintrag gespeichert wurde, nicht dass der Befehl ausgeführt wird. Überprüfen Sie die Verbindung:✗ Failed to connect anzeigen, während npx das Paket herunterlädt, daher warten Sie einen Moment und führen Sie es erneut aus.Verwenden Sie den Browser
playwright-Servernamen und der Aktion gekennzeichnet, wie z. B. browser_navigate.Versuchen Sie, es auf Ihren lokalen Dev-Server zu verweisen, um zu überprüfen, dass eine Seite nach einer Änderung immer noch gerendert wird, oder lassen Sie es einen Fehlerbericht Schritt für Schritt durchgehen.Verbinden Sie einen Server, der eine Anmeldung erfordert
Gehostete Dienste wie Sentry, Linear und Notion führen ihre MCP-Server hinter OAuth aus: Sie fügen die URL des Servers hinzu, dann melden Sie sich über Ihren Browser an. Die folgenden Schritte verwenden Sentry als Beispiel. Um einen anderen Dienst zu verbinden, ersetzen Sie seine URL, die Sie im Anthropic-Verzeichnis oder in der Dokumentation des Dienstes finden können.Fügen Sie den Server hinzu
add-Befehl ist derselbe wie für den Dokumentationsserver, mit Sentrys URL:claude mcp list den Server mit ! Needs authentication an. Das ist erwartet: Der nächste Schritt schließt die Anmeldung ab.Authentifizieren Sie sich in Ihrem Browser
sentry aus der Liste, drücken Sie Enter, und wählen Sie Authenticate. Ihr Browser öffnet sich auf Sentrys Anmeldeseite. Genehmigen Sie die Verbindung dort.Zurück in Claude Code ändert sich der Status des Servers zu verbunden. Wenn die Anmeldung fehlschlägt oder der Browser nicht öffnet, siehe Fehlerbehebung.--header "Authorization: Bearer <token>" an. Siehe das GitHub-Beispiel für eine durchgearbeitete Version.
Bearbeiten Sie .mcp.json direkt
Jede Datei in der Bereichstabelle verwendet das gleiche JSON-Format für Server-Einträge. Dieser Abschnitt bearbeitet.mcp.json, die projektbezogene Datei. Es ist die, die sich am meisten lohnt, von Hand zu schreiben, da sie im Repository eingecheckt wird, wo sie auch als Konfiguration-als-Code für Ihr Team dient.
Erstellen Sie .mcp.json im Projektstammverzeichnis. Das folgende Beispiel definiert beide Server aus dieser Anleitung, den gehosteten Dokumentationsserver, der über HTTP erreichbar ist, und den Playwright-Server als lokalen stdio-Prozess:
- Für HTTP-Server ist
urlder Endpunkt, mit dem sich Claude Code verbindet. - Für stdio-Server sind
commandundargsdas Programm, das es ausführt.
.mcp.json beim Start.
Wenn Claude Code zum ersten Mal einen projektbezogenen Server sieht, fragt es Sie, ihn zu genehmigen. Die Aufforderung existiert, damit ein Repository, das Sie klonen, keine Prozesse auf Ihrem Computer ohne Ihre Zustimmung starten kann. Genehmigen Sie die Aufforderung, oder führen Sie /mcp aus, um später zu genehmigen, wenn Sie sie verpasst haben.
Nachdem Sie genehmigt haben, führen Sie /mcp aus und überprüfen Sie, dass die Server als verbunden angezeigt werden. Wenn einer stattdessen einen Fehler anzeigt, siehe Fehlerbehebung.
Von anderen Oberflächen verbinden
Diese Anleitung verwendet dieclaude mcp CLI-Befehle, aber jede Claude Code-Oberfläche kann sich mit MCP-Servern verbinden:
- Claude Code Desktop-App: Fügen Sie Server über die Connectors-Benutzeroberfläche hinzu.
- Claude Desktop Chat-App: eine separate App von Claude Code. Um Server aus ihrer
claude_desktop_config.jsonin die CLI zu kopieren, führen Sieclaude mcp add-from-claude-desktopauf macOS oder WSL aus. - VS Code: siehe Mit externen Tools mit MCP verbinden.
- Claude Code im Web: liest
.mcp.jsonaus Ihrem Repository. Siehe Bearbeiten Sie .mcp.json direkt. - Claude.ai: Connectors, die Sie unter claude.ai/customize/connectors hinzufügen, werden automatisch in die CLI geladen, wenn Sie sich mit diesem Konto anmelden. Siehe Verwenden Sie MCP-Server von Claude.ai.
Fehlerbehebung
Wenn sich ein Server nicht verbindet, überprüfen Sie seinen Status mit/mcp in einer Sitzung oder claude mcp list aus Ihrer Shell, dann gleichen Sie das Symptom unten ab. Das /mcp-Panel ermöglicht es Ihnen auch, sich erneut zu verbinden oder zu authentifizieren, ohne die Sitzung zu verlassen.
/mcp shows No MCP servers configured
/mcp shows No MCP servers configured
- Sie haben
claude mcp addaus einem anderen Projekt ausgeführt. Lokal begrenzte Server sind an das Projekt gebunden, in dem Sie sie hinzugefügt haben: das Repository-Stammverzeichnis oder das genaue Verzeichnis, wenn Sie sich nicht in einem Git-Repository befanden. Fügen Sie den Server aus dem Projekt erneut hinzu, in dem Sie sich jetzt befinden, oder fügen Sie ihn mit--scope userhinzu, damit er nicht an ein Projekt gebunden ist. - Sie haben eine Konfigurationsdatei unter dem falschen Pfad bearbeitet. Die richtigen Dateien sind
~/.claude.jsonund<project>/.mcp.json. Claude Code liest keine Pfade wie~/.claude/config/mcp.json,~/.claude/mcp.jsonoder%APPDATA%\Claude\mcp.json.
Status shows Failed to connect or Connection error
Status shows Failed to connect or Connection error
curl.exe anstelle von curl, damit die Anfrage zum echten curl-Binary geht, anstatt zum Invoke-WebRequest-Alias.Die Antwort sagt Ihnen, welche Art von Problem Sie haben:- Ein
404oder405: Der Server ist aktiv. Viele MCP-Endpunkte antworten nur auf POST-Anfragen, daher bestätigt dies immer noch, dass die URL von Ihrem Computer aus erreichbar ist. - Ein
401oder403: Der Server ist aktiv und Sie müssen sich authentifizieren. Verwenden Sie die Browser-Anmeldung in Verbinden Sie einen Server, der eine Anmeldung erfordert, oder für Server, die stattdessen ein Token annehmen, wie GitHubs, übergeben Sie es mit--header "Authorization: Bearer <token>"imclaude mcp add-Befehl. - Keine Antwort: Überprüfen Sie die URL und Ihr Netzwerk.
- Der Befehl startet und wartet auf Eingabe: Der Server selbst funktioniert. Führen Sie
claude mcp get <name>aus und bestätigen Sie, dass der dort angezeigte Befehl dem entspricht, den Sie gerade ausgeführt haben. Wenn sich der angezeigte Befehl von dem unterscheidet, den Sie eingegeben haben, haben Sie wahrscheinlich das---Trennzeichen vor dem Server-Befehl weggelassen. Entfernen Sie den Server und fügen Sie ihn mit--an der richtigen Stelle erneut hinzu. Wenn Sie.mcp.jsonvon Hand geschrieben haben, überprüfen Sie seine Syntax und seinen Speicherort. - Der Befehl gibt einen Fehler aus: Die Nachricht nennt, was fehlt, wie z. B. Node.js oder ein Browser.
Connection timed out at startup
Connection timed out at startup
npx das Paket herunterlädt. Erhöhen Sie das Limit mit der Umgebungsvariablen MCP_TIMEOUT, in Millisekunden:Server already exists
Server already exists
remove exists in multiple scopes. Übergeben Sie --scope, um zu wählen, welche Kopie gelöscht werden soll, z. B. claude mcp remove claude-code-docs --scope local.Server connects but no tools appear
Server connects but no tools appear
/mcp in einer Sitzung aus und wählen Sie den Server, um seine Tool-Liste zu sehen. Wenn die Liste leer ist, ist der Server gestartet, hat aber keine Tools registriert, was normalerweise bedeutet, dass ihm eine erforderliche Umgebungsvariable wie ein API-Schlüssel fehlt.Übergeben Sie die Variable mit --env KEY=value im claude mcp add-Befehl, oder im env-Feld des Server-Eintrags in .mcp.json. Die Dokumentation des Servers listet die Variablen auf, die er benötigt.Changes to .mcp.json don't take effect
Changes to .mcp.json don't take effect
.mcp.json beim Sitzungsstart. Beenden Sie die Sitzung und starten Sie sie nach dem Bearbeiten der Datei neu.Wenn Ihre Server immer noch nicht angezeigt werden, führen Sie /mcp aus und suchen Sie nach einer Parse-Warnung. Claude Code überspringt fehlerhafte Einträge und zeigt das beleidigende Feld dort an.Wenn Sie den Server zuvor abgelehnt haben, wenn Sie dazu aufgefordert wurden, setzen Sie Projektgenehmigungen zurück:OAuth sign-in fails or browser doesn't open
OAuth sign-in fails or browser doesn't open
/mcp aus, wählen Sie den Server, und wählen Sie Authenticate erneut. Wenn der Browser nicht automatisch öffnet, kopieren Sie die im Terminal angezeigte URL und öffnen Sie sie manuell. Siehe Authentifizieren Sie sich mit Remote-MCP-Servern für feste Callback-Ports und vorkonfigurierte Anmeldedaten.Nächste Schritte
Mit einem verbundenen Server erkunden Sie den Rest dessen, was MCP ermöglicht:- Finden Sie weitere MCP-Server im Anthropic-Verzeichnis
- Teilen Sie Server mit Ihrem Team mit Installationsbereichen
- Verwalten Sie MCP-Zugriff für eine Organisation mit verwalteten Einstellungen und Richtlinienkontrollen
- Referenzieren Sie MCP-Ressourcen in Eingabeaufforderungen mit @-Erwähnungen
- Führen Sie MCP-Eingabeaufforderungen als Befehle aus aus dem
/-Menü - Erstellen Sie Ihren eigenen Server mit dem MCP SDK