ChiR24 Unreal Mcp

Unreal Engine MCP Server

[License: MIT] [NPM Package] [MCP SDK] [Unreal Engine] [MCP Registry] [Project Board] [Discussions]

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

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.gitcd Unreal_mcpnpm installnpm run buildnode 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)

1. Open Unreal Editor → Edit → Plugins
2. Click Plugin Directories (bottom-left)
3. In Additional Plugin Directories, add the path to Unreal_mcp/plugins/
4. 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
# Windowsscripts\package-plugin.bat C:\Path\To\UE_5.6

This produces a zip like McpAutomationBridge-v<version>-UE5.7-Linux.zip, where <version> is the package.json version (currently 0.6.0-beta-b).

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.

💡 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:

1. Edit > Project Settings > Plugins > MCP Automation Bridge
2. Check Enable Native MCP
3. Set port (default: 3000)
4. Optionally set Native MCP Instructions for project-specific guidance
5. 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 running, number in parens = active sessions. Click it to open settings.
• Output Log — filter by LogMcpNativeTransport to see connections, tool calls, and session activity:
  LogMcpNativeTransport: Native MCP server started on http://localhost:3000/mcpLogMcpNativeTransport: MCP session initialized: ... (client: claude-code 2.1.92, active sessions: 1)LogMcpNativeTransport: tools/call: inspect (RequestId=...)LogMcpNativeTransport: tools/call completed: ... (tool=inspect, success=true)

Features:

• SSE streaming for real-time progress during long operations
• Multiple concurrent sessions (Cursor + Claude Code + others simultaneously)
• Dynamic tool management — core tools load by default, enable more via manage_tools
• Python execution via execute_python action (inline code or .py files)
• Capability token authentication — on by default (auto-generated secret at <Project>/Saved/MCP/capability-token; manual CapabilityToken in Project Settings overrides)

Option B: TypeScript Bridge (stdio — classic setup)

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

# RequiredUE_PROJECT_PATH="C:/Path/To/YourProject"
# Automation BridgeMCP_AUTOMATION_HOST=127.0.0.1MCP_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
# LoggingLOG_LEVEL=info  # debug | info | warn | error
# OptionalMCP_CONNECTION_TIMEOUT_MS=5000MCP_REQUEST_TIMEOUT_MS=120000ASSET_LIST_TTL_MS=10000
# Optional Prometheus metrics endpoint# Loopback-only by default. Non-loopback metrics requires both explicit opt-in and a token.# MCP_METRICS_PORT=9100# MCP_METRICS_HOST=127.0.0.1# MCP_METRICS_ALLOW_NON_LOOPBACK=false# MCP_METRICS_TOKEN=change-me
# Custom content mount points (comma-separated)# Plugins with CanContainContent register mount points beyond /Game/.# MCP_ADDITIONAL_PATH_PREFIXES=/ProjectObject/,/ProjectAnimation/

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=trueMCP_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. Enable capability token authentication (Require Capability Token in project settings) to prevent unauthorized access when using LAN mode.

Available Tools

The MCP server exposes a single unreal gateway tool. The 23 canonical parent tools are internal and reachable exclusively through the gateway's four operations: search, describe, execute, and configure.

Gateway Workflow

1. search — discover available tools by keyword, category, or action name
2. describe — get the exact contract (actions, parameters, schema) for a specific tool
3. execute — run one validated action on a canonical tool
4. configure — manage internal tool enable/disable state (wraps manage_tools)

Example call:

{  "operation": "search",  "query": "asset"}

Then:

{  "operation": "describe",  "tool": "manage_asset",  "action": "import_asset"}

Then:

{  "operation": "execute",  "tool": "manage_asset",  "action": "import_asset",  "params": { "sourcePath": "/path/to/asset.fbx", "destinationPath": "/Game/Imported/asset" }}

Migration from direct tool calls

The single unreal gateway is permanent on both transports; there is no opt-out and no legacy 23-tool listing to restore. A client that still calls a canonical tool name directly (tools/call with name: "manage_asset", name: "control_actor", etc.) receives a bounded, copy-paste-executable DIRECT_TOOL_CALL_REMOVED receipt instead of a routed call. The receipt carries a nextCall that drills exactly one level: { "operation": "search" } for an unknown name, { "operation": "describe", "tool": "<tool>" } when no action was supplied, or { "operation": "execute", "tool": "<tool>", "action": "<action>", "params": { ... } } when the direct call already named an action. Run that nextCall through the unreal tool to finish the migration.

Gateway Protocol & Transport

Both transports expose the same unreal gateway contract, but they are separate lifecycles. Do not route around their boundaries.

• TypeScript stdio transport — node dist/cli.js talks to the Unreal plugin over a WebSocket bridge. It permanently exposes the single unreal gateway tool; there is no gateway-mode toggle.
• Native MCP transport — the plugin's built-in Streamable HTTP/SSE server at /mcp (no Node.js, no bridge). The native MCP surface permanently exposes the same single unreal gateway tool; there is no gateway-mode toggle.

Both surfaces negotiate the MCP protocol version at initialize; the supported set is intentionally asymmetric. The native /mcp transport supports exactly the three modern versions 2025-11-25, 2025-06-18, and 2025-03-26, and deliberately does not implement the later 2026-07-28 RC. The TypeScript stdio server also accepts the two legacy versions 2024-11-05 and 2024-10-07, so the native surface is intentionally stricter. Both negotiate down to the highest mutually supported version (2025-11-25 is the latest). See docs/protocol.md for the full negotiation and transport contract, including the MCP-Protocol-Version header guard (HTTP 400 on invalid), cancellation semantics, and progressToken handling.

Internal Canonical Tools (23)

The gateway hides these 23 canonical parent tools. They are listed here for reference:

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

Docker

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

Documentation

Development

npm run build         # Clean + compile TypeScript to dist/npm run lint          # Run ESLint 9 (fail on any warning)npm run type-check    # tsc --noEmitnpm run test:unit     # Vitest unit tests (no Unreal required)npm run test:smoke    # Offline mock in-memory MCP check (needs built dist/)npm run manifest:check   # Fail if generated gateway manifest artifacts driftnpm run test:native-parity # TS vs native canonical tool/action equalitynpm run test:params      # Parity + strict parameter auditnpm run version:check    # Assert all version sources agreenpm test                 # Integration suite (needs a live Unreal Editor + bridge)

Gateway manifest generation

The neutral gateway manifest is generated from src/tools/catalog/consolidated-tool-definitions.ts into three artifacts (runtime .ts/.json plus the native .h). Never hand-edit the generated files.

node --loader ts-node/esm scripts/generate-gateway-manifest.ts          # regeneratenode --loader ts-node/esm scripts/generate-gateway-manifest.ts --check  # CI gate: fail on drift

CI gates

CI runs, in order: ESLint 9 (npx eslint . --max-warnings=0), TypeScript type-check, unit tests, registry:check, normalization:check, manifest:check, policy:check, native parity + parameter audit (test:params), migration:check, primitives:check, security:check, eval:check, version:check, workflow:check, then a blocking runtime-only dependency audit (npm audit --omit=dev --audit-level=high) followed by an informational full-tree npm audit --audit-level=moderate. A plugin packaging job runs scripts/package-plugin.sh only when an Unreal Engine source root secret is provided (opt-in), because CI runners do not ship an engine. Release archives exclude Binaries/, Intermediate/, and Saved/ so generated build dirs never leak.

Community

Contributing

Contributions welcome! Please:

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

License

MIT — See LICENSE