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
• GraphQL API
• 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, World Partition, data layers
Animation & Physics	Animation BPs, state machines, ragdolls, vehicles, constraints
Visual Effects	Niagara particles, GPU simulations, procedural effects, debug shapes
Sequencer	Cinematics, timeline control, camera animations, keyframes
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
• 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
• 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 18+
• Unreal Engine 5.0–5.7

Step 1: Install MCP Server

Option A: NPX (Recommended)

npx unreal-engine-mcp-server

Option B: 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.

Method 1: Copy Folder

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

Regenerate project files after copying.

Method 2: Add in Editor

1. Open Unreal Editor → Edit → Plugins
2. Click "Add" → Browse to Unreal_mcp/plugins/
3. Select the McpAutomationBridge folder

Video Guide:

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

⚠️ First-Time Project Open: When opening the project directly (double-click .uproject) for the first time, UE will prompt "Would you like to rebuild them now?" for missing modules. Click Yes to rebuild. After the rebuild completes, you may still see: "Plugin 'McpAutomationBridge' failed to load because module could not be loaded." This is expected — UE rebuilds successfully but doesn't reload the plugin in the same session. Simply close and reopen the project and the plugin will load correctly. Alternatively, build via Visual Studio first to avoid this.

Step 3: Enable Required Plugins

Enable via Edit → Plugins, then restart the editor.

<details> <summary><b>Core Plugins (Required)</b></summary>

Plugin	Required For
MCP Automation Bridge	All automation operations
Editor Scripting Utilities	Asset/Actor subsystem operations
Niagara	Visual effects and particle systems

</details>

<details> <summary><b>Optional Plugins (Auto-enabled)</b></summary>

Plugin	Required For
Level Sequence Editor	manage_sequence operations
Control Rig	animation_physics operations
GeometryScripting	manage_geometry operations
Behavior Tree Editor	manage_behavior_tree operations
Niagara Editor	Niagara authoring
Environment Query Editor	AI/EQS operations
Gameplay Abilities	manage_gas operations
MetaSound	manage_audio MetaSound authoring
StateTree	manage_ai State Tree operations
Smart Objects	AI smart object operations
Enhanced Input	manage_input operations
Chaos Cloth	Cloth simulation
Interchange	Asset import/export
Data Validation	Data validation
Procedural Mesh Component	Procedural geometry
OnlineSubsystem	Session/networking operations
OnlineSubsystemUtils	Session/networking operations

</details>

💡 Optional plugins are auto-enabled by the MCP Automation Bridge plugin when needed.

Step 4: Configure MCP Client

Add to your Claude Desktop / Cursor config file:

Using Clone/Build:

{
  "mcpServers": {
    "unreal-engine": {
      "command": "node",
      "args": ["path/to/Unreal_mcp/dist/cli.js"],
      "env": {
        "UE_PROJECT_PATH": "C:/Path/To/YourProject",
        "MCP_AUTOMATION_PORT": "8091"
      }
    }
  }
}

Using NPX:

{
  "mcpServers": {
    "unreal-engine": {
      "command": "npx",
      "args": ["unreal-engine-mcp-server"],
      "env": {
        "UE_PROJECT_PATH": "C:/Path/To/YourProject"
      }
    }
  }
}

---

Configuration

Environment Variables

# Required
UE_PROJECT_PATH="C:/Path/To/YourProject"

# Automation Bridge
MCP_AUTOMATION_HOST=127.0.0.1
MCP_AUTOMATION_PORT=8091

# LAN Access (optional)
# SECURITY: Set to true to allow binding to non-loopback addresses (e.g., 0.0.0.0)
# Only enable if you understand the security implications.
MCP_AUTOMATION_ALLOW_NON_LOOPBACK=false

# Logging
LOG_LEVEL=info  # debug | info | warn | error

# Optional
MCP_AUTOMATION_REQUEST_TIMEOUT_MS=120000
ASSET_LIST_TTL_MS=10000

LAN Access Configuration

By default, the automation bridge only binds to loopback addresses (127.0.0.1) for security. To enable access from other machines on your network:

TypeScript (MCP Server):

MCP_AUTOMATION_ALLOW_NON_LOOPBACK=true
MCP_AUTOMATION_HOST=0.0.0.0

Unreal Engine Plugin:

1. Go to Edit → Project Settings → Plugins → MCP Automation Bridge
2. Under Security, enable "Allow Non Loopback"
3. Under Connection, set "Listen Host" to 0.0.0.0
4. Restart the editor

