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
`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

ChiR24-unreal_mcp_server

Documentation