unreal-mcp-ue4

UE4.27.2-focused MCP server for Unreal Engine using Unreal Python Remote Execution

unreal-mcp-ue4 started from the core idea and early workflow shape of runreal/unreal-mcp, but it has since been heavily refactored for Unreal Engine 4.27.2 and expanded with many new tools, UE4-specific compatibility layers, documentation, and smoke coverage. At this point, the original inspiration remains, but the public surface and day-to-day behavior are substantially different and UE4-first.

This port and the follow-up tool, documentation, and smoke-test work were developed with assistance from OpenAI Codex.

This project is still under active development, so bugs, rough edges, and UE4.27-specific limitations may still surface.

Published package: unreal-mcp-ue4
Registry name: io.github.conaman/unreal-mcp-ue4

Overview

• No custom Unreal C++ plugin from this repository is required.
• The server talks to the editor through Unreal's built-in Python Remote Execution path.
• The tool surface is organized into granular tools and higher-level tool namespaces.
• UE5-only editor scripting features are not reintroduced; UE4.27-safe operations work normally, while unreliable graph or binding flows are either excluded from the MCP surface or return a clear message instead of silently failing.

Origin

• Original inspiration and starting point: runreal/unreal-mcp
• The current codebase has gone through extensive UE4.27-focused refactoring, architecture changes, and tool expansion.
• In practice, the shared idea is still visible, but the implementation, scope, and supported workflows now reflect a separate UE4-first project.
• Unreal Python API reference: Unreal Engine Python API 4.27

Safety

• This is not an official Epic Games project.
• Any connected MCP client can inspect and modify your open Unreal Editor session.
• Use a disposable test project first, especially when trying asset or world-generation tools.

Requirements

• Unreal Engine 4.27.2
• Node.js 18+
• npm
• An MCP client such as Codex, Claude Code, Claude Desktop, Cursor, or GitHub Copilot in a supported IDE

MCP Client Setup

This is the most important setup step: your MCP client must know how to launch unreal-mcp-ue4.

1. Install the server

Recommended global install:

npm install -g unreal-mcp-ue4

After the global install, use the published unreal-mcp-ue4 binary in your client configuration.

One-off invocation with npx:

npx unreal-mcp-ue4

Local source checkout:

git clone https://github.com/conaman/unreal-mcp-ue4.git
cd unreal-mcp-ue4
npm install
npm run build

Successful build output should create dist/bin.js, dist/index.js, and dist/editor/tools.js. Use the dist/bin.js path in the local source checkout examples below.

2. Register the server in your client

Use the global examples when you installed with npm install -g unreal-mcp-ue4. Use the local source checkout examples when you are developing from a cloned repository.

Claude

Global npm install:

claude mcp add --scope user unreal-mcp-ue4 -- unreal-mcp-ue4

Local source checkout:

claude mcp add --scope user unreal-mcp-ue4 -- node /absolute/path/to/unreal-mcp-ue4/dist/bin.js

Codex

Global npm install:

codex mcp add unreal-ue4 -- unreal-mcp-ue4

Local source checkout:

codex mcp add unreal-ue4 -- node /absolute/path/to/unreal-mcp-ue4/dist/bin.js

GitHub Copilot

Create or update .vscode/mcp.json.

Global npm install:

{
  "servers": {
    "unreal-ue4": {
      "command": "unreal-mcp-ue4",
      "args": []
    }
  }
}

Local source checkout:

{
  "servers": {
    "unreal-ue4": {
      "command": "node",
      "args": [
        "/absolute/path/to/unreal-mcp-ue4/dist/bin.js"
      ]
    }
  }
}

Then start the server from the MCP config UI and verify that unreal-ue4 appears in the tools picker.

Official Copilot docs:

• Extending GitHub Copilot Chat with MCP servers
• About Model Context Protocol in GitHub Copilot

3. Enable Unreal Editor remote execution

This repository does not ship its own Unreal plugin. Instead, it depends on built-in editor features that must be enabled in your UE4.27.2 project.

