Fehlerbehebung

Diese Seite listet die Probleme auf, die bei Unreal MCP am häufigsten auftreten, und wie du sie behebst. Beginne mit den Schnellchecks und springe dann zum passenden Abschnitt.

Schnellchecks#

1. Ist das Plugin geladen? Im Output Log sollte nach dem Start des Editors [Unreal-MCP] plugin loaded stehen.
2. Was zeigt das Fenster an? Öffne Tools, AI Game Developer und lies die Statuszeile (Connected, Connecting, Reconnecting, Disconnected oder No MCP bridge).
3. Was sieht die CLI? Führe unreal-mcp-cli status --path ./YourProject aus.
4. Lies das Log. Nutze Open log file im Fenster, filtere das Output Log nach der Kategorie LogUnrealMcp oder frage den Agenten nach console | where Verbosity == "Error".

Das Plugin lädt nicht#

Wenn keine Zeile [Unreal-MCP] plugin loaded erscheint, konnte das Editor-Modul nicht starten.

• Suche im Output Log nach einem Startfehler des Plugins oder nach einer beschädigten .uplugin.
• Stelle sicher, dass das Projekt ein C++-Projekt mit funktionierender Compiler-Toolchain ist. Siehe Installation.
• Wenn Unreal meldet, dass Module fehlen oder das Plugin inkompatibel ist, lasse es neu bauen, oder öffne das Projekt mit unreal-mcp-cli open ./YourProject, das zuerst die nativen Module baut und diese Hinweise wegklickt.

Ein Update zeigt keine Wirkung#

Der inkrementelle Build von Unreal kann alten Plugin-Code behalten, wenn sich der Quellcode des Plugins ändert, aber sein alter Ordner Intermediate/ erhalten bleibt.

• Aktualisiere mit unreal-mcp-cli update ./YourProject, das den Build-Cache standardmäßig bereinigt.
• Nach einem manuellen Kopieren: Schließe den Editor, lösche Plugins/UnrealMCP/Intermediate/ und die C++-Dateien in Plugins/UnrealMCP/Binaries/ (behalte Binaries/ThirdParty/) und öffne ihn dann erneut.

"No MCP bridge" oder die Bridge startet immer wieder neu#

Das Plugin benötigt seinen Bridge-Prozess unreal-mcp-bridge. Das Fenster zeigt den Bridge-Status und einen Neustart-Zähler.

• Wenn im Log no sidecar binary resolved for rid <rid> steht, wurde keine Bridge gefunden.
  • App- oder CLI-Installation: Die Bridge ist mitgeliefert. Installiere sie mit unreal-mcp-cli install-plugin ./YourProject neu (oder über die App); möglicherweise fehlt in dem Paket deine Plattform.
  • Source-Checkout: Baue eine mit unreal-mcp-cli bootstrap-local ./YourProject oder setze UNREAL_MCP_BRIDGE_PATH.
• Klicke in der Fußzeile des Fensters auf Restart bridge, nachdem du die Ursache behoben hast.

Hängt bei "Connecting" oder "Reconnecting"#

• Cloud-Modus: Prüfe, ob du angemeldet bist. Wenn das Fenster "Sign in required" anzeigt, ist deine gespeicherte Anmeldung abgelaufen; klicke auf Authorize und bestätige den neuen Code.
• Prüfe, ob die Maschine ai-game.dev erreichen kann (Proxy- oder Firewall-Regeln).
• Custom-Modus: Stelle sicher, dass der lokale Server läuft (Start in der MCP-Server-Karte oder --start-server) und dass die Server URL darauf verweist.
• Nutze Disconnect und dann Connect oder Restart bridge.

Lokaler Server meldet "No connected clients"#

Wenn ein lokaler gamedev-mcp-server No connected clients. Retrying loggt und dann mit HTTP 500 antwortet, ist der Editor noch im Modus Cloud und mit ai-game.dev statt mit deinem lokalen Server verbunden. Wechsle im Fenster auf Custom, setze UNREAL_MCP_CONNECTION_MODE=Custom oder übergib --connection-mode Custom (oder --host) an unreal-mcp-cli open.

