Unity Editor MCP Server

MCP Unity Editor (Spiele-Engine)

MCP Unity ist eine Implementierung des Model Context Protocol für den Unity Editor und ermöglicht KI-Assistenten die Interaktion mit Ihren Unity-Projekten. Dieses Paket bildet eine Brücke zwischen Unity und einem Node.js-Server, der das MCP-Protokoll implementiert. Dadurch können KI-Agenten wie Claude, Windsurf und Cursor Operationen im Unity Editor ausführen.

Merkmale

IDE-Integration – Paket-Cache-Zugriff

MCP Unity ermöglicht die automatische Integration mit VSCode-ähnlichen IDEs (Visual Studio Code, Cursor, Windsurf), indem der Ordner Unity Library/PackedCache zu Ihrem Arbeitsbereich hinzugefügt wird. Diese Funktion:

• Verbessert die Code-Intelligenz für Unity-Pakete
• Ermöglicht eine bessere Autovervollständigung und Typinformationen für Unity-Pakete
• Hilft KI-Codierungsassistenten, die Abhängigkeiten Ihres Projekts zu verstehen

MCP-Servertools

Zum Bearbeiten und Abfragen von Unity-Szenen und GameObjects über MCP stehen die folgenden Tools zur Verfügung:

• execute_menu_item : Führt Unity-Menüelemente aus (Funktionen, die mit dem Attribut „MenuItem“ gekennzeichnet sind)

  Beispiel-Eingabeaufforderung: „Führen Sie den Menüpunkt ‚GameObject/Create Empty‘ aus, um ein neues leeres GameObject zu erstellen.“

• select_gameobject : Wählt Spielobjekte in der Unity-Hierarchie nach Pfad oder Instanz-ID aus

  Beispielaufforderung: „Wählen Sie das Hauptkameraobjekt in meiner Szene aus.“

• update_gameobject : Aktualisiert die Kerneigenschaften eines GameObjects (Name, Tag, Ebene, aktiver/statischer Status) oder erstellt das GameObject, wenn es nicht existiert

  Beispiel-Eingabeaufforderung: „Setzen Sie das Tag des Player-Objekts auf ‚Enemy‘ und machen Sie es inaktiv.“

• update_component : Aktualisiert Komponentenfelder in einem GameObject oder fügt sie dem GameObject hinzu, wenn es die Komponente nicht enthält

  Beispiel-Eingabeaufforderung: „Fügen Sie dem Player-Objekt eine Rigidbody-Komponente hinzu und setzen Sie ihre Masse auf 5.“

• add_package : Installiert neue Pakete im Unity Package Manager

  Beispiel-Eingabeaufforderung: „Fügen Sie das TextMeshPro-Paket zu meinem Projekt hinzu.“

• run_tests : Führt Tests mit dem Unity Test Runner aus

  Beispiel-Eingabeaufforderung: „Alle EditMode-Tests in meinem Projekt ausführen“

• send_console_log : Senden Sie ein Konsolenprotokoll an Unity

  Beispiel-Eingabeaufforderung: „Senden Sie ein Konsolenprotokoll an den Unity Editor“

• add_asset_to_scene : Fügt der Unity-Szene ein Asset aus der AssetDatabase hinzu

  Beispiel-Eingabeaufforderung: „Fügen Sie das Player-Prefab aus meinem Projekt zur aktuellen Szene hinzu.“

MCP-Serverressourcen

• unity://menu-items : Ruft eine Liste aller verfügbaren Menüelemente im Unity-Editor ab, um das Tool execute_menu_item zu vereinfachen

  Beispiel-Eingabeaufforderung: „Zeigen Sie mir alle verfügbaren Menüelemente im Zusammenhang mit der Erstellung von GameObjects.“

• unity://scenes-hierarchy : Ruft eine Liste aller Spielobjekte in der aktuellen Unity-Szenenhierarchie ab

  Beispiel-Eingabeaufforderung: „Zeigen Sie mir die aktuelle Hierarchiestruktur der Szenen.“

• unity://gameobject/{id} : Ruft detaillierte Informationen zu einem bestimmten GameObject anhand der Instanz-ID oder des Objektpfads in der Szenenhierarchie ab, einschließlich aller GameObject-Komponenten mit ihren serialisierten Eigenschaften und Feldern

  Beispiel-Eingabeaufforderung: „Holen Sie mir detaillierte Informationen zum Player-GameObject.“

• unity://logs : Ruft eine Liste aller Protokolle von der Unity-Konsole ab

  Beispiel-Eingabeaufforderung: „Zeigen Sie mir die letzten Fehlermeldungen der Unity-Konsole.“

• unity://packages : Ruft Informationen über installierte und verfügbare Pakete vom Unity Package Manager ab

  Beispiel-Eingabeaufforderung: „Listen Sie alle Pakete auf, die derzeit in meinem Unity-Projekt installiert sind.“

