# Fehlerbehebung — Unity · AI Game Developer Wiki Behebe häufige Unity-MCP-Probleme – keine Tools im KI-Client, Anmelde- und Verbindungsfehler, Server-Download-Fehler, NuGet-DLL-Fehler und Portkonflikte. Diese Seite wurde maschinell aus dem Englischen übersetzt. [Englisches Original lesen](https://ai-game.dev/docs/wiki/unity/troubleshooting). 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 .` 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](https://ai-game.dev/docs/auth) beschrieben. ## Der lokale MCP-Server startet nicht (Custom-Modus) - **Die Binärdatei wurde nicht heruntergeladen.** Sie landet in `Library/mcp-server//`. 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: ```powershell netstat -ano | findstr : ``` ```bash lsof -i : ``` 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](https://ai-game.dev/de/docs/wiki/unity/custom-tools#main-thread). ## 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](https://ai-game.dev/de/docs/wiki/unity/faq) oder die websiteweite [FAQ](https://ai-game.dev/docs/faq) durchsuchen. --- Source (HTML): https://ai-game.dev/de/docs/wiki/unity/troubleshooting Machine-translated (de) from the English page: https://ai-game.dev/docs/wiki/unity/troubleshooting