Installation

Diese Seite zeigt, wie du Unreal MCP, das AI Game Developer Plugin für Unreal Engine, in ein Projekt installierst. Wähle einen Installationsweg, folge seinen Schritten und fahre dann mit Getting started fort.

Voraussetzungen#

Das Plugin legt in seinem Descriptor keine exakte Engine-Version fest, sodass dasselbe Plugin auch in neueren Engine-Releases lädt.

Hinweis: Ein reines Blueprint-Projekt benötigt ein C++-Modul, bevor es Plugins bauen kann. Füge im Unreal Editor eine beliebige C++-Klasse hinzu (Tools, New C++ Class), um es in ein C++-Projekt umzuwandeln, oder erstelle mit unreal-mcp-cli create-project ein neues C++-Projekt.

Option 1: die AI Game Dev Desktop-App#

Die Desktop-App ist der einfachste Weg. Sie enthält die Installationslogik, du brauchst also kein Node.js, kein npm und kein Terminal.

1. Installiere AI Game Dev über die Download-Seite. Die Installationsanleitung für die App führt dich durch die einzelnen Schritte.
2. Melde dich mit deinem ai-game.dev-Konto an.
3. Wähle Open folder… und deinen Unreal-Projektordner (den Ordner, der die Datei .uproject enthält). Die App erkennt ihn als Unreal-Projekt. Oder nutze Create new project, um ein neues anzulegen; das Plugin wird dann automatisch installiert.
4. Klicke in der Seitenleiste auf Install Package. Die App installiert die neueste veröffentlichte Unreal MCP Version und prüft den Download vorher. Ist das installierte Plugin bereits neuer, behält die App es bei.
5. Klicke auf Open Editor, um den Unreal Editor mit deiner angemeldeten Sitzung zu starten, damit sich das Plugin über ai-game.dev ohne manuellen Token verbindet.

In der CLI der App sind die entsprechenden Aktionen die Befehle /install-plugin und /open. Die App kann außerdem die optionalen Erweiterungen installieren. Details findest du unter Projects and engines.

Option 2: unreal-mcp-cli#

unreal-mcp-cli ist auf npm veröffentlicht und läuft unter Windows, macOS und Linux. Es benötigt keinen Clone des Repositorys und keinen eigenen Build-Schritt.

Installiere die CLI global:

npm install -g unreal-mcp-cli

Oder führe einen beliebigen Befehl einmalig aus, ohne ihn zu installieren:

npx unreal-mcp-cli@latest status

Installiere dann das Plugin, melde dich an und öffne den Editor:

# 1. Install the UnrealMCP plugin into <project>/Plugins/UnrealMCP
unreal-mcp-cli install-plugin ./YourProject

# 2. Sign in to ai-game.dev once per machine (device-code flow in your browser)
unreal-mcp-cli login

# 3. Open the Unreal Editor for the project
unreal-mcp-cli open ./YourProject

Was diese Befehle tun:

• install-plugin lädt den Plugin-Quellcode herunter, der zur CLI-Version passt (unreal-mcp-plugin-source-<version>.zip aus dem GitHub-Release), und prüft seine Signatur, bevor er ihn entpackt. Ein manipulierter oder unsignierter Download wird abgelehnt. Die Bridge für deine Plattform ist in diesem Paket enthalten.
• login speichert deine Anmeldedaten im maschinenweiten Store (~/.ai-game-dev/credentials.json), den die App und die anderen Engine-CLIs gemeinsam nutzen.
• open findet die richtige Engine über die EngineAssociation des Projekts, baut zuerst die nativen Editor-Module, wenn sie kompiliert werden müssen, und schließt die bekannten Unreal-Startmeldungen (etwa "Missing Modules"), falls sie trotzdem erscheinen.

Tipp: Schließe den Unreal Editor, bevor du das Plugin installierst oder aktualisierst. Unreal kann ein Plugin nicht ersetzen, das ein laufender Editor geladen hat.

Option 3: manuelle Installation aus dem Quellcode#

Die manuelle Installation ist für Contributors und die Plugin-Entwicklung gedacht.

1. Kopiere den Ordner UnrealMCP/ aus dem Unreal-MCP Repository nach <YourProject>/Plugins/UnrealMCP/.
2. Ein Source-Checkout enthält keine mitgelieferte Bridge. Baue eine mit unreal-mcp-cli bootstrap-local ./YourProject (benötigt das .NET 9 SDK) oder setze UNREAL_MCP_BRIDGE_PATH auf eine Bridge, die du selbst gebaut hast.
3. Öffne das Projekt. Unreal kompiliert die Module des Plugins beim ersten Start.

Für die Live-Entwicklung verlinkt unreal-mcp-cli install-plugin --junction den Plugin-Ordner, statt ihn zu kopieren (Windows).

Fab / Epic Marketplace#

Ein Fab-Eintrag ist geplant, aber noch nicht live. Bis er veröffentlicht ist, gibt es nichts, was du von Fab aus installieren könntest; nutze die App oder die CLI.

Installation prüfen#

Beim Start des Editors gibt das Output Log Folgendes aus:

[Unreal-MCP] plugin loaded

Du kannst auch unreal-mcp-cli status --path ./YourProject ausführen, um den Zustand von Paket, Projekt, Plugin und Verbindung zu sehen.

Das Plugin erscheint dann im Tools-Menü des Editors als AI Game Developer. Fahre mit Getting started fort.

Das Plugin aktualisieren#

• App: Die Seitenleiste zeigt Update Package, wenn eine neuere Plugin-Version verfügbar ist.
• CLI: Führe unreal-mcp-cli update ./YourProject aus. Bei einem Versionswechsel löscht es den Ordner Intermediate/ des installierten Plugins und dessen kompilierte C++-Binaries/, damit Unreal einen sauberen Rebuild durchführt, und es behält die mitgelieferte Bridge bei. Füge --force hinzu, um dieselbe Version neu zu installieren, oder --no-clean, um den Build-Cache zu behalten.
• Manuelles Kopieren: Schließe den Editor, lösche Plugins/UnrealMCP/Intermediate/ und die C++-Binaries/ (behalte Binaries/ThirdParty/) und öffne dann das Projekt erneut.

Ein veralteter Build-Cache ist der häufigste Grund dafür, dass ein Update wirkungslos zu sein scheint. Siehe Troubleshooting.

Das Plugin entfernen#

unreal-mcp-cli remove-plugin ./YourProject

Oder lösche <YourProject>/Plugins/UnrealMCP/ bei geschlossenem Editor.

Das Plugin aus gepackten Spielen heraushalten#

Wenn du Unreal MCP nur für KI-Unterstützung im Editor verwendest, schließe es in den Plugin-Einträgen der .uproject-deines Projekts von gepackten Builds aus:

{
  "Name": "UnrealMCP",
  "Enabled": true,
  "TargetDenyList": ["Game", "Client", "Server"]
}

Das Plugin bleibt dann im Editor aktiv, aber nichts davon – einschließlich der Bridge – wird in ein gepacktes Spiel kompiliert oder gestaged. Füge kein UnrealMcp*-Modul zu den Build.cs-Abhängigkeiten deines Spielmoduls hinzu: Eine direkte Abhängigkeit überschreibt die Deny-List. Um KI-Tools stattdessen in einem laufenden Spiel zu nutzen, siehe in-game tools.