Unreal Master Agent

Unreal Master AI — Project Website | Unreal Master MCP Workflows Community

An autonomous AI agent that gives Claude Code bidirectional control over Unreal Engine internals — manipulating Blueprints at the graph level, generating Slate UI code, triggering Live Coding compilation, and self-healing from compile errors without manual intervention.

What This Does

You describe what you want in natural language. Claude Code calls the right tools in sequence. Unreal Engine executes the changes in real time.

Example:

"Add a PrintString node to BP_TestActor connected after BeginPlay, set the message to 'Hello World', then compile."

The agent serializes the Blueprint to JSON, creates the node, connects the exec pins, sets the default value, and triggers Live Coding — reporting any compile errors back for self-healing if needed.

Core capabilities:

Blueprint graph serialization (UEdGraph → structured JSON AST)
Dynamic node creation and pin connection via C++ UE APIs
Slate UI code generation with RAG-assisted template retrieval
Live Coding compilation trigger and compile log capture
Self-healing loop: parse compile errors → apply fix → retry (max 3 iterations)
Human-in-the-loop approval gate for destructive operations
Actor spawning, deletion, property editing, transform control
Material creation, parameter setting (scalar/vector), texture assignment
Level management (create, open, save, sublevels, world settings)
Asset pipeline (import, export, create, duplicate, rename, delete, references)
Animation tools (montages, blend spaces, skeleton info)
Mesh operations (LOD, materials, collision generation)
DataTable CRUD operations
Project introspection (structure, plugins, settings, class hierarchy, dependency graph)
Build pipeline (lightmaps, content cooking, map check)
Source control integration (status, checkout, diff)
Gameplay systems (input actions, game mode)
Python script execution bridge (166 scripts) for extensible UE automation
Sequencer/cinematics, AI/navigation, widget/UMG tools
Texture, Niagara VFX, audio, landscape pipelines
Physics, world partition, foliage, curves, PCG, geometry script tools
Workflow templates (character, UI, level, multiplayer, inventory, dialogue)
Analysis tools (Blueprint complexity, asset health, performance, conventions)
Context intelligence (auto-gather project context, tool manifest, workflow chains)
Workflow learning system (learn from Epic docs, intent matching with UE synonym expansion)
Error resolution learning (capture troubleshooting outcomes, replay fixes for similar errors)
Outcome-weighted recommendations (proven workflows rank higher automatically)
89 workflow patterns (21 builtin from Epic docs + 68 community-seeded), 25 error resolution patterns
Proactive tool recommendations based on workflow step adjacency analysis
Analytics dashboard for workflow coverage, tool usage, and error resolution metrics

Multi-LLM Support:

Works with Claude Code, Claude Desktop, Cursor, Windsurf, and VS Code + GitHub Copilot — any MCP-compatible AI editor.

Workflow Community Platform

Browse, share, and discover community-created workflows at the Workflow Community platform:

22+ official workflows covering 14+ UE domains (Blueprint, Material, Level, Character, Animation, Niagara, Audio, Landscape, Physics, Gameplay, Sequencer, AI/Nav, Widget, Mesh)
Community-contributed workflows with ratings and reviews
Create and share your own workflows with the community
Integration guides for Claude Code, Claude Desktop, Cursor, Windsurf, and VS Code
CLI import — npx unreal-master-mcp-server import-workflow <id> to import any workflow directly
Full-text search and filtering by domain and difficulty

Visit the platform: https://unreal-workflow-web.vercel.app

See UnrealWorkflow for the community platform source code.

Extensibility:

Custom MCP tools: drop .ts/.js files in mcp-server/custom-tools/ for automatic discovery and registration
Tool hooks: register pre/post execution callbacks via ToolHookManager for logging, validation, or transformation
Custom Python scripts: place scripts in Content/Python/uma_custom/ and invoke them with python-customExecute
Auto-registration architecture: each domain exposes a ToolModule via its own index.ts — adding a new domain requires no changes to server.ts
Workflow Marketplace: standardized JSON sharing format, context-exportWorkflow/context-importWorkflow tools, CLI import from file or URL, 10 community workflow templates

Architecture Overview

The system uses a 4-layer architecture with clean separation between reasoning, bridging, execution, and engine APIs.

