ExbyteLabs/unreal-engine-mcp-system-plugin
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Unified, portable Unreal Engine MCP system plugin

Browse Source 
Merge of the two project copies into one self-contained plugin (the superset:
variable_op + variables.py, full pcg_op runtime/declarative/preset ops, the
CreateWidgetFloatAnimation widget tool, and full Voxel graph authoring).

Made fully project- and machine-agnostic — no hardcoded paths:
- New src/projectPaths.js auto-detects the host .uproject (walk-up), project
  name, Editor build target, log file, and engine install (EngineAssociation
  via launcher manifest/registry, else installed-engine scan). All overridable
  via UE_* env vars.
- Rewired buildOrchestrator/insights/launcher/insightsExporter/server.js and the
  Python workers (cpp_scaffold, live_coding, apply_graph, console) off the old
  C:/Github/ihy, IHY*, E:/UE_Versions and UE_5.7 literals onto the resolver.
- Voxel made optional: Build.cs auto-detects the Voxel plugin (env
  UE_MCP_WITH_VOXEL override) and the C++ compiles to stubs under WITH_MCP_VOXEL,
  so the module builds in projects without Voxel; .uplugin marks Voxel optional.
- De-branded the agent-gateway and docs; scrubbed a leaked API key; excluded
  node_modules/Binaries/Intermediate/__pycache__/secrets from the repo.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
Bonchellon
2026-06-24 01:07:24 +03:00
parent d46e03e53e
commit eba71c4ca8
76 changed files with 23838 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

120
README.md
View File

@ -1,2 +1,120 @@
# unreal-engine-mcp-system-plugin
# Unreal Engine MCP System Plugin
A drop-in Unreal Engine **editor plugin** that exposes the UE editor to an
[MCP](https://modelcontextprotocol.io) 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. Install the MCP server deps:
```bash
cd Plugins/UEBlueprintMCP
npm install
```
6. Point your MCP client at `src/server.js`, e.g.:
```json
{
"mcpServers": {
"ue-blueprint": {
"command": "node",
"args": ["<abs-path>/Plugins/UEBlueprintMCP/src/server.js"]
}
}
}
```
Call `ping_ue` first to confirm the editor is reachable.
---
## 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](https://voxelplugin.com) 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.