Unity MCP Server

Ein MCP-Server für den Unity Editor. Ermöglicht KI-Agenten wie Claude Code, Ihr Projekt zu inspizieren, zu manipulieren, zu testen und Screenshots davon zu erstellen.

Highlights

• 73 Werkzeuge: Szenen, GameObjects, Komponenten, Prefabs, Transforms, Tests, Reflection + Dekompilierung, C#-Eval, UI-Erfassung

• Clients ohne Konfiguration: ein Klick (oder ein Befehl) pro Rechner, danach verbinden sich jedes Projekt und jeder Editor automatisch. Keine Ports, keine Tokens, keine projektspezifische Konfiguration

• Multi-Editor-sicher: Jedes geöffnete Projekt läuft mit seinem eigenen Server. Sitzungen werden automatisch zum richtigen Server weitergeleitet

• MCP-Ressourcen – Konsolen-Logs, Szenenhierarchie, testergebnisse, Projektdateien

• Unity 2022.3+ (Unity 6 empfohlen), Node.js 18+

Related MCP server: Unity MCP Server

Installation

Paketmanager > + > Paket aus Git-URL hinzufügen:

https://github.com/Singtaa/UnityMCP.git

Oder klonen / als Submodul in Packages/com.singtaa.unity-mcp einbinden.

Einrichtung (einmal pro Rechner)

1. Öffnen Sie das Projekt in Unity. Der Server startet automatisch, der Launcher wird nach ~/.unity-mcp/stdio.js bereitgestellt

2. Fenster > Unity MCP Server > Claude Code einrichten

Fertig. Das Terminal-Äquivalent:

# macOS / Linux
claude mcp add --scope user --transport stdio unity -- node ~/.unity-mcp/stdio.js

# Windows
claude mcp add --scope user --transport stdio unity -- node "%USERPROFILE%\.unity-mcp\stdio.js"

Jede Claude-Code-Sitzung innerhalb eines Unity-Projekts erreicht jetzt den Editor des jeweiligen Projekts. Viele Editoren nebeneinander: Jede Sitzung findet ihren eigenen. Ist ein Editor geschlossen oder mitten im Reload, geben die Werkzeuge einen klaren Fehler zurück und erholen sich von selbst. Das Öffnen des Editors mitten in einer Sitzung funktioniert ebenfalls: Eine Sitzung, die bei geschlossenem Editor gestartet wird, registriert die Werkzeugliste sofort (bereitgestellt aus einem projektspezifischen Cache) und synchronisiert sich live neu, sobald der Editor wieder da ist – ohne dass der Client neu gestartet werden muss.

Im Hintergrund schreibt der Editor ein Beacon pro Sitzung (Temp/UnityMcp_Endpoint.json, das beim Beenden entfernt wird und nie veraltet). Der Launcher ermittelt das Projekt der Sitzung (CLAUDE_PROJECT_DIR, andernfalls durch Hochgehen im aktuellen Arbeitsverzeichnis; UNITY_MCP_PROJECT überschreibt beides) und leitet MCP-Anfragen an den Live-Endpunkt dieses Projekts weiter, wobei er das Beacon bei jeder Anfrage neu liest. Er deklariert tools.listChanged und überwacht das Beacon: Wenn ein Editor erscheint (oder ein anderer das Projekt übernimmt), sendet er list_changed-Notifications, sodass Clients die Werkzeug- und Ressourcenlisten mitten in der Sitzung neu abrufen. Die Launcher-Bereitstellung nach ~/.unity-mcp/stdio.js erfolgt nur bei Upgrades über LAUNCHER_VERSION; dadurch streiten sich Editoren aus verschiedenen Paketversionen nie um das File.

Andere MCP-Clients: entweder derselbe Launcher oder einfaches HTTP (Endpunkt und Token werden im Fenster angezeigt).

Werkzeuge

Hervorzuheben:

• unity_eval: Kompiliert und führt ein C#-Snipet im Editor aus, ganz ohne Domain-Reload. Die Ausdrucksform gibt ihren Wert zurück, die Anweisungsform benutzt return. Übliche usings werden importiert, vorangestellte using-Zeilen werden nach oben verschoben. Mitgeliefertes Roslyn (Obergrenze C# 9). Der erste Aufruf wärmt ein paar Sekunden auf, danach dauert eine Kompilierung nur wenige zehn Millisekunden

