mcp-unreal

This repository is a fork/mirror of the mcp-unreal Unreal Engine Model Context Protocol server originally published under remiphilippe/mcp-unreal.

It provides an MCP server that lets compatible coding agents inspect and operate an Unreal Engine project through a combination of headless Unreal command-line tools, the built-in Remote Control API, and the companion MCPUnreal editor plugin.

• Status: functional upstream-derived tooling; treat this repository as a maintained fork unless local commits explicitly establish a divergent product contract.
• Primary implementation: Go MCP server plus Unreal Engine editor plugin.
• Target: Unreal Engine 5.7-era workflow in the current documented codebase.
• Transport: MCP over stdio; editor-side operations use localhost HTTP interfaces.
• License: Apache-2.0; preserve upstream attribution and license terms.
• Last README review: 2026-08-18.

The tool surface covers major Unreal workflows including:

• project build, cook, project-file generation, and automation tests;
• Unreal documentation/class lookup;
• actor discovery/spawn/move/property access;
• Blueprint inspection and modification;
• assets, materials, levels, PCG/GAS/Niagara, and mesh-oriented editor operations;
• PIE control and viewport/player interaction;
• project/config file operations.

Headless tools can run through Unreal command-line programs without the editor. Deep editor operations require Unreal Editor plus the MCPUnreal plugin. Remote-control operations require the Unreal Remote Control API.

• Go 1.25+ for building the server from source.
• Unreal Engine 5.7-compatible installation for the currently documented target.
• Remote Control API enabled for property/function access.
• plugin/ installed into the target project's Plugins/MCPUnreal/ directory for advanced editor operations.

go build ./cmd/mcp-unreal

or use the repository's Make targets where available.

To build the documentation index, run the built binary with:

mcp-unreal --build-index

Set MCP_UNREAL_PROJECT to the target .uproject file or project root and register the built mcp-unreal executable as a stdio MCP server.

Example Codex configuration:

[mcp_servers.mcp-unreal]
command = "/path/to/mcp-unreal"
args = []
tool_timeout_sec = 120

[mcp_servers.mcp-unreal.env]
MCP_UNREAL_PROJECT = "/path/to/MyProject/MyProject.uproject"

Example Claude Code registration:

claude mcp add mcp-unreal -- /path/to/mcp-unreal

For editor calls, verify the editor-side interfaces before using mutation tools:

curl http://localhost:30010/remote/info

The companion plugin normally serves its local API on port 8090 in the documented configuration.

MCP client
   │ stdio / JSON-RPC
   ▼
mcp-unreal Go server
   ├── headless UnrealEditor-Cmd / UBT / UAT
   ├── UE Remote Control API (localhost)
   ├── MCPUnreal editor plugin (localhost)
   └── local UE documentation index

See IMPLEMENTATION.md and plugin/README.md for the detailed architecture and plugin contract.

This server can expose high-impact project and editor mutation tools. Treat project selection and MCP permissions as an authority boundary:

• verify the exact .uproject before mutating;
• use source control and inspect diffs after automated changes;
• save/compile Blueprints deliberately;
• run build/tests after code changes;
• do not expose the editor/plugin HTTP ports to untrusted networks;
• prefer read-only discovery first when the target project is unfamiliar.

The useful next step for this fork is to pin the exact upstream revision and local divergence, run the server/plugin test surface against the Unreal version actually used by the owning project, and document any fork-specific changes rather than inheriting upstream compatibility claims automatically.

Upstream project: remiphilippe/mcp-unreal. Preserve upstream copyright/license notices when redistributing this fork.