unreal-mcp-ue4-for-OHD

UE4.25.4-first MCP server for Operation Harsh Doorstop modding via Unreal Python Remote Execution (stdio transport)

Fork of runreal/unreal-mcp, heavily refactored UE4-first (via a UE4.27.2 stage) and retargeted here to UE4.25.4 for the OHDCore Mod Kit: same transport and tool surface, with version pins, docs links, and Python-dialect constraints adjusted for the kit's embedded Python 2.7.14. Port, tool, docs, and smoke-test work were developed with assistance from OpenAI Codex.

[!NOTE] Still under active development — expect bugs, rough edges, and UE4.25-specific limitations. Published package: unreal-mcp-ue4-for-ohd · Registry name: io.github.RibatTRW/unreal-mcp-ue4-for-ohd

[!CAUTION] Not an official Epic Games project. Any connected MCP client can inspect and modify your open editor session — use a disposable test project first, especially for asset or world-generation tools.

Contents

• Requirements · Setup · Migrating from unreal-mcp-ue4 · Editor remote execution · Usage · Sidebar tab · Internals · Testing · Publishing · Available Tools · Contributing · Troubleshooting · Notes and Limitations · Roadmap · License

Requirements

Reference: Unreal Engine Python API 4.25. No custom C++ plugin is required — the server uses the editor's built-in Python Remote Execution. UE5-only scripting features are not reintroduced; unreliable graph/binding flows are excluded from the MCP surface or return a clear message instead of failing silently.

graph TD
    A[MCP client] --> B[unreal-mcp-ue4-for-ohd stdio server]
    B --> C[manage_* namespaces + direct tools]
    C --> D[Python 2.7 payloads]
    D --> E[Unreal Editor via Remote Execution]

Setup

Autonomous agents setting up unattended: follow the ordered guide in docs/agent-setup.md.

npm install -g unreal-mcp-ue4-for-ohd   # recommended; then reference the `unreal-mcp-ue4-for-ohd` binary
npx unreal-mcp-ue4-for-ohd              # one-off invocation

Local source checkout:

git clone https://github.com/RibatTRW/unreal-mcp-ue4-for-OHD.git
cd unreal-mcp-ue4-for-OHD
npm install
npm run build   # produces `dist/bin.js`, `dist/index.js`, `dist/editor/tools.js`

One install, then one line per client (global vs local-checkout variants). All clients call the same 34 tools over stdio (3 session-info + 3 direct actor CRUD primitives + 28 manage_* namespaces):

Copilot docs: Extending GitHub Copilot Chat with MCP servers · About Model Context Protocol in GitHub Copilot

Migrating from unreal-mcp-ue4

This fork was renamed to its own identity so it can ship independently of upstream. Upstream credit: the UE4 line derives from conaman/unreal-mcp-ue4 (itself forked from runreal/unreal-mcp).

[!WARNING] npm install -g unreal-mcp-ue4 installs upstream's UE4.27 build, not this fork. For the OHD/UE4.25.4 retarget, install the renamed package instead.

Re-add the server in your client (local server labels such as unreal-ue4 are unchanged — only the command changes):

claude mcp add --scope user unreal-mcp-ue4-for-ohd -- unreal-mcp-ue4-for-ohd
codex mcp add unreal-ue4 -- unreal-mcp-ue4-for-ohd

Copilot .vscode/mcp.json: change "command" to "unreal-mcp-ue4-for-ohd", keeping the unreal-ue4 server key.

Editor remote execution

Verified live against the kit. In the OHD editor (LaunchEditor.bat → HarshDoorstop.uproject):

1. Edit -> Plugins: enable Python Editor Script Plugin (ships disabled). Editor Scripting Utilities is already enabled — no action needed. Enable SequencerScripting (ships disabled) only for advanced manage_sequence actions: actor binding, track/key edits, camera cuts, playback ranges, speed-track analysis.
2. Restart if prompted → Edit -> Project Settings -> Plugins -> Python → enable Enable Remote Execution (endpoint 239.0.0.1:6766, bind 0.0.0.0, raise Multicast TTL from kit default 0 to 1). Restart again if needed.
3. Keep the project open while using the server or tests; restart the editor after any plugin/Python setting change.
4. No UMG plugin to install (tooling uses shipped editor modules). Do mod experiments in a throwaway content-only mod (Create Mod in the editor); never edit shipped Plugins/*, HDAssets, or engine content.

Connection env overrides (UNREAL_MCP_*):

Usage

• Prefer manage_* namespace tools (action-specific input schemas are exposed over MCP). Namespaces dispatch through action + params. Canonical reads: manage_editor.project_info (project), manage_editor.map_info + manage_level.world_outliner (map/level). Discover the surface with manage_tools (list_namespaces).
• Direct tools (get_unreal_*, editor_create/update/delete_object) are low-level primitives for session path discovery and actor CRUD.
• manage_editor.run_python is the escape hatch for debugging, prototyping, and UE4.25 API gaps — still Python 2.7-compatible.

First run: open the kit project and wait for load → confirm plugins + remote execution → npm install -g unreal-mcp-ue4-for-ohd (or npm run build) → open/start the client session → run something read-only:

• unreal-mcp-ue4-for-ohd --version (prints version, no stdio transport)
• manage_editor + action: "project_info" / "map_info" · manage_level + "world_outliner" · manage_tools + "list_namespaces"
• In prose: 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/actor info; spawn, inspect, move, delete level actors; search assets and inspect references/metadata; create DataAsset/StringTable and other common UE4 data assets; create/edit Blueprint assets and Widget Blueprint trees where UE4.25 Python exposes the APIs.

Sidebar tab

One call sets up the EUW (Editor Utility Widget) sidebar tab end to end — an EUW asset plus a WebBrowser child hosting a web page beside the viewport:

manage_widget + action: "setup_sidebar_tab", params widget_blueprint_path (e.g. /Game/DSHSidebar), url (any page URL; the DSH web GUI is the convention), use_template: true (missing target is duplicated from the golden template — full-fill DSHBrowser + verified On Key Down shortcut fix — instead of built from scratch; re-runs are idempotent, reusing existing targets while refreshing URL/layout).