Unreal Engine MCP Server

A comprehensive Model Context Protocol (MCP) server that enables AI assistants to control Unreal Engine through a native C++ Automation Bridge plugin. Built with TypeScript and C++.

Table of Contents

• Features

• Getting Started

• Configuration

• Available Tools

• Docker

• Documentation

• Community

• Development

• Contributing

Features

Category Capabilities

Asset Management Browse, import, duplicate, rename, delete assets; create materials

Actor Control Spawn, delete, transform, physics, tags, components

Editor Control PIE sessions, camera, viewport, screenshots, bookmarks

Level Management Load/save levels, streaming, lighting

Animation & Physics Animation BPs, state machines, ragdolls, vehicles, constraints

Visual Effects Niagara particles, GPU simulations, procedural effects, debug shapes

Sequencer Cinematics, timeline control, Movie Render Queue, media, Take Recorder, replay

Graph Editing Blueprint, Niagara, Material, and Behavior Tree graph manipulation

Audio Sound cues, audio components, sound mixes, ambient sounds

System Console commands, UBT, tests, logs, project settings, CVars

Architecture

• Native C++ Automation — All operations route through the MCP Automation Bridge plugin

• Dual Transport — Native HTTP/SSE (no bridge needed) or WebSocket via TypeScript bridge

• Dynamic Type Discovery — Runtime introspection for lights, debug shapes, and sequencer tracks

• Graceful Degradation — Server starts even without an active Unreal connection

• On-Demand Connection — Retries automation handshakes with exponential backoff

• Command Safety — Blocks dangerous console commands with pattern-based validation

• Capability Token Auth — On-by-default token authentication (auto-generated 32-byte secret at <Project>/Saved/MCP/capability-token) for both WS and HTTP transports; manual CapabilityToken in Project Settings overrides the file

• Asset Caching — 10-second TTL for improved performance

• Metrics Rate Limiting — Per-IP rate limiting (60 req/min) on Prometheus endpoint

• Centralized Configuration — Unified class aliases and type definitions

Getting Started

Prerequisites

• Node.js 20.19 or later (Node.js 18 is not supported) — required for the TypeScript stdio bridge. Not needed for the native MCP transport.

Step 1: Install MCP Server (Option B only — skip for Native MCP)

Skip this step if using Option A: Native MCP Transport (Step 4A below).

NPX (Recommended):

npx unreal-engine-mcp-server

Clone & Build:

git clone https://github.com/ChiR24/Unreal_mcp.git
cd Unreal_mcp
npm install
npm run build
node dist/cli.js

Step 2: Install Unreal Plugin

The MCP Automation Bridge plugin is included at Unreal_mcp/plugins/McpAutomationBridge.

From source (requires a project with code target)

Your project must have a code target (.sln or .xcworkspace). Blueprint-only projects cannot compile native plugins — to convert, add any class via Tools > New C++ Class in the editor.

Method 1: Copy Folder

Copy:  Unreal_mcp/plugins/McpAutomationBridge/
To:    YourUnrealProject/Plugins/McpAutomationBridge/

Method 2: External Plugin Directory (no copy needed)

• Open Unreal Editor → Edit → Plugins

• Click Plugin Directories (bottom-left)

• In Additional Plugin Directories, add the path to Unreal_mcp/plugins/

• Restart the editor — the plugin will be picked up from the external location

This saves the path in your .uproject file so the plugin stays linked without copying.

The plugin compiles automatically when you open the project — UE detects the .uplugin + Source/ and runs UnrealBuildTool.

Video Guide:

https://github.com/user-attachments/assets/d8b86ebc-4364-48c9-9781-de854bf3ef7d

⚠️ First-Time Project Open: UE may prompt "Would you like to rebuild them now?" — click Yes. If instead you see "Missing Modules — McpAutomationBridge. Engine modules cannot be compiled at runtime. Please build through your IDE." — open your project in Visual Studio (Win) or Xcode (Mac) and build from there. After that, the editor will open normally with the plugin loaded.

