Diese Seite wurde maschinell aus dem Englischen übersetzt. Englisches Original lesen.

Fehlerbehebung

Behebe häufige Unity-MCP-Probleme – keine Tools im KI-Client, Anmelde- und Verbindungsfehler, Server-Download-Fehler, NuGet-DLL-Fehler und Portkonflikte.

Aktualisiert am 4. November 2026 Als Markdown anzeigen

Diese Seite sammelt die Probleme, auf die Leute bei Unity MCP am häufigsten stoßen, und wie man sie behebt. Beginne mit der kurzen Checkliste; wenn das nicht hilft, suche unten nach deinem Symptom.

Kurze Checkliste

  1. Öffne Window > AI Game Developer — MCP und sieh dir die Timeline an: Unity, MCP server und AI agent sollten alle grün sein.
  2. Prüfe die Unity Console auf Fehler. Ein Kompilierfehler irgendwo im Projekt verhindert, dass die Editor-Skripte des Plugins geladen werden.
  3. Führe unity-mcp-cli status ./MyUnityProject aus, um zu sehen, ob Unity läuft und welcher Server erreichbar ist.
  4. Starte deinen KI-Client nach jeder Konfigurationsänderung neu.
  5. Stelle sicher, dass das Plugin und deine Erweiterungen auf aktuellen Versionen sind.

Der KI-Client zeigt keine Unity-Tools

  • Der Client hat sich verbunden, bevor Unity bereit war. Verbinde den MCP-Server im Client neu (in Claude Code /mcp) oder starte den Client neu, nachdem das Fenster Connected anzeigt.
  • Der Client wurde nicht konfiguriert oder verwendet eine alte Konfiguration. Klicke im Fenster auf Configure (oder Reconfigure) für deinen Agent oder führe unity-mcp-cli setup-mcp <agent> . aus und starte dann den Client neu.
  • Im Cloud-Modus ist man nicht angemeldet. Das Fenster zeigt "Authorization Required". Klicke auf Authorize und bestätige den Code im Browser.
  • Es sind mehrere Projekte geöffnet. Eine nicht angeheftete https://ai-game.dev/mcp-URL kann zu einem anderen Editor führen. Verwende die angeheftete URL, die Configure schreibt.
  • Der Agent wird aus einem anderen Ordner gestartet. Projektbezogene Konfigurationen wie .mcp.json oder .cursor/mcp.json werden nur gelesen, wenn der Client im Unity-Projektordner läuft.
  • In VS Code schalte Copilot Chat in den Agent-Modus.

Probleme bei der Cloud-Anmeldung

  • "Authorization Required" kommt immer wieder. Dein Zugangsdatum ist abgelaufen oder wurde widerrufen. Klicke erneut auf Authorize oder führe unity-mcp-cli login --force aus.
  • "Connection Required". Die Anmeldung hat funktioniert, aber Unity ist nicht verbunden. Klicke auf Connect.
  • Mit dem falschen Konto angemeldet. Klicke auf Revoke (damit werden alle AI Game Dev-Tools auf dem Rechner abgemeldet) und dann mit dem richtigen Konto auf Authorize. unity-mcp-cli login fragt vor dem Kontowechsel nach.

Sitzungs- und Geräteverwaltung für dein Konto wird in Authentication beschrieben.

Der lokale MCP-Server startet nicht (Custom-Modus)

  • Die Binärdatei wurde nicht heruntergeladen. Sie landet in Library/mcp-server/<platform>/. Wenn der Download fehlgeschlagen ist (offline, Firewall, Proxy), zeigt das Fenster "Server binary error" und eine Schaltfläche Download / Retry server. Du kannst auch Tools > AI Game Developer > Server > Download Binaries verwenden.
  • Antivirus hat die ausführbare Datei blockiert. Erlaube gamedev-mcp-server in deiner Sicherheitssoftware und versuche es dann erneut.
  • Der Transport ist stdio. Bei stdio startet der KI-Agent den Server selbst, daher ist die Schaltfläche Start deaktiviert. Wechsle zu http, wenn Unity ihn ausführen soll.
  • Lies die Server-Logs. Verwende Tools > AI Game Developer > Server > Open Logs und Open Log Errors.
  • Teste den Server direkt. Tools > AI Game Developer > Server > Launch MCP Inspector öffnet den MCP Inspector gegen den lokalen Server (nur HTTP-Transport; benötigt Node.js).

Portkonflikte

