MCP-Server in Cursor Fehlerbehebung

MCP-Server erweitern Cursor um externe Tools, aber sie sind unabhängige Prozesse mit eigenen Abhängigkeiten, und wenn sie sich fehlerhaft verhalten, können die Symptome verwirrend sein: ein Server, der rot angezeigt wird, eine Tool-Liste, die sich nicht aktualisiert, oder eine Disconnect-Schaltfläche, die nichts zu bewirken scheint. Dieser Leitfaden gibt Ihnen eine systematische Methode zur Diagnose von MCP-Problemen in Cursor, von der schnellen Triage-Checkliste über die spezifischen Korrekturen für jeden häufigen Fehlermodus bis hin zur Validierung jedes Servers außerhalb der IDE, damit Sie erkennen können, ob das Problem im Server oder in Cursors Verbindung zu ihm liegt.

Schnelle Triage-Checkliste

Wenn sich ein MCP-Server fehlerhaft verhält, arbeiten Sie diese Tabelle von oben nach unten durch. Die meisten Probleme werden in den ersten drei Zeilen gelöst.

Symptom	Erste Prüfung	Typische Korrektur
Server rot oder startet nicht	Führen Sie den Server-Befehl manuell in einem Terminal aus	Befehlspfad, fehlende Laufzeit oder Umgebungsvariablen korrigieren
Tools fehlen oder sind veraltet	Haben Sie mcp.json bearbeitet, ohne neu zu starten?	Cursor neu starten oder das Fenster neu laden
Disconnect-Schaltfläche tut nichts	Ist der Prozess tatsächlich beendet?	Prozess manuell beenden, dann neu verbinden
Server fehlerhaft und wiederholt nie	Cursor wiederholt nach manchen Fehlern nicht automatisch	Server aus- und einschalten oder neu starten
Anfragen hängen und laufen dann in ein Timeout	Server-Start oder Tool-Laufzeit ist zu langsam	Abhängigkeiten vorwärmen, Timeout erhöhen
Authentifizierungsfehler	Token abgelaufen oder Umgebungsvariable fehlt	Token erneuern, Umgebung korrigieren

Server startet nicht

Der häufigste MCP-Fehler ist der einfachste: Der Befehl, den Cursor zum Starten des Servers verwendet, funktioniert tatsächlich nicht. Cursor startet exakt den Befehl aus Ihrer mcp.json mit der Umgebung, die Sie ihm gegeben haben, und wenn das fehlschlägt, erscheint der Server nie.

Fehlerhafter Befehlspfad

Prüfen Sie den Befehl exakt so, wie Cursor ihn ausführen würde. Wenn mcp.json command": "npx" angibt, Ihr PATH innerhalb des Cursor-Prozesses aber kein npx enthält, schlägt der Start fehl. Unter Windows ist dies besonders häufig, weil GUI-Anwendungen einen anderen PATH erben als Ihr Terminal.

{
  "mcpServers": {
    "filesystem": {
      "command": "C:\\Program Files\\nodejs\\npx.cmd",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "C:\\projects"]
    }
  }
}

Die Verwendung des absoluten Pfads zur ausführbaren Datei ist die zuverlässige Korrektur unter Windows. Unter macOS und Linux gibt which npx den absoluten Pfad an, wenn der bloße Befehl nicht gefunden wird.

npx oder uvx fehlt

Viele MCP-Server werden als npm- oder Python-Pakete ausgeliefert und über npx oder uvx gestartet. Wenn die Laufzeit nicht installiert ist, kann der Server nicht starten:

# Verify the runtimes exist
node --version    # Node 18+ for npx-based servers
npx --version
python --version
uvx --version     # install with: pip install uv

Wenn uvx fehlt, installieren Sie es und starten Sie Ihr Terminal und Cursor neu, damit der aktualisierte PATH übernommen wird.

Falsche Umgebungsvariablen

Ein Server, der einen API-Schlüssel benötigt, startet oft und beendet sich sofort wieder oder startet und gibt bei jedem Tool-Aufruf Fehler zurück, wenn seine Umgebung falsch ist. Lesen Sie die Dokumentation des Servers auf die exakten Variablennamen und bedenken Sie, dass Cursor nur weitergibt, was Sie im env-Block auflisten:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_PAT}"
      }
    }
  }
}

Tools werden nach dem Bearbeiten von mcp.json nicht neu geladen

