unreal-mcp

Ein MCP-Server, der einen laufenden Unreal Engine Editor von Claude aus steuert.

Er spricht Epics eigenes Python Remote Execution-Protokoll: UDP-Multicast auf 239.0.0.1:6766, um Editor-Instanzen zu entdecken, dann einen TCP-Kanal, um Python im Editor auszuführen.

Claude  ──stdio──▶  unreal-mcp  ──UDP discovery + TCP──▶  Unreal Editor (PythonScriptPlugin)

Die Client-Seite des Protokolls ist nicht mitgeliefert. Der Server findet Epics remote_execution.py zur Laufzeit in Ihrer Engine-Installation, sodass er über Engine-Versionen hinweg funktioniert.

Anforderungen

• Unreal Engine 5.x (entwickelt gegen 5.6)

• Python 3.10+ und uv

Related MCP server: unreal-mcp

Einrichtung

1. Remote Execution in Unreal aktivieren – dieser Schritt wird von allen übersehen

Remote Execution ist standardmäßig deaktiviert. Ohne sie ist der Editor für die Erkennung unsichtbar und jedes Tool schlägt fehl.

1. Edit > Plugins → Python Editor Script Plugin aktivieren → neu starten.

2. Edit > Project Settings > Plugins > Python → Enable Remote Execution aktivieren.

3. Editor neu starten.

2. Installation

cd unreal-mcp
uv sync

3. Bei Claude registrieren

Fügen Sie zu claude_desktop_config.json hinzu:

{
  "mcpServers": {
    "unreal": {
      "command": "uv",
      "args": ["--directory", "E:\\Maya\\unreal-mcp", "run", "unreal-mcp"]
    }
  }
}

Starten Sie dann eine neue Konversation – Server, die mitten in einer Sitzung hinzugefügt werden, werden von einem bereits laufenden Chat nicht erkannt.

Wenn Ihre Engine an einem nicht standardmäßigen Ort liegt, setzen Sie UNREAL_ENGINE_ROOT:

"env": { "UNREAL_ENGINE_ROOT": "D:\\Epic\\UE_5.6" }

Tools

Listentools paginieren mit limit / offset und geben has_more plus next_offset zurück.

Wie Ergebnisse zurückkommen

Tool-Bodies werden in einer Hülle an den Editor gesendet, die einer result-Variablen zuweist und sie als JSON zwischen Sentinel-Markern ausgibt. So verhindert ein versehentliches print() oder eine Unreal-Logzeile, dass die Nutzlast beschädigt wird, und eine Ausnahme im Editor wird zu einem strukturierten Fehler statt zu einem Traceback, der in stdout vergraben ist.

Sicherheitshinweis

unreal_execute_python führt nicht sandboxed Code im Interpreter des Editors aus mit vollem Zugriff auf das unreal-Modul. Es kann Projektinhalte ändern oder löschen. Behandeln Sie es mit derselben Vorsicht wie eine Python-Konsole im Editor selbst.

Fehlerbehebung

„Kein laufender Unreal Editor wurde entdeckt" — fast immer die Einstellung „Enable Remote Execution" oben. Bestätigen Sie mit unreal_get_status.

„Verbindung verloren ... während ein Befehl ausgeführt wurde" — der Editor wurde geschlossen oder ist in einem modalen Dialog blockiert. Schließen Sie den Dialog und versuchen Sie es erneut; die Sitzung erkennt automatisch neu.

Mehrere geöffnete Editoren — der zuerst entdeckte Knoten gewinnt. unreal_get_status listet alle auf, damit Sie erkennen können, welcher welcher ist.