Claude Code (Layer 1)
    │ stdio / JSON-RPC
MCP Bridge Server — Node.js/TypeScript (Layer 2)
    │ WebSocket
UE Agent Plugin — C++ (Layer 3)
    │ Direct C++ API calls
Engine APIs: UEdGraph, Slate, ILiveCodingModule (Layer 4)

Key design decisions:

UE is the WebSocket client — Node.js listens, UE connects. This uses UE's stable FWebSocketsModule client rather than a nonexistent server API.
All UE operations run on the GameThread — WebSocket callbacks dispatch via AsyncTask(ENamedThreads::GameThread).
TryCreateConnection always, never MakeLinkTo — ensures polymorphic pin type propagation.
Self-healing is Claude's responsibility — the server provides atomic tools; Claude orchestrates retry logic.

See ARCHITECTURE.md for the full architecture document including data flow diagrams, threading model, safety architecture, and all ADRs.

Prerequisites

Node.js 20+
npm 10+
TypeScript 5.5+ (installed via devDependencies)
Unreal Engine 5.4 - 5.7
Python Editor Script Plugin enabled in UE (Edit → Plugins → Scripting) — required for Python automation (166 scripts)
Claude Code (latest) with MCP support

Quick Start

1. Install dependencies

cd mcp-server
npm install

2. Configure for your AI editor

npx unreal-master-mcp-server init --host=claude      # Claude Desktop (default)
npx unreal-master-mcp-server init --host=cursor      # Cursor
npx unreal-master-mcp-server init --host=windsurf    # Windsurf
npx unreal-master-mcp-server init --host=vscode      # VS Code + Copilot
npx unreal-master-mcp-server init --host=claude-code # Claude Code CLI

Note: Only one AI host can connect to a UE instance at a time. Each host spawns its own MCP server process which binds WebSocket port 9877. Close the current host before switching to another. See the Integration Guides for details.

Or manually add to .claude/mcp.json (project root):

{
  "mcpServers": {
    "unreal-master": {
      "command": "node",
      "args": ["mcp-server/dist/index.js"],
      "env": {
        "UE_WS_PORT": "9877"
      }
    }
  }
}

Or, if installed globally via npm:

{
  "mcpServers": {
    "unreal-master": {
      "command": "npx",
      "args": ["-y", "unreal-master-mcp-server"],
      "env": {
        "UE_WS_PORT": "9877"
      }
    }
  }
}

3. Build the MCP server

cd mcp-server
npm run build

4. Enable the UE Plugin

Quick install (copies the plugin automatically):

./scripts/install-plugin.sh /path/to/YourProject

Manual install:

Copy or symlink UnrealMasterAgent/ into your Unreal Engine project's Plugins/ directory, then enable it in the .uproject file:

{
  "Plugins": [{ "Name": "UnrealMasterAgent", "Enabled": true }]
}

Rebuild the project from source.

5. Enable Python Editor Script Plugin

The Python automation layer (166 scripts) requires the Python Editor Script Plugin:

Open your UE project → Edit → Plugins
Search for "Python Editor Script Plugin" under Scripting
Enable it and restart the editor

Without this plugin, all non-Python tools (Blueprints, actors, materials, etc.) still work. Only Python-based automation will be unavailable.

See docs/setup-guide.md for verification steps and troubleshooting.

6. Start the agent

Open your Unreal Engine project (the plugin auto-connects to the MCP server on startup), then launch Claude Code in the project root. The MCP server starts automatically.

Verify the connection:

> editor.ping

Expected response: { "status": "ok", "ueVersion": "5.4.x" }

Development mode (watch + auto-rebuild)

cd mcp-server
npm run dev

Project Structure

Unreal Master/
├── ARCHITECTURE.md          Architecture decisions and system design
├── README.md                This file
├── AGENTS.md                AI agent guidance for this codebase
├── package.json             Workspace root
│
├── mcp-server/              Layer 2: Node.js/TypeScript MCP bridge
│   ├── src/
│   │   ├── index.ts         Entry point (McpServerBootstrap)
│   │   ├── server.ts        McpServer configuration (auto-registers tools)
│   │   ├── tools/

UnrealMasterAI

Install / Use

README