• unity://assets : Ruft Informationen zu Assets in der Unity Asset-Datenbank ab

  Beispiel-Eingabeaufforderung: „Alle Textur-Assets in meinem Projekt finden“

• unity://tests/{testMode} : Ruft Informationen zu Tests im Unity Test Runner ab

  Beispiel-Eingabeaufforderung: „Liste alle verfügbaren Tests in meinem Unity-Projekt auf“

Anforderungen

• Unity 2022.3 oder höher – um den Server zu installieren
• Node.js 18 oder höher – zum Starten des Servers
• npm 9 oder höher – zum Debuggen des Servers

Installation

Die Installation dieses MCP Unity Servers ist ein mehrstufiger Prozess:

Schritt 1: Installieren Sie das Unity MCP Server-Paket über den Unity Package Manager

1. Öffnen Sie den Unity-Paketmanager (Fenster > Paketmanager).
2. Klicken Sie oben links auf die Schaltfläche "+"
3. Wählen Sie „Paket von Git-URL hinzufügen …“
4. Geben Sie ein: https://github.com/CoderGamester/mcp-unity.git
5. Klicken Sie auf „Hinzufügen“

Schritt 2: Installieren Sie Node.js

Um den MCP Unity-Server auszuführen, muss Node.js 18 oder höher auf Ihrem Computer installiert sein:

1. Besuchen Sie die Node.js-Downloadseite
2. Laden Sie den Windows Installer (.msi) für die LTS-Version herunter (empfohlen)
3. Führen Sie das Installationsprogramm aus und folgen Sie dem Installationsassistenten
4. Überprüfen Sie die Installation, indem Sie PowerShell öffnen und Folgendes ausführen:
   node --version
5. Besuchen Sie die Node.js-Downloadseite
6. Laden Sie das macOS-Installationsprogramm (.pkg) für die LTS-Version herunter (empfohlen)
7. Führen Sie das Installationsprogramm aus und folgen Sie dem Installationsassistenten
8. Wenn Sie Homebrew installiert haben, können Sie alternativ Folgendes ausführen:
   brew install node@18
9. Überprüfen Sie die Installation, indem Sie das Terminal öffnen und Folgendes ausführen:
   node --version

Schritt 3: AI LLM-Client konfigurieren

1. Öffnen Sie den Unity-Editor
2. Navigieren Sie zu Tools > MCP Unity > Serverfenster
3. Klicken Sie auf die Schaltfläche "Konfigurieren" für Ihren AI LLM-Client, wie im Bild unten gezeigt

4. Bestätigen Sie die Installation der Konfiguration mit dem angezeigten Popup

Öffnen Sie die MCP-Konfigurationsdatei Ihres AI-Clients (z. B. claude_desktop_config.json in Claude Desktop) und kopieren Sie den folgenden Text:

Ersetzen Sie ABSOLUTE/PATH/TO durch den absoluten Pfad zu Ihrer MCP Unity-Installation oder kopieren Sie einfach den Text aus dem MCP-Serverfenster des Unity Editors (Tools > MCP Unity > Serverfenster).

Starten Sie den Unity Editor MCP-Server

1. Öffnen Sie den Unity-Editor
2. Navigieren Sie zu Tools > MCP Unity > Serverfenster
3. Klicken Sie auf „Server starten“, um den WebSocket-Server zu starten
4. Öffnen Sie Claude Desktop oder Ihre AI Coding IDE (z. B. Cursor IDE, Windsurf IDE usw.) und starten Sie die Ausführung der Unity-Tools

Wenn der AI-Client eine Verbindung zum WebSocket-Server herstellt, wird er automatisch im grünen Feld im Fenster angezeigt

Optional: WebSocket-Port festlegen

Standardmäßig läuft der WebSocket-Server auf Port 8090. Sie können diesen Port auf zwei Arten ändern:

1. Öffnen Sie den Unity-Editor
2. Navigieren Sie zu Tools > MCP Unity > Serverfenster
3. Ändern Sie den Wert "WebSocket Port" auf die gewünschte Portnummer
4. Unity richtet die Systemumgebungsvariable UNITY_PORT auf die neue Portnummer ein
5. Starten Sie den Node.js-Server neu
6. Klicken Sie erneut auf „Server starten“, um den Unity Editor-Websocket wieder mit dem Node.js MCP-Server zu verbinden
7. Legen Sie die Umgebungsvariable UNITY_PORT im Terminal fest
   • Powershell GXP6
   • Eingabeaufforderung/Terminal GXP7
8. Starten Sie den Node.js-Server neu
9. Klicken Sie erneut auf „Server starten“, um den Unity Editor-Websocket wieder mit dem Node.js MCP-Server zu verbinden