Jedes Projekt erhält einen festen Port zwischen 20000 und 29999, der aus seinem Pfad abgeleitet wird. Wenn bereits etwas anderes darauf lauscht, zeigt das Fenster den MCP-Server als External an. Finde den Prozess:

netstat -ano | findstr :<port>
lsof -i :<port>

Beende diesen Prozess oder trenne die Verbindung und gib einen anderen Port in Server URL ein (zum Beispiel http://localhost:25000), und klicke dann erneut auf Configure, damit der Agent den neuen Port verwendet.

Verbindungsabbrüche während der Kompilierung

Unity lädt Skripte nach jeder Codeänderung und beim Betreten des Play-Modus neu. Das Plugin trennt die Verbindung vor dem Neuladen und verbindet sie danach wieder, daher ist ein kurzes "Disconnected" oder "Connecting..." normal. Ein Tool-Aufruf, der während des Neuladens lief, kann fehlschlagen; bitte den Agent, ihn erneut zu versuchen.

Kompilierfehler oder fehlende DLLs nach der Installation

Das Plugin lädt seine .NET-Abhängigkeiten von NuGet nach Assets/Plugins/NuGet herunter.

  • Fehler über fehlende Typen aus McpPlugin, ReflectorNet oder SignalR. Warte, bis der erste Import abgeschlossen ist, und verwende dann Tools > AI Game Developer > Dependencies > Force Resolve NuGet DLLs.
  • "Path too long" unter Windows. Die Unity-Laufzeit kann keine DLLs öffnen, die das 260-Zeichen-Pfadlimit von Windows überschreiten, selbst wenn lange Pfade aktiviert sind. Verschiebe das Projekt in einen kürzeren Ordner, etwa C:/Projects/MyGame.
  • Saubere Neuinstallation. Schließe Unity, lösche Assets/Plugins/NuGet und die zugehörige .meta-Datei und öffne das Projekt erneut.

Projektpfad mit Leerzeichen

Wenn die Console "The project path contains spaces" anzeigt, verschiebe das Projekt in einen Ordner ohne Leerzeichen. Das Plugin warnt, weil solche Pfade bei der Verwendung Probleme verursachen können.

Tool-Aufrufe schlagen fehl oder laufen in einen Timeout

  • Fehler wie "object not found". Bitte den Agent, zuerst abzufragen (zum Beispiel mit rql-query), statt Namen oder Pfade zu raten. Asset-Pfade beginnen mit Assets/.
  • Lange Vorgänge laufen in einen Timeout. Erhöhe Tool timeout (ms) im Fenster (Standard 300000) für langsame Bakes oder große Testläufe.
  • Screenshots schlagen im Batch-Modus fehl. Ein Editor, der mit -nographics gestartet wurde, hat kein Grafikgerät. Starte headless ohne -nographics; unity-mcp-cli open --headless macht das bereits.
  • Ein benutzerdefiniertes Tool wirft Thread-Fehler. Packe Unity-API-Aufrufe in MainThread.Instance.Run. Siehe Custom tools.

Probleme mit unity-mcp-cli

  • open bleibt bei "Enter Safe Mode?" stehen. Die CLI klickt automatisch auf Ignore. Unter macOS erteile deinem Terminal die Bedienungshilfen-Berechtigung; unter Linux installiere xdotool.
  • exec wartet und gibt dann auf. Das Projekt ist in einem Editor geöffnet, den die CLI nicht gestartet hat, und sein Plugin antwortet nicht lokal (zum Beispiel ist es mit der Cloud verbunden). Verbinde das Plugin, stelle es auf Custom um oder übergib --url.
  • setup-skills schlägt fehl. Es benötigt einen laufenden Editor mit verbundenem Plugin. Führe zuerst open und wait-for-ready aus.
  • Verwende --verbose bei jedem Befehl für ausführliche Logs.

Vollständiger Reset

  1. Schließe Unity.
  2. Lösche Library/mcp-server/ im Projekt.
  3. Öffne Unity erneut und wähle Tools > AI Game Developer > Reset Config.
  4. Melde dich erneut an (Cloud) oder starte den Server (Custom) und klicke dann für deinen Agent auf Configure.
  5. Starte deinen KI-Client neu.

Hilfe erhalten

Verwende Help / Talk (Discord) oder Bug Report (GitHub issues) am unteren Rand des AI Game Developer-Fensters. Gib deine Unity-Version, dein Betriebssystem, die Plugin-Version (wird im Fenster angezeigt), den Fehler aus der Console und die Schritte zur Reproduktion an. Du kannst auch die FAQ oder die websiteweite FAQ durchsuchen.