Unreal Engine MCP Server

A comprehensive Model Context Protocol (MCP) server that enables AI assistants to control Unreal Engine via Remote Control API. Built with TypeScript and designed for game development automation.

Features

Core Capabilities

• Asset Management - Browse, import, and create materials
• Actor Control - Spawn, delete, and manipulate actors with physics
• Editor Control - PIE sessions, camera, and viewport management
• Level Management - Load/save levels, lighting, and environment building
• Animation & Physics - Blueprints, state machines, ragdolls, constraints
• Visual Effects - Niagara particles, GPU simulations, procedural effects
• Sequencer - Cinematics, camera animations, and timeline control
• Console Commands - Safe execution with dangerous command filtering

Quick Start

Prerequisites

• Node.js 18+
• Unreal Engine 5.0-5.6
• Required UE Plugins (enable via Edit ▸ Plugins):
  • Remote Control API – core Remote Control HTTP/WS endpoints
  • Remote Control Web Interface – enables WebSocket bridge used by this server
  • Python Editor Script Plugin – exposes Python runtime for automation
  • Editor Scripting Utilities – unlocks Editor Actor/Asset subsystems used throughout the tools
  • Sequencer (built-in) – keep enabled for cinematic tools
  • Level Sequence Editor – required for manage_sequence operations

💡 After toggling any plugin, restart the editor to finalize activation. Keep Editor Scripting Utilities and Python Editor Script Plugin enabled prior to connecting, otherwise many subsystem-based tools (actor spawning, audio, foliage, UI widgets) will refuse to run for safety.

Plugin feature map

| Plugin | Location | Used By | Notes | |--------|----------|---------|-------| | Remote Control API | Developer Tools ▸ Remote Control | All tools | Provides HTTP/WS endpoints consumed by the MCP bridge | | Remote Control Web Interface | Developer Tools ▸ Remote Control | All tools | Enables persistent WebSocket session | | Python Editor Script Plugin | Scripting | Landscapes, lighting, audio, physics, sequences, UI | Required for every Python execution path | | Editor Scripting Utilities | Scripting | Actors, foliage, assets, landscapes, UI | Supplies Editor Actor/Asset subsystems in UE5.6 | | Sequencer | Built-in | Sequencer tools | Ensure not disabled in project settings | | Level Sequence Editor | Animation | Sequencer tools | Activate before calling manage_sequence operations |

Installation

Option 1: NPM Package (Recommended)

# Install globally
npm install -g unreal-engine-mcp-server

# Or install locally in your project
npm install unreal-engine-mcp-server

Option 2: Clone and Build

# Clone the repository
git clone https://github.com/ChiR24/Unreal_mcp.git
cd Unreal_mcp

# Install dependencies and build
npm install
npm run build

# Run directly
node dist/cli.js

Unreal Engine Configuration

Add to your project's Config/DefaultEngine.ini:

[/Script/PythonScriptPlugin.PythonScriptPluginSettings]
bRemoteExecution=True
bAllowRemotePythonExecution=True

[/Script/RemoteControl.RemoteControlSettings]
bAllowRemoteExecutionOfConsoleCommands=True
bEnableRemoteExecution=True
bAllowPythonExecution=True

Then enable Python execution in: Edit > Project Settings > Plugins > Remote Control

MCP Client Configuration

Claude Desktop / Cursor

For NPM Installation (Local)

{
  "mcpServers": {
    "unreal-engine": {
      "command": "npx",
      "args": ["unreal-engine-mcp-server"],
      "env": {
        "UE_HOST": "127.0.0.1",
        "UE_RC_HTTP_PORT": "30010",
        "UE_RC_WS_PORT": "30020",
        "UE_PROJECT_PATH": "C:/Users/YourName/Documents/Unreal Projects/YourProject"
      }
    }
  }
}

For Clone/Build Installation

{
  "mcpServers": {
    "unreal-engine": {
      "command": "node",
      "args": ["path/to/Unreal_mcp/dist/cli.js"],
      "env": {
        "UE_HOST": "127.0.0.1",
        "UE_RC_HTTP_PORT": "30010",
        "UE_RC_WS_PORT": "30020",
        "UE_PROJECT_PATH": "C:/Users/YourName/Documents/Unreal Projects/YourProject"
      }
    }
  }
}

Available Tools (13)

| Tool | Description | |------|-------------| | manage_asset | List, create materials, import assets | | control_actor | Spawn, delete actors, apply physics | | control_editor | PIE control, camera, view modes | | manage_level | Load/save levels, lighting | | animation_physics | Animation blueprints, ragdolls | | create_effect | Particles, Niagara, debug shapes | | manage_blueprint | Create blueprints, add components | | build_environment | Landscapes, terrain, foliage | | system_control | Profiling, quality, UI, screenshots, Output Log reading | | console_command | Direct console command execution | | manage_rc | Remote Control presets | | manage_sequence | Sequencer/cinematics | | inspect | Object introspection |

Key Features

• Graceful Degradation - Server starts even without UE connection
• Auto-Reconnection - Attempts reconnection every 10 seconds
• Connection Timeout - 5-second timeout with configurable retries
• Non-Intrusive Health Checks - Uses echo commands every 30 seconds
• Command Safety - Blocks dangerous console commands
• Input Flexibility - Vectors/rotators accept object or array format
• Asset Caching - 10-second TTL for improved performance

Supported Asset Types

Blueprints, Materials, Textures, Static/Skeletal Meshes, Levels, Sounds, Particles, Niagara Systems

Example Console Commands

• Statistics: stat fps, stat gpu, stat memory
• View Modes: viewmode wireframe, viewmode unlit
• Gameplay: slomo 0.5, god, fly
• Rendering: r.screenpercentage 50, r.vsync 0

Configuration

Environment Variables

UE_HOST=127.0.0.1              # Unreal Engine host
UE_RC_HTTP_PORT=30010          # Remote Control HTTP port
UE_RC_WS_PORT=30020            # Remote Control WebSocket port
UE_PROJECT_PATH="C:/Users/YourName/Documents/Unreal Projects/YourProject"  # Absolute path to your .uproject file
LOG_LEVEL=info                 # debug | info | warn | error

Docker

docker build -t unreal-mcp .
docker run -it --rm unreal-mcp

Pull from Docker Hub

docker pull mcp/server/unreal-engine-mcp-server:latest
docker run --rm -it mcp/server/unreal-engine-mcp-server:latest

Development

npm run build          # Build TypeScript
npm run lint           # Run ESLint
npm run lint:fix       # Fix linting issues

Contributing

Contributions welcome! Please:

• Include reproduction steps for bugs
• Keep PRs focused and small
• Follow existing code style

License

MIT - See LICENSE file