• unity_capture_panel: Rendert eine UI Toolkit PanelSettings offscreen als PNG, ohne Szenen-Optik, und funktioniert im Edit- und Play-Modus. Das aktive UIDocument wird automatisch erkannt

• unity_assets_find: Abfrage-Syntax des Projektfensters (t:Material, t:Prefab ui, l:MyLabel), ordnerbegrenzt optional, begrenztes Ergebnis mit Gesamtanzahl

• unity_reflection_decompile: vollständiger C#-Quellcode jedes Typs und jeder Methode

• Runtime-Verhalten: Nach einem Domain-Reload etwa 1 Sekunde warten, bevor Testwerkzeuge verwendet werden; unity_capture_game_view ist auf Unity 6.3+ nur im Play-Modus verfügbar

Ressourcen

unity://console/logs · unity://hierarchy · unity-://hierarchy/{scene} · unity://tests/results · unity://project/files

Konfiguration

ProjectSettings/McpSettings.json (im Team einchecken): HTTP-Port of ICQ, 5173, IPC-Port 52100, Autostart, Auth-Token.

Ports durch ein anderes Projekt belegt? Ein freies Portpaar wird automatisch zugewiesen und pro Rechner unter UserSettings/McpPortOverride.json gespeichert (git-ignoriert), damit keine Port-Verschiebungen bis zum Team gelangen. Die Projektidentität wird bei jeder Bridge-Verbindung überprüft: Ein Editor kann niemals den Server eines anderen Projekts übernehmen, selbst bei falsch konfigurierten Ports.

Server manuell starten: node src/server.js mit MCP_PROJECT_ROOT, das auf den Projektpfad gesetzt ist.

Funktioniert mit Unity CLI

Ergänzend, nichtkonkurrierend:

• Unity CLI verwaltet den gesamten Editor-Lebenszyklus: Installationen, unity open, Builds, CI

• UnityMCP verwaltet die die Live-Editor-Sitzung: UI-Erfassung, Dekompilierung, Eval, Testszyklus, Routing ohne Konfiguration

• Typischer Agentenablauf: unity open <project> über die CLI, Editor startet, Server und Beacon kommen hoch, der Launcher verbindet sich. Keine Konfigurationerldn auf beiden Seiten

• Per gestartete Editor laufen unbeobachtet / im Hintergrund. UnityMCP ist dafür gebaut(Background-sicherer Start, Wiederholungen über Domain-Reloads hinweg)

• Keine Konflikte bei Ports oder Tool-Namen. Registrieren Sie einfach beide.

Architektur

┌─────────────────────────────────────────────────────────────┐
│                      AI Assistant                           │
├──────────────────────────────┬──────────────────────────────┤
│  stdio launcher              │  (or direct HTTP clients)    │
│  ~/.unity-mcp/stdio.js       │                              │
│  resolves the session's      │                              │
│  project, reads its beacon   │                              │
│  Temp/UnityMcp_Endpoint.json │                              │
├──────────────────────────────┴──────────────────────────────┤
│           HTTP JSON-RPC (Port 5173, per project)            │
├─────────────────────────────────────────────────────────────┤
│              Node.js MCP Server (Server~/)                  │
├─────────────────────────────────────────────────────────────┤
│                TCP NDJSON (Port 52100)                      │
├─────────────────────────────────────────────────────────────┤
│                Unity Editor C# Bridge                       │
│  (McpBridge → ToolRegistry → MainThreadDispatcher)          │
├─────────────────────────────────────────────────────────────┤
│                     Unity APIs                              │
└─────────────────────────────────────────────────────────────┘

Jedes geöffnete Projekt läuft mit einem eigenen Node-Server. Der Launcher ist die gemeinsame Eingangstür, die jede Sitzung zu trennen richtigen Instanz des weiterleitet.

Entwicklung

• Unity-Tests: Fenster > Allgemein > Test Runner (EditMode + PlayMode)

• Launcher-Tests: npm test in Server~/

• Changelog: CHANGELOG.md

Lizenz

MIT. Hinweise siehe LICENSE.