Der AI-Agent hat keine Unreal-Tools#

• Prüfe die Konfiguration des Agenten: Führe unreal-mcp-cli setup-mcp <agent> --path ./YourProject --dry-run aus und vergleiche, oder klicke im Bereich für den AI-Agenten auf Configure (oder Reconfigure).
• Starte oder lade den Agenten nach den Konfigurationsänderungen neu. Viele Clients lesen MCP-Konfigurationen nur beim Start.
• Claude Code liest .mcp.json aus dem Ordner, in dem du es startest; starte es daher im Projektordner.
• Wenn du mit setup-mcp konfiguriert hast, bevor du den Editor jemals geöffnet hast, verweist die Konfiguration möglicherweise auf localhost statt auf die Cloud. Öffne das Projekt einmal und führe dann setup-mcp erneut aus, oder übergib --url.
• Prüfe die Zeile AI agents im Bereich Connection. Wenn dein Agent dort nicht aufgeführt ist, ist er nicht mit demselben Server wie der Editor verbunden.
• Wenn du Tools im Fenster MCP Tools ausgeblendet oder UNREAL_MCP_TOOLS gesetzt hast, sieht der Agent weniger Tools.

Der Agent erreicht den falschen Editor#

Wenn mehrere Editoren unter einem Konto laufen, nutze die projektgebundene URL (/mcp/p/<pin>), die setup-mcp standardmäßig schreibt. Führe setup-mcp erneut ohne --no-pin aus. Siehe Connecting AI clients.

401-Fehler im Agenten#

• Im Cloud-Modus muss sich der Agent bei einer reinen URL-Konfiguration selbst anmelden. Lass ihn entweder seinen OAuth-Sign-in ausführen oder melde die Maschine an (unreal-mcp-cli login) und führe setup-mcp erneut aus, damit die Konfiguration einen Projektschlüssel enthält.
• Wenn der Projektschlüssel widerrufen wurde, verwende Regenerate key im Editor oder setup-mcp --regenerate-key.
• Im Custom-Modus mit token-Authentifizierung muss die Konfiguration dasselbe Token enthalten wie der Editor. Verwende Reconfigure, nachdem du ein neues Token erzeugt hast.

Tool-Aufrufe laufen in ein Timeout#

Ein Tool-Aufruf darf standardmäßig 5 Minuten laufen. Erhöhe UNREAL_MCP_TOOL_TIMEOUT (Millisekunden) für lange Python-Skripte oder große Importe. python-execute hat außerdem ein eigenes timeout (Standard 30 Sekunden), das der Agent pro Aufruf setzen kann.

Screenshot-Tools geben einen Fehler zurück#

Pixel-Capture benötigt einen Editor mit GPU-Unterstützung. Unter -nullrhi geben die Screenshot-Tools einen strukturierten Fehler zurück. unreal-mcp-cli exec und open --headless starten Editoren, die off-screen rendern, daher funktionieren Aufnahmen dort weiterhin.

Python-Tools schlagen fehl#

python-execute verwendet Unreals Python Editor Script Plugin, das Unreal MCP aktiviert. Wenn Python nicht verfügbar ist, prüfe, ob das Plugin unter Edit, Plugins aktiviert ist. Fehler verweisen auf Zeilen von snippet.py, also den Code, den der Agent gesendet hat.

Erweiterung wird nicht angezeigt#

• Erweiterungen benötigen Unreal Engine 5.7 oder neuer und Unreal MCP 0.26.0 oder neuer.
• Nach der Installation muss die Erweiterung kompiliert werden: Öffne den Editor erneut, verwende --build oder Compile (Live Coding) im Abschnitt Extensions.
• Prüfe, ob die Erweiterung im Abschnitt Extensions aktiviert ist.

Immer noch nicht weiter?#

• Siehe die FAQ und die allgemeine FAQ.
• Verwende Help / Talk im Fenster, um auf Discord zu fragen, oder Bug Report, um ein GitHub-Issue zu öffnen. Gib die Unreal-Version, dein Betriebssystem, die Statuszeile des Fensters und die relevanten Logzeilen an (niemals deine Tokens).