⚠️ Security Warning: Enabling LAN access exposes the automation bridge to your local network. Only use on trusted networks with appropriate firewall rules.

---

Available Tools

36 MCP tools with action-based dispatch for comprehensive Unreal Engine automation.

<details> <summary><b>Core Tools</b></summary>

Tool	Description
manage_asset	Assets, Materials, Render Targets, Behavior Trees
control_actor	Spawn, delete, transform, physics, tags
control_editor	PIE, Camera, viewport, screenshots
manage_level	Load/Save, World Partition, streaming
system_control	UBT, Tests, Logs, Project Settings, CVars
inspect	Object Introspection
manage_pipeline	Build automation, UBT compilation, status checks
manage_tools	Dynamic tool management (enable/disable at runtime)

</details>

<details> <summary><b>World Building</b></summary>

Tool	Description
manage_lighting	Spawn lights, GI, shadows, build lighting, list_light_types
manage_level_structure	Level creation, sublevels, World Partition, data layers, HLOD
manage_volumes	Trigger volumes, blocking, physics, audio, navigation volumes
manage_navigation	NavMesh settings, nav modifiers, nav links, smart links, pathfinding
build_environment	Landscape, Foliage, Procedural
manage_splines	Spline creation, spline mesh deformation

</details>

<details> <summary><b>Animation & Physics</b></summary>

Tool	Description
animation_physics	Animation BPs, Vehicles, Ragdolls, Control Rig, IK, Blend Spaces
manage_skeleton	Skeleton, sockets, physics assets, cloth binding
manage_geometry	Procedural mesh creation (Geometry Script)

</details>

<details> <summary><b>Visuals & Effects</b></summary>

Tool	Description
manage_effect	Niagara, Particles, Debug Shapes, GPU simulations
manage_material_authoring	Material creation, expressions, landscape layers
manage_texture	Texture creation, modification, compression settings
manage_blueprint	Create, SCS, Graph Editing, Node manipulation
manage_sequence	Sequencer / Cinematics, list_track_types
manage_performance	Profiling, optimization, scalability

</details>

<details> <summary><b>Audio & Input</b></summary>

Tool	Description
manage_audio	Audio Assets, Components, Sound Cues, MetaSounds, Attenuation
manage_input	Enhanced Input Actions & Contexts

</details>

<details> <summary><b>Gameplay Systems</b></summary>

Tool	Description
manage_behavior_tree	Behavior Tree Graph Editing
manage_ai	AI controllers, EQS, perception, State Trees, Smart Objects
manage_gas	Gameplay Ability System: abilities, effects, attributes
manage_character	Character creation, movement, advanced locomotion
manage_combat	Weapons, projectiles, damage, melee combat
manage_inventory	Items, equipment, loot tables, crafting
manage_interaction	Interactables, destructibles, triggers
manage_widget_authoring	UMG widget creation, layout, styling, animations

</details>

<details> <summary><b>Networking & Sessions</b></summary>

Tool	Description
manage_networking	Replication, RPCs, network prediction
manage_game_framework	Game modes, game states, player controllers, match flow
manage_sessions	Sessions, split-screen, LAN, voice chat

</details>

Supported Asset Types

Blueprints • Materials • Textures • Static Meshes • Skeletal Meshes • Levels • Sounds • Particles • Niagara Systems • Behavior Trees

---

GraphQL API

Optional GraphQL endpoint for complex queries. Disabled by default.

GRAPHQL_ENABLED=true
GRAPHQL_PORT=4000

See GraphQL API Documentation.

---

Docker

docker build -t unreal-mcp .
docker run -it --rm -e UE_PROJECT_PATH=/project unreal-mcp

---

Documentation

Document	Description
Handler Mappings	TypeScript to C++ routing
GraphQL API	Query and mutation reference
Plugin Extension	C++ plugin architecture
Testing Guide	How to run and write tests
Roadmap	Development phases

---

Development

npm run build       # Build TypeScript
npm run lint        # Run ESLint
npm run test:unit   # Run unit tests
npm run test:all    # Run all tests

---

Community

Resource	Description
Project Roadmap	Track development progress across 47 phases
Discussions	Ask questions, share ideas, get help
Issues	Report bugs and request features

---

Contributing

Contributions welcome! Please:

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

---

License

MIT — See LICENSE