unreal-engine-mcp-system-plugin/README.md

Unreal Engine MCP System Plugin

A drop-in Unreal Engine editor plugin that exposes the UE editor to an MCP client (Claude Code, Cursor, etc.) as a rich set of tools: Blueprint graph CRUD, UMG/Slate authoring with a screenshot vision loop, materials, Niagara, PCG (incl. PCGEx), assets, member variables, C++ scaffolding & rebuild, headless asset/scene capture, Unreal Insights analysis, the Project Launcher, and more.

It has two halves that ship together:

Part	Lives in	What it is
C++ editor module	Source/UEBlueprintMCPEditor/	UEBlueprintMCPEditor — Blueprint function libraries the Python workers call.
MCP server	src/ (Node.js) + ue_side/ (Python)	A stdio MCP server that drives the editor over Remote Control.

Portable by design. Nothing is hardcoded to a project, user, or machine. The server discovers the host .uproject, project name, Editor build target, log file, and engine install automatically from where the plugin sits on disk. Every value can still be overridden with an environment variable (below).

---

Install

1. Clone (or submodule) this repo into your project's Plugins/ folder. The folder name doesn't matter to UE — the plugin is identified by UEBlueprintMCP.uplugin:

   <YourProject>/Plugins/UEBlueprintMCP/        <- this repo
   

2. Enable the engine plugins it builds against (most are on by default): Python Editor Script Plugin, Remote Control API, Niagara. (Voxel is optional — see below.)

3. Generate project files and build the editor (the plugin has a C++ module).

4. In the editor, enable Remote Control and start its web server (WebControl.StartServer, or set WebControl.EnableServerOnStartup=true).

5. Run the setup wizard — it installs deps, confirms the auto-detected project/engine, checks the editor side, and prints the exact client-config snippet to paste:

   cd Plugins/UEBlueprintMCP
   npm run setup
   

   (Prefer to do it by hand? npm install, then point your client at src/server.js as below.)

6. Point your MCP client at src/server.js, e.g.:

   {
     "mcpServers": {
       "ue-blueprint": {
         "command": "node",
         "args": ["<abs-path>/Plugins/UEBlueprintMCP/src/server.js"]
       }
     }
   }
   

   Call ping_ue first to confirm the editor is reachable.

First-run check & doctor

The first time the server starts it prints a one-time environment check to its stderr (visible in your client's MCP logs) and points you at npm run setup if anything is off. You can re-run the checks any time:

• npm run doctor — print the diagnostics report in a terminal.
• the doctor MCP tool — same checks from inside a session, so the assistant can diagnose and guide you.

The wizard pins any overrides (project dir, engine dir, Remote Control URL, ...) to a git-ignored mcp.config.json. Precedence everywhere is env var > config > auto-detect.

---

Zero-config path resolution

src/projectPaths.js resolves everything from the plugin's location:

• Project — walks up from the plugin to the nearest *.uproject.
• Project name / Editor target / log file — derived from that .uproject (<Name>, <Name>Editor, Saved/Logs/<Name>.log).
• Engine — read from the project's EngineAssociation, resolved via the Epic launcher manifest / registry, falling back to a scan of installed engines.

Environment overrides

Variable	Overrides
UE_PROJECT_DIR	the .uproject parent folder
UE_UPROJECT_NAME	e.g. MyGame.uproject
UE_BUILD_TARGET	e.g. MyGameEditor
UE_BUILD_CONFIG	build config (default Development)
UE_ENGINE_DIR	engine root (the folder containing /Engine)
UE_INSIGHTS_EXE	full path to UnrealInsights.exe
UE_REMOTE_CONTROL_URL	Remote Control base URL (default http://127.0.0.1:30010)
UE_MCP_WITH_VOXEL	1/0 to force the optional Voxel integration on/off

---

Optional: Voxel integration

The voxel_graph_op tool authors Voxel Plugin graphs. Voxel is heavy and most projects don't have it, so the plugin compiles with or without it:

• The build auto-detects the Voxel plugin. If present, voxel support is enabled (WITH_MCP_VOXEL=1); otherwise the C++ compiles to stubs and voxel_graph_op returns a "Voxel not enabled" error.
• Force it with UE_MCP_WITH_VOXEL=1 (errors if Voxel is missing) or disable with UE_MCP_WITH_VOXEL=0.

---

Optional: in-engine agent gateway

agent-gateway/ is a small HTTP gateway that lets an in-engine WebBrowser widget talk to the MCP server through the Claude Agent SDK. It is not required for MCP clients — see agent-gateway/README.md. Copy agent-gateway/auth.env.example to agent-gateway/auth.env and add your token; that file is git-ignored.

---

Docs

• UI_WORKFLOW.md — the mandatory protocol for any UMG/UI work (theme tokens, components, the screenshot vision loop).
• FUTURE_MCP_TOOLS.md — backlog of tool ideas.