Pre-built (works with any project, including Blueprint-only)

Build the plugin once, then distribute the compiled binaries — no IDE or compilation needed on the target machine.

1. Build:

# macOS / Linux
./scripts/package-plugin.sh /path/to/UE_5.6

# Windows
scripts\package-plugin.bat C:\Path\To\UE_5.6

This produces a zip like McpAutomationBridge-v0.5.30-UE5.7-Linux.zip.

2. Install: unzip into YourProject/Plugins/ and open the project. That's it — no compilation step.

Note: pre-built binaries are tied to a specific UE version. A build for 5.6 won't work with 5.5, 5.7, or 5.8.

Step 3: Enable Required Plugins

Enable via Edit → Plugins, then restart the editor.

Plugin Required For

MCP Automation Bridge All automation operations

Python Editor Script Plugin Python-backed editor automation helpers

Editor Scripting Utilities Asset/Actor subsystem operations

Niagara Visual effects and particle systems

Gameplay Abilities manage_gas operations

Smart Objects AI smart object operations

Plugin Required For

Level Sequence Editor manage_sequence operations

Movie Render Pipeline manage_sequence Movie Render Queue operations

Movie Pipeline Mask Render Pass Object-ID render pass

Takes manage_sequence Take Recorder operations

Electra Player manage_sequence file-backed media playback

Control Rig animation_physics operations

GeometryScripting manage_geometry operations

Behavior Tree Editor manage_ai Behavior Tree operations

Niagara Editor Niagara authoring

Environment Query Editor AI/EQS operations

MetaSound manage_audio MetaSound authoring

StateTree manage_ai State Tree operations

Enhanced Input manage_networking input mapping operations

Chaos Cloth Cloth simulation

Interchange Asset import/export

Data Validation Data validation

PCG manage_pcg graph authoring and execution when enabled for the build

Procedural Mesh Component Procedural geometry

OnlineSubsystem Session/networking operations

OnlineSubsystemUtils Session/networking operations

💡 Optional plugins are auto-enabled by the MCP Automation Bridge plugin when needed. PCG support is compiled for source projects when the project explicitly enables PCG. Versioned release packages for UE 5.2+ include PCG support. All Unreal Engine versions from 5.0 to 5.8 are supported and working.

Step 4: Configure MCP Client

Option A: Native MCP Transport (Direct HTTP — no bridge needed)

The plugin includes a built-in MCP Streamable HTTP server. AI clients connect directly to the plugin over HTTP — no TypeScript bridge, no Node.js, no npm. Note: the bAllowNonLoopback setting now applies to both the WebSocket bridge and the native MCP transport. Enabling it binds both surfaces to non-loopback addresses. If you only need LAN access for the WebSocket bridge, do not enable bAllowNonLoopback and instead expose the bridge via a reverse proxy. Capability token auth is on by default (0.5.30+) — both transports require authentication automatically. A manually configured CapabilityToken in Project Settings or the auto-generated token at <Project>/Saved/MCP/capability-token is used automatically.

Enable in Unreal:

• Edit > Project Settings > Plugins > MCP Automation Bridge

• Check Enable Native MCP

• Set port (default: 3000)

• Optionally set Native MCP Instructions for project-specific guidance

• Restart the editor

Configure your MCP client to use Streamable HTTP transport at:

http://localhost:3000/mcp

Claude Code:

claude mcp add unreal-engine --transport http http://localhost:3000/mcp

Or manually in ~/.claude/settings.json or project .mcp.json:

{
  "mcpServers": {
    "unreal-engine": {
      "type": "url",
      "url": "http://localhost:3000/mcp"
    }
  }
}

Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "unreal-engine": {
      "url": "http://localhost:3000/mcp"
    }
  }
}

Verify it works:

• Status bar — look for ● MCP :3000 (2) in the bottom-right of the editor. Green dot = server