Sie bearbeiten mcp.json, speichern sie, öffnen die Tool-Liste, und die neuen Tools sind nicht da. Die MCP-Konfiguration wird beim Start des Server-Prozesses gelesen, daher werden Bearbeitungen nicht in jeder Situation hot-reloaded.

1. Speichern Sie die Datei und bestätigen Sie, dass sie gültiges JSON ist. Ein abschließendes Komma macht die gesamte Datei unparsbar und jeder Server kann fehlschlagen.
2. Starten Sie Cursor vollständig neu oder laden Sie das Fenster neu, wenn Ihre Version eine Neuladeoption in der Befehlspalette bietet.
3. Öffnen Sie das MCP-Einstellungsfenster und bestätigen Sie, dass der Server als verbunden angezeigt wird.
4. Starten Sie einen neuen Chat. Eine bestehende Unterhaltung hat möglicherweise die alte Tool-Liste zwischengespeichert, sodass neue Tools nur in frischen Sitzungen erscheinen.

Neustart schlägt Aktualisierung

Wenn das Aus- und Einschalten des Servers im MCP-Fenster Ihre Änderungen nicht übernimmt, führen Sie einen vollständigen Fenster-Reload durch oder starten Sie Cursor neu. mcp.json wird beim Verbindungsaufbau gelesen, und ein veralteter Prozess liefert weiterhin seine ursprüngliche Tool-Liste, egal was die Datei jetzt sagt.

Verbindungs- und Wiederholungsprobleme

Die Disconnect-Schaltfläche tut nichts

Die Disconnect-Aktion stoppt Cursors Client-Seite der Verbindung, aber bei stdio-Servern kann der eigentliche Kindprozess überleben, wenn er nicht sauber herunterfährt. Das Ergebnis ist ein Server, der noch halb lebendig erscheint und eine saubere Neuverbindung verweigert. Wenn die Schaltfläche ignoriert zu werden scheint:

# Find and kill a stubborn stdio MCP server process
# macOS / Linux:
ps aux | grep mcp
kill <PID>

# Windows PowerShell:
Get-Process | Where-Object { $_.ProcessName -like "*npx*" -or $_.ProcessName -like "*uvx*" }
Stop-Process -Id <PID> -Force

Nachdem der Prozess beendet ist, verbinden Sie sich über das MCP-Fenster neu. Die nächste Verbindung startet einen frischen Prozess mit Ihrer aktuellen Konfiguration.

Keine Wiederholungen nach einem Server-Fehler

Wenn ein Server beim Start oder während der Initialisierung einen Fehler zurückgibt, wiederholt Cursor im Allgemeinen nicht weiter im Hintergrund. Der Server bleibt in einem fehlerhaften Zustand, bis Sie eingreifen. Die manuellen Neustartoptionen, in aufsteigender Reihenfolge der Härte:

1. Schalten Sie den Server im MCP-Einstellungsfenster aus und wieder ein.
2. Laden Sie das Cursor-Fenster neu, damit sich alle MCP-Server neu verbinden.
3. Beenden Sie Cursor vollständig und starten Sie ihn neu.
4. Wenn der Prozess festhängt, beenden Sie ihn wie oben gezeigt und verbinden Sie sich dann neu.

Timeouts bei langsamen Servern

Server, die beim ersten Lauf Abhängigkeiten herunterladen, oder Tools, die langsame externe APIs aufrufen, können das Standard-Timeout überschreiten und einen Fehler melden, der wie ein kaputter Server aussieht. Der klassische Fall ist ein npx-basierter Server bei seiner ersten Aufrufung, wenn npm das Paket lädt, bevor irgendetwas starten kann:

# Pre-warm an npx-based server so the first real connection is fast
npx -y @modelcontextprotocol/server-github --help

Für Timeouts auf Host-Ebene beachten viele MCP-Hosts, Cursor eingeschlossen, konventionelle Timeout-Umgebungsvariablen. Sie vor dem Start von Cursor zu setzen gibt langsamen Servern mehr Spielraum:

# macOS / Linux (add to your shell profile)
export MCP_TIMEOUT=30000        # server startup timeout in ms
export MCP_TOOL_TIMEOUT=120000  # individual tool call timeout in ms

Wenn ein Server immer noch zu langsam ist, hosten Sie ihn anders: Betreiben Sie ihn als persistenten lokalen Prozess und verbinden Sie sich über SSE oder HTTP, statt ihn pro Sitzung zu starten.

Transporttypen: stdio vs SSE/HTTP

Cursor unterstützt zwei MCP-Transportstile, und mehrere Fehlerbehebungsschritte unterscheiden sich zwischen ihnen.

Aspekt	stdio	SSE / HTTP
Wie es läuft	Cursor startet den Prozess	Server läuft separat, Cursor verbindet sich mit einer URL
Konfigurationsschlüssel	command, args, env	url (und Header, wo unterstützt)
Häufige Fehler	Falscher Befehlspfad, fehlende Laufzeit	Falsche URL, Auth-Header, CORS- oder Netzwerkprobleme
Neustartverhalten	Umschalten verbindet den Prozess neu	Neuverbindung erreicht den Remote-Endpunkt
Debugging	Führen Sie den Befehl manuell aus	Curlen Sie den Endpunkt, prüfen Sie die Server-Logs

{
  "mcpServers": {
    "local-stdio-server": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
    },
    "remote-http-server": {
      "url": "https://mcp.example.com/sse"
    }
  }
}

Bei SSE- und HTTP-Servern verifizieren Sie, dass der Endpunkt erreichbar ist, bevor Sie Cursor überhaupt anfassen:

# A plain GET should return something, even if it is an auth error
curl -i https://mcp.example.com/sse

Ein 401 oder 403 bedeutet, dass der Transport in Ordnung ist und Ihre Authentifizierung das Problem ist. Ein Timeout oder Connection refused bedeutet, dass der Server ausgefallen oder die URL falsch ist.

Umgebungsvariablen und Secrets

Projekt- vs globales mcp.json

Cursor liest die MCP-Konfiguration von zwei Stellen:

• Global: ~/.cursor/mcp.json (unter Windows: %USERPROFILE%\.cursor\mcp.json). Gilt für jedes Projekt. Legen Sie persönliche Server hierhin: Ihr GitHub-Token, Ihr Datenbank-Browser, Ihre Scraping-Tools.
• Projekt: .cursor/mcp.json innerhalb des Repositorys. Gilt nur für dieses Projekt und wird mit Teammitgliedern geteilt, wenn es committet wird. Legen Sie projektspezifische Server hierhin: ein Schema-MCP für die Datenbank dieses Repos, eine Design-Tool-Integration, die von dieser Codebasis verwendet wird.

Wenn ein Server an beiden Stellen definiert ist, gehen Sie davon aus, dass die Projektkonfiguration für dieses Projekt gilt. Wenn Tools dupliziert werden oder verschwinden, prüfen Sie beide Dateien auf einen Eintrag mit demselben Namen.

Secrets sicher übergeben

Cursor expandiert ${VAR_NAME}-Platzhalter im env-Block aus Ihrer Umgebung, sodass Secrets außerhalb von mcp.json leben können:

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "DATABASE_URL": "${MY_DATABASE_URL}"
      }
    }
  }
}

# Set the real value in your shell profile, not in the JSON file
export MY_DATABASE_URL="postgresql://user:password@localhost:5432/appdb"

Committen Sie keine Secrets ins Repository

Die .cursor/mcp.json auf Projektebene ist eine reguläre Datei in Ihrem Repo. Wenn sie einen wörtlichen API-Schlüssel enthält, bekommt jede Person und jeder Agent, der das Repository klont, den Schlüssel. Verwenden Sie ${VAR}-Expansion für alles Sensible und fügen Sie die Projekt-mcp.json zu .gitignore hinzu, wenn sie lokale Werte enthalten muss.

MCP-Logs lesen

Wenn das Symptom unklar ist, benennen die Logs meist das eigentliche Problem. Cursor gibt MCP-Aktivität über seine Output-Infrastruktur aus:

1. Öffnen Sie die Befehlspalette und führen Sie den Befehl zum Anzeigen des Ausgabefensters aus, oder verwenden Sie das Ansicht-Menü.
2. Wählen Sie im Kanal-Dropdown des Ausgabefensters den Kanal MCP oder Cursor MCP logs.
3. Lösen Sie die fehlschlagende Aktion aus und lesen Sie dann die neuesten Einträge. Suchen Sie nach Spawn-Fehlern, Exit-Codes ungleich Null und Stack-Traces aus dem stderr des Servers.

Typische Logzeilen und was sie bedeuten:

[MCP] spawn npx ENOENT                 -> the runtime was not found on PATH
[MCP] server exited with code 1        -> the server crashed; run it manually for the real error
[MCP] initialize timed out             -> slow startup; pre-warm or raise the timeout
[MCP] tool call rejected: invalid args -> the model sent a bad schema; check the tool input

Serverseitiges stderr wird in diese Logs weitergeleitet, sodass ein Python-Traceback oder eine Exception wegen einer fehlenden Abhängigkeit vom Server selbst hier meist wörtlich erscheint.

Einen Server eigenständig validieren

Der schnellste Weg, um zu beweisen, ob ein Problem bei Cursor oder beim Server liegt, ist, den Server ohne Cursor auszuführen.

Den Befehl manuell ausführen

Kopieren Sie command und args aus mcp.json und führen Sie sie in einem einfachen Terminal aus:

# Whatever your mcp.json launches, launch it yourself
npx -y @modelcontextprotocol/server-filesystem /tmp

Ein gesunder stdio-MCP-Server startet und wartet still auf JSON-RPC-Eingabe auf stdin. Wenn Sie stattdessen einen Command-not-found-Fehler, einen Absturz oder einen Fehler bei der Paketinstallation sehen, haben Sie das Problem gefunden und Cursor ist unschuldig. Tippen Sie ein paar Zeichen und drücken Sie Enter; eine bloße Protokoll-Fehlerantwort ist tatsächlich ein gutes Zeichen, weil sie beweist, dass der Prozess JSON-RPC spricht.

Den MCP Inspector verwenden

Der offizielle MCP inspector verbindet sich mit einem Server, listet seine Tools auf und lässt Sie sie interaktiv aufrufen:

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

Dies öffnet eine lokale Web-Oberfläche, in der Sie den Server initialisieren, Tools auflisten und eines mit handgeschriebenen Argumenten aufrufen können. Wenn ein Tool im Inspector funktioniert, aber nicht in Cursor, ist der Unterschied meist die Umgebung: Variablen, die in Ihrem Terminal vorhanden sind, aber im Cursor-Prozess fehlen, oder ein anderes Arbeitsverzeichnis. Wenn das Tool auch im Inspector fehlschlägt, korrigieren Sie zuerst den Server; nichts, was Sie in Cursor ändern, wird helfen.

Minimal funktionierende mcp.json

Verwenden Sie dies als Referenz, wenn Ihre Konfiguration in etwas abgedriftet ist, das nicht mehr startet. Sie zeigt einen stdio-Server und einen Remote-Server, mit Env-Expansion:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/you/projects"
      ]
    },
    "remote-search": {
      "url": "https://mcp.example.com/sse",
      "env": {
        "API_TOKEN": "${MY_MCP_TOKEN}"
      }
    }
  }
}

Checkliste zur Anpassung an Ihren Server:

1. Ersetzen Sie den Paketnamen und die Argumente durch die aus der Dokumentation des Servers.
2. Verwenden Sie unter Windows absolute Pfade zur ausführbaren Datei, wenn der bloße Befehl nicht gefunden wird.
3. Behalten Sie Secrets als ${VAR}-Platzhalter und setzen Sie die echten Werte in Ihrem Shell-Profil.
4. Validieren Sie das JSON, starten Sie dann Cursor neu und bestätigen Sie, dass der Server als verbunden angezeigt wird, bevor Sie einen Chat öffnen.

Ein fehlerhafter Eintrag kann die ganze Datei zerstören

mcp.json wird als ein einzelnes JSON-Dokument geparst. Ein einziges abschließendes Komma oder ein nicht in Anführungszeichen gesetzter Wert macht die gesamte Datei ungültig, und jeder Server darin kann gemeinsam nicht starten, auch die, die einwandfrei funktionierten. Wenn mehrere Server auf einmal ausfallen, verdächtigen Sie die Dateisyntax, bevor Sie jeden Server einzeln verdächtigen.

Kurzreferenz

Ziel	Tun Sie dies
Server rot nach Start	Führen Sie den Befehl manuell aus; korrigieren Sie Pfad, Laufzeit oder Env
Neue Tools erscheinen nicht	Laden Sie das Fenster neu und starten Sie dann einen frischen Chat
Disconnect reagiert nicht	Beenden Sie den Kindprozess und verbinden Sie sich dann neu
Wiederholte Fehler, keine Wiederholung	Schalten Sie den Server aus und ein oder starten Sie Cursor neu
Timeout beim ersten Lauf	Wärmen Sie das Paket vor, erhöhen Sie die Timeout-Env-Variablen
Verdacht auf den Server, nicht Cursor	Validieren Sie mit einem manuellen Lauf oder dem MCP inspector
Verdacht auf Cursor, nicht den Server	Vergleichen Sie Ihre Env mit einem Terminal und lesen Sie den Kanal MCP logs