Optional: Timeout festlegen

Standardmäßig beträgt das Timeout zwischen dem MCP-Server und dem WebSocket 10 Sekunden. Sie können es je nach verwendetem Betriebssystem ändern:

1. Öffnen Sie den Unity-Editor
2. Navigieren Sie zu Tools > MCP Unity > Serverfenster
3. Ändern Sie den Wert "Anforderungs-Timeout (Sekunden)" auf die gewünschten Timeout-Sekunden
4. Unity richtet die Systemumgebungsvariable UNITY_REQUEST_TIMEOUT auf den neuen Timeout-Wert ein
5. Starten Sie den Node.js-Server neu
6. Klicken Sie erneut auf „Server starten“, um den Unity Editor-Websocket wieder mit dem Node.js MCP-Server zu verbinden

Für Nicht-Windows-Betriebssysteme müssen Sie zwei Stellen konfigurieren:

Im Editor-Prozess-Timeout

1. Öffnen Sie den Unity-Editor
2. Navigieren Sie zu Tools > MCP Unity > Serverfenster
3. Ändern Sie den Wert "Anforderungs-Timeout (Sekunden)" auf die gewünschten Timeout-Sekunden

WebSocket-Timeout

1. Legen Sie die Umgebungsvariable UNITY_REQUEST_TIMEOUT im Terminal fest
   • Powershell GXP8
   • Eingabeaufforderung/Terminal GXP9
2. Starten Sie den Node.js-Server neu
3. Klicken Sie erneut auf „Server starten“, um den Unity Editor-Websocket wieder mit dem Node.js MCP-Server zu verbinden

[!TIPP]
Das Timeout zwischen Ihrer AI Coding IDE (z. B. Claude Desktop, Cursor IDE, Windsurf IDE) und dem MCP-Server hängt von der IDE ab.

Debuggen des Servers

Der MCP Unity-Server wird mit Node.js erstellt. Dazu muss der TypeScript-Code im build -Verzeichnis in JavaScript kompiliert werden. Um den Server zu erstellen, öffnen Sie ein Terminal und:

1. Navigieren Sie zum Serververzeichnis:
   cd ABSOLUTE/PATH/TO/mcp-unity/Server~
2. Installieren Sie Abhängigkeiten:
   npm install
3. Erstellen Sie den Server:
   npm run build
4. Führen Sie den Server aus:
   node build/index.js

Debuggen Sie den Server mit @modelcontextprotocol/inspector :

• PowerShell

• Eingabeaufforderung/Terminal

Vergessen Sie nicht, den Server mit Ctrl + C herunterzufahren, bevor Sie das Terminal schließen oder es mit dem MCP Inspector debuggen.

1. Aktivieren Sie die Protokollierung auf Ihrem Terminal oder in einer log.txt-Datei:
   • Powershell GXP16
   • Eingabeaufforderung/Terminal GXP17

Fehlerbehebung

• Stellen Sie sicher, dass der WebSocket-Server ausgeführt wird (überprüfen Sie das Serverfenster in Unity).
• Senden Sie eine Konsolenprotokollnachricht vom MCP-Client, um eine erneute Verbindung zwischen MCP-Client und Unity-Server zu erzwingen
• Ändern Sie die Portnummer im MCP-Serverfenster des Unity-Editors. (Tools > MCP Unity > Serverfenster)
• Überprüfen Sie die Unity-Konsole auf Fehlermeldungen
• Stellen Sie sicher, dass Node.js ordnungsgemäß installiert und in Ihrem PATH zugänglich ist
• Überprüfen Sie, ob alle Abhängigkeiten im Serververzeichnis installiert sind

Das Tool run_tests gibt die folgende Antwort zurück:

Dieser Fehler tritt auf, weil die Bridge-Verbindung verloren geht, wenn die Domäne beim Wechsel in den Wiedergabemodus neu geladen wird.
Die Problemumgehung besteht darin, „Domäne neu laden“ unter „Bearbeiten > Projekteinstellungen > Editor > „Einstellungen für den Wiedergabemodus eingeben“ zu deaktivieren.

Support und Feedback

Wenn Sie Fragen haben oder Unterstützung benötigen, öffnen Sie bitte ein Problem in diesem Repository.

Alternativ können Sie uns erreichen unter:

• Linkedin:
• Discord: gamester7178
• E-Mail: game.gamester@gmail.com

Beitragen

Beiträge sind willkommen! Senden Sie uns gerne einen Pull Request oder eröffnen Sie ein Issue mit Ihrer Anfrage.

Übernehmen Sie Ihre Änderungen im konventionellen Commit- Format.

Lizenz

Dieses Projekt steht unter der MIT-Lizenz

Danksagung

• Modellkontextprotokoll
• Unity Technologies
• Node.js
• WebSocket-Sharp