unreal-mcp-ue4

UE4.26.2 / UE4.27-focused MCP server for Unreal Engine using Unreal Python Remote Execution

中文文档：README_zh.md

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.26.2 and 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.26/4.27-specific limitations may still surface.

Published packages (same code, shipped under two names):

• Short alias: ue4-mcp — recommended for end-users
• Canonical scoped name: @pjkui/unreal-mcp-ue4

Registry name: io.github.pjkui/unreal-mcp-ue4

This is an independent fork. The original unreal-mcp-ue4 npm package is still maintained at conaman/unreal-mcp-ue4; see Credits & Attribution below.

Credits & Attribution

This project is a derivative work, distributed under the MIT License. The original copyright notices are retained and the original authors are gratefully acknowledged.

• Original project (upstream root): runreal/unreal-mcp — Copyright (c) 2025 runreal. The core idea, initial MCP wiring, and early tool surface originated there.
• UE4-focused fork and original npm publisher: conaman/unreal-mcp-ue4 — Copyright (c) 2025-2026 Seungjee Baek / conaman. The current unreal-mcp-ue4 npm package, the UE4.27-focused refactor, the tool-namespace layer, the smoke-test suite, and most of the existing documentation come from this repository. Much of the code in this fork is still based directly on that work.
• This fork: pjkui/unreal-mcp-ue4 — Copyright (c) 2026 pjkui. Adds UE4.26.2 compatibility, Chinese documentation (README_zh.md), packaging tweaks, and miscellaneous fixes.

Thanks to runreal for open-sourcing the original implementation, and to conaman for the substantial UE4-oriented refactor and for publishing unreal-mcp-ue4 on npm. If you build on this project, please also credit the upstream projects above.

See the LICENSE file for the full copyright statement.

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.26/4.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.26/4.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 (shared across 4.26 and 4.27): 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.26.2 or 4.27.2
• Node.js 18+
• npm
• An MCP client such as Codex, Claude Desktop, Cursor, or GitHub Copilot in a supported IDE

Required Unreal Editor Setup

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

Required plugins

• Python Editor Script Plugin
• Editor Scripting Utilities

Required project setting

• Edit -> Project Settings -> Python -> Enable Remote Execution

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.

Installation

1. Clone and build the server

git clone https://github.com/pjkui/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.

1a. Install from npm

Once the package is published on npm, you can install it directly instead of cloning the repository.

Global install (recommended for end-users):

npm install -g ue4-mcp

One-off invocation with npx:

npx --yes ue4-mcp

The exact same code is also published as the scoped package @pjkui/unreal-mcp-ue4; pick whichever fits your workflow:

npm install -g @pjkui/unreal-mcp-ue4
# or one-off:
npx --yes -p @pjkui/unreal-mcp-ue4 ue4-mcp

Either package ships the same CLI binary named ue4-mcp.

2. Enable the Unreal requirements

In Unreal Editor:

1. Open the target UE4.26.2 or UE4.27.2 project.

2. Go to Edit -> Plugins.

3. Enable Python Editor Script Plugin.

4. Enable Editor Scripting Utilities.

5. Restart the editor if prompted.

6. Go to Edit -> Project Settings -> Python.

7. Enable Enable Remote Execution.

8. Restart the editor again if needed.

3. Configure your MCP client

Most clients use a local stdio server command. Pick the option that best matches how you installed the server.

Option 1 (recommended) — global install + bare ue4-mcp command

Install once:

npm install -g ue4-mcp
# equivalent: npm install -g @pjkui/unreal-mcp-ue4

Then in the client config just call the binary directly:

{
  "mcpServers": {
    "unreal-ue4": {
      "command": "ue4-mcp"
    }
  }
}

This is the fastest option to start (no cold-start download per launch), is easy for users to understand, and works the same way on macOS, Linux, and Windows as long as the npm global bin directory is on PATH.

If your MCP client cannot find ue4-mcp on PATH, use the absolute path to the installed binary:

# locate it:
npm root -g
# Windows example: C:\Users\<you>\AppData\Roaming\npm\node_modules
# The binary sits next to node_modules at:
#   C:\Users\<you>\AppData\Roaming\npm\ue4-mcp.cmd
#   /usr/local/bin/ue4-mcp on macOS/Linux

{
  "mcpServers": {
    "unreal-ue4": {
      "command": "C:\\Users\\YourName\\AppData\\Roaming\\npm\\ue4-mcp.cmd"
    }
  }
}

Behind a corporate npm mirror? Some mirrors deliver corrupted ajv tarballs which will make this server fail to start. Install against the public registry instead: npm install -g ue4-mcp --registry=https://registry.npmjs.org/.

Option 2 — npx (no global install, always-latest)

Good if you want to always pick up the newest release without re-installing:

{
  "mcpServers": {
    "unreal-ue4": {
      "command": "npx",
      "args": ["--yes", "ue4-mcp@latest"]
    }
  }
}

Force the public npm registry (strongly recommended if your default is a corporate mirror):

{
  "mcpServers": {
    "unreal-ue4": {
      "command": "npx",
      "args": ["--yes", "ue4-mcp@latest"],
      "env": {
        "npm_config_registry": "https://registry.npmjs.org/"
      }
    }
  }
}

Trade-off: each cold start may take a few seconds while npx checks for updates, and if the ~/.npm/_npx cache gets corrupted by a flaky mirror you will need to clear it manually.

Option 3 — local development build (unpublished code)

When iterating on this repository itself and you do not want to publish, point the client at the freshly built dist/bin.js:

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

If node is already on your PATH, "command": "node" is enough; otherwise use the absolute path to the node executable. Remember to run npm run build after every change.

Codex example

Once the package is installed globally:

codex mcp add unreal-ue4 -- ue4-mcp

Or via npx (no global install):

codex mcp add unreal-ue4 -- npx --yes ue4-mcp@latest

Local development fallback:

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

Note: the CLI binary is ue4-mcp. Both npm package names (ue4-mcp and @pjkui/unreal-mcp-ue4) expose the same executable; if you install both globally they overwrite each other harmlessly since they are the same code.

GitHub Copilot example

For VS Code, create .vscode/mcp.json.

Recommended (global install):

{
  "servers": {
    "unreal-ue4": {
      "command": "ue4-mcp"
    }
  }
}

Using npx instead:

{
  "servers": {
    "unreal-ue4": {
      "command": "npx",
      "args": ["--yes", "ue4-mcp@latest"]
    }
  }
}

Local development:

{
  "servers": {
    "unreal-ue4": {
      "command": "node",
      "args": [
        "C:\\Users\\YourName\\dev\\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

Usage

Interface model

• Prefer the manage_* namespace tools as the main MCP surface.
• 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.26.2 or 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. Build the MCP server 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:

• 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.26/4.27-safe UMG helpers.
• Run grouped tool namespaces that dispatch through action and params.

Testing

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:

• npm run test:e2e -- --with-assets --keep-assets keeps the generated test assets so you can inspect them in the Content Browser after the run.
• npm run test:e2e -- --skip-namespace skips the namespace-dispatch portion of the smoke run.
• npm run test:e2e -- --verbose prints MCP server stderr during the run.
• npm run test:e2e -- --help prints the runner options without rebuilding the server.

Windows test commands

Open PowerShell in the repository folder:

cd C:\dev\unreal-mcp-ue4
npm install
npm run test:e2e
npm run test:e2e -- --with-assets

What success looks like

• The console prints [PASS] for every test step.
• Actor tests visibly create and then remove temporary actors in the editor through both the direct-tool and namespace surfaces.
• The asset-inclusive test creates temporary Blueprint, DataAsset, StringTable, Texture, and Widget Blueprint assets under /Game/MCP/Tests and then removes them before exit unless --keep-assets is used.

Recommended test workflow

1. Start with npm run test:e2e.
2. If that passes, run npm run test:e2e -- --with-assets.
3. After both pass, try the server once from your real MCP client.
4. Use a separate Unreal test project before pointing the server at production content.

Publishing to npm

This repository is dual-published under two npm package names that share the exact same built artifact:

• ue4-mcp (short, non-scoped public name)
• @pjkui/unreal-mcp-ue4 (scoped canonical name)

The project version format is unified everywhere as the semver-compatible date form YYYY.M.D-N. For example, this fork's current release is 2026.4.23-2.

Recommended maintainer flow:

1. Bump the project version with npm run set:version 2026.4.23-3 (updates package.json, package-lock.json, server.json, server/version.ts in one shot).
2. Run the publish preflight on the canonical scoped name:

npm run publish:check

3. If you have a running UE4.26.2 or UE4.27.2 editor test environment available, also run:

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

4. Dual-publish both names with one command (requires a granular npm token with Bypass 2FA requirement when publishing enabled, or a one-time TOTP code):

# with a granular token
NPM_TOKEN=npm_xxx npm run publish:both

# with a 2FA one-time code
npm run publish:both -- --otp=123456

# simulate only, no auth needed
npm run publish:both -- --dry-run

Notes:

• scripts/publish-both.mjs publishes @pjkui/unreal-mcp-ue4 with package.json untouched, then temporarily rewrites the name field to ue4-mcp, publishes again, and restores package.json. The token is never written to ~/.npmrc.
• prepack runs npm run build, so the published tarball always uses a fresh dist.
• npm run publish:check verifies typecheck, rebuilds the package, and runs npm pack --dry-run so you can inspect the exact tarball contents before publishing.
• Because the unified date version uses a semver prerelease suffix, the script publishes both packages with an explicit --tag latest so npm install resolves to them by default.

Troubleshooting

Remote node is not available

• Make sure Unreal Editor is fully open before running the MCP client or smoke test.
• Verify that Python Editor Script Plugin is enabled.
• Verify that Editor Scripting Utilities is enabled.
• Verify that Enable Remote Execution is enabled in project settings.
• Restart Unreal Editor after changing any of the above.

Connection or discovery problems on Windows

• Allow UnrealEditor.exe and node.exe through Windows Defender Firewall.
• The bundled unreal-remote-execution package uses UDP multicast discovery on 239.0.0.1:6766 and a localhost command channel on 127.0.0.1:6776.
• If your client config uses JSON, escape backslashes or switch to forward slashes.

Client starts but cannot find node

• Use an absolute path to node or node.exe in the MCP config instead of relying on PATH.

Some Blueprint graph or UMG binding commands are unavailable

• Widget Blueprint creation and common widget-tree editing work in this fork; the main UMG gaps are delegate binding helpers and runtime-dependent viewport flows.
• Blueprint asset creation, component editing, compilation, and high-level asset summaries work; graph inspection, graph pin wiring, and variable or function metadata helpers are intentionally excluded because stock UE4.26/4.27 Python does not expose the required Blueprint metadata reliably.
• Capability areas that are not reliable enough to keep in the MCP surface are listed under Excluded Capability Areas in the tool section.

Notes and Limitations

• World-building and structure-generation tools use UE4.26/4.27-friendly preset builders based on engine basic-shape assets.
• Common UMG widget-tree editing works well with CanvasPanel-based layouts, but delegate binding helpers remain unavailable in stock UE4.26/4.27 Python.
• UMG positioning currently targets CanvasPanel slots in UE4.27.
• Reparenting the current root widget and editing named-slot content are not currently handled.
• Blueprint asset and component editing work, but Blueprint graph inspection, pin wiring, and variable or function metadata inspection are excluded in the stock UE4.26/4.27 Python environment.
• The tool surface includes both granular tools and action-based tool namespaces so different MCP clients can work at different abstraction levels.

The tool list below is generated from server/index.ts during build.

Available Tools

Notes call out important requirements or UE4.26/4.27 limitations when they matter. Empty notes mean there are no additional caveats beyond normal editor setup.

The recommended public surface is the manage_* namespace layer. Prefer manage_editor.project_info, manage_editor.map_info, and manage_level.world_outliner as canonical read entry points, and treat the small direct-tool set as low-level primitives for path discovery and actor CRUD.

Editor Session Info

Core Direct Tools

Core Tool Namespaces

World & Environment Tool Namespaces

Content & Authoring Tool Namespaces

Gameplay & Systems Tool Namespaces

Excluded Capability Areas

These capability areas are intentionally not exposed through the MCP surface in this UE4.26/4.27 port because they fail reliably in the current Python environment and only add prompt or context overhead until a native bridge exists.

| Capability Area | Effect on MCP Surface | Why It Is Excluded | |-----------------|-----------------------|---------------------| | Blueprint event-graph event insertion | Related event-node and input-action helpers are excluded from the MCP surface. | The current UE4.26/4.27 Python environment does not expose reliable event graph access or K2 event reference setup. | | Blueprint graph inspection and node search | Graph-analysis, graph-inspection, and node-search helpers are excluded from the MCP surface. | The current UE4.26/4.27 Python environment does not expose Blueprint graph arrays such as UbergraphPages or FunctionGraphs reliably enough for deterministic inspection. | | Low-level Blueprint graph node creation | Generic graph-node helpers and related self or component reference insertion helpers are excluded from the MCP surface. | The current UE4.26/4.27 Python environment does not expose stable low-level graph node creation or member-reference wiring. | | Blueprint function-call node authoring | Function-node helpers that depend on editor graph member-reference setup are excluded from the MCP surface. | The current UE4.26/4.27 Python environment does not expose reliable function-call node reference setup. | | Blueprint variable and function metadata inspection | Variable-detail and function-detail helpers are excluded from the MCP surface. | The current UE4.26/4.27 Python environment does not expose NewVariables or FunctionGraphs reliably enough for deterministic inspection. | | Blueprint variable authoring | Variable-creation helpers are excluded from the MCP surface. | BPVariableDescription and EdGraphPinType are not exposed in the current UE4.26/4.27 Python environment. | | UMG delegate-binding authoring | Widget event-binding and text-binding helpers are excluded from the MCP surface. | DelegateEditorBinding is not exposed in the current UE4.26/4.27 Python environment. |

License

Licensed under the MIT License.

This project is a derivative work. Copyright is held jointly by runreal (original project), Seungjee Baek / conaman (the UE4-focused fork and original npm publisher of unreal-mcp-ue4), and pjkui (this fork). All prior copyright notices are retained as required by the MIT License. See the LICENSE file and the Credits & Attribution section for details.