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, C++, and Rust (WebAssembly).

Table of Contents

• Features
• Getting Started
• Configuration
• Available Tools
• WebAssembly Acceleration
• GraphQL API
• Docker
• Documentation
• Community
• Development
• Contributing

Features

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鈥�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

Step 3: Enable Required Plugins

Enable via Edit 鈫� Plugins, then restart the editor:

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

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

# Optional
WASM_ENABLED=true
MCP_AUTOMATION_REQUEST_TIMEOUT_MS=120000
ASSET_LIST_TTL_MS=10000

Available Tools

Supported Asset Types

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

WebAssembly Acceleration

Optional WASM acceleration for computationally intensive operations. Enabled by default when available, falls back to TypeScript automatically.

Building WASM (Optional)

cargo install wasm-pack  # Once per machine
npm run build:wasm       # Builds  WASM

To disable: WASM_ENABLED=false

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

Development

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

Community

Contributing

Contributions welcome! Please:

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

License

MIT 鈥� See LICENSE