In Unreal Editor:

1. Open the target UE4.27.2 project.
2. Go to Edit -> Plugins.
3. Enable Python Editor Script Plugin.
4. Enable Editor Scripting Utilities.
5. Enable SequencerScripting if you want to use advanced manage_sequence actions such as actor binding, track or key edits, camera cuts, playback ranges, and speed-track analysis.
6. Restart the editor if prompted.
7. Go to Edit -> Project Settings -> Python.
8. Enable Enable Remote Execution.
9. Restart the editor again if needed.

Notes:

• UMG tooling works with editor modules that already ship with Unreal Editor. There is no extra UMG plugin from this repository to install.
• Keep the target Unreal project open while using the MCP server or running tests.
• If you change plugin or Python settings, restart the editor before testing again.

Usage

Interface model

• Prefer the manage_* namespace tools as the main MCP surface.
• Namespace tools now expose action-specific input schemas through MCP, so clients can discover the expected params keys per action instead of relying only on trial and error.
• Treat manage_editor.project_info as the canonical project summary entry point.
• Treat manage_editor.map_info and manage_level.world_outliner as the canonical map and level read entry points.
• Use direct tools only for a small set of low-level primitives such as Unreal session path discovery and actor create or update or delete flows.
• Use manage_editor.run_python as an escape hatch for debugging, rapid prototyping, and UE4.27 API gaps that are not yet wrapped as stable tools.

Recommended first-run flow

1. Open your UE4.27.2 project and wait for the editor to finish loading.
2. Make sure the required plugins and Enable Remote Execution are enabled.
3. Install the MCP server globally with npm install -g unreal-mcp-ue4, or build your local checkout with npm run build.
4. Start your MCP client or open a new session in the client that already references this server.
5. Run a small read-only command first.

Useful first commands:

• unreal-mcp-ue4 --version to print the MCP server package version without starting stdio transport.
• manage_editor with action: "project_info"
• manage_editor with action: "map_info"
• manage_level with action: "world_outliner"
• manage_tools with action: "list_namespaces"

Useful first natural-language requests:

• Get project info from the unreal-ue4 server.
• List the actors in the current level.
• Spawn a StaticMeshActor named TestCube at 0,0,100.

What the server can do

• Read project, map, asset, and actor information from the open editor.
• Spawn, inspect, move, and delete actors in the current level.
• Search assets and inspect references or metadata.
• Create common UE4 data assets such as DataAsset and StringTable assets.
• Create and edit Blueprint assets where UE4.27 Python exposes the necessary editor APIs.
• Create and edit Widget Blueprint trees with UE4.27-safe UMG helpers.
• Run grouped tool namespaces that dispatch through action and params.

Testing

No-Unreal smoke test

Use this when you want to verify MCP startup, tool discovery, namespace action schemas, and action-specific parameter validation without launching Unreal Editor.

npm run test:no-unreal

Quick smoke test

The smoke test builds the server, launches its own local MCP server process, connects to the already running Unreal Editor, and runs a deterministic validation flow. You do not need to start a separate MCP server manually before this test.

npm run test:e2e

This checks:

• MCP server startup
• tool discovery
• project info, map info, and world outliner reads
• source-control provider and state reads
• direct-tool actor create, update, and delete
• namespace-layer actor spawn, search, transform, inspect, and delete
• tool-namespace discovery and namespace-layer dispatch for source control and actor control

Asset-inclusive smoke test

npm run test:e2e -- --with-assets

This adds:

• Blueprint creation
• Blueprint component editing
• Blueprint mesh assignment
• Blueprint compilation
• DataAsset creation
• DataAsset metadata readback
• StringTable creation
• Texture import and metadata readback
• Widget Blueprint creation
• TextBlock and Button insertion
• advanced CanvasPanel and child-widget add, move, and remove flows
• cleanup of temporary assets under /Game/MCP/Tests

Useful options: