UE BPToolkit

Blueprint read / review / generate toolkit for AI coding agents (ZCode, Claude Code, Cursor, any MCP client) on Unreal Engine 5.4+.

.uasset blueprints are binary and UE's Python API cannot touch graph internals (EdGraph.Nodes is protected) — so agents can't see your blueprint logic. UE_BPToolkit ships a small editor-side C++ plugin that exposes safe read/write primitives, a warm headless-editor session that drives them, and an MCP server + CLI on top.

Verified on UE 5.4.4 with the City Sample project (985+ node blueprints, Wwise audio integration).

What you can do

Architecture

MCP client (ZCode / Claude Code)          CLI (bpt)
        │  MCP stdio                           │
        ▼                                      ▼
  bptoolkit-mcp ────────────┬──────────── bptoolkit.cli
                            ▼
                  SessionManager ── file-based job queue ──► headless UnrealEditor-Cmd.exe
                  (starts once, stays warm)                   └─ BPToolkit plugin (C++)
                                                                  └─ EdGraph primitives

• First tool call boots the editor (30–90 s); subsequent calls are fast. The session lives in <project>/Saved/BPToolkit/ and shuts down when your MCP server stops.

• The C++ plugin (UEPlugin/BPToolkit) exposes ~14 UFUNCTIONs (dump / create / add component-variable-functiongraph / spawn event-call-variable-self nodes / connect pins / set defaults / compile / save). Write operations take the UBlueprint object directly; nodes are addressed by GUID.

Install

Requirements: Python 3.10+, Unreal Engine 5.4+ (Windows; source-built or launcher), and for the plugin: VS 2022 with the C++ workload.

git clone <this repo>
cd UE_BPToolkit
pip install -e ".[mcp]"

Then install the plugin into your project (copies UEPlugin/BPToolkit to <project>/Plugins/ and enables it in .uproject):

bpt install-plugin --project D:/path/MyGame
# then build the editor target once, e.g.:
# "D:/Game/Epic Games/UE_5.4/Engine/Build/BatchFiles/Build.bat" MyGameEditor Win64 Development -project=D:/path/MyGame/MyGame.uproject -WaitMutex

Use as an MCP server

ZCode / Claude Code config (.mcp.json / mcp_servers):

{
  "bptoolkit": {
    "command": "bptoolkit-mcp",
    "args": ["--project", "D:/path/MyGame", "--engine", "D:/Game/Epic Games/UE_5.4"]
  }
}

Environment fallback: BPT_PROJECT, BPT_ENGINE, BPT_UEPLUGIN.

Use from the CLI

export BPT_PROJECT=D:/path/MyGame          # or pass --project each time

bpt status
bpt dump /Game/Audio/Vehicles/BP_Vehicle_AudioController_Wwise --out bp.json
bpt review /Game/Crowd/Blueprints/BP_CrowdCharacter --out review.md
bpt generate examples/specs/selftest.json   # needs a project with the Wwise integration
bpt selftest                                # generate -> dump round-trip validation

Example: generate a Wwise blueprint

{
  "asset": "/Game/Testing/BPToolkit/BPT_TestSound",
  "delete_existing": true,
  "parent": "/Script/Engine.Actor",
  "components": [
    {"class": "/Script/AkAudio.AkComponent", "name": "AkComp"}
  ],
  "variables": [
    {"name": "TestEvent", "type": "object", "sub": "/Script/AkAudio.AkAudioEvent"}
  ],
  "graphs": [{
    "name": "EventGraph",
    "nodes": [
      {"id": "bp", "kind": "event", "function": "/Script/Engine.Actor:ReceiveBeginPlay", "x": 0, "y": 0},
      {"id": "akcomp", "kind": "var_get", "variable": "AkComp", "x": 200, "y": 100},
      {"id": "evget", "kind": "var_get", "variable": "TestEvent", "x": 200, "y": 200},
      {"id": "post", "kind": "call", "function": "/Script/AkAudio.AkComponent:PostAkEvent", "x": 450, "y": 0}
    ],
    "connections": [
      {"from": ["bp", "then"], "to": ["post", "execute"]},
      {"from": ["akcomp", "AkComp"], "to": ["post", "self"]},
      {"from": ["evget", "TestEvent"], "to": ["post", "AkEvent"]}
    ]
  }],
  "compile": true, "save": true
}

Node/pin notes for spec authors: a call node's target pin is named self (the compiler error text calls it "Target"); variable-get nodes expose an output pin named after the variable; exec pins are execute/then. A "pre-compile" pass runs automatically so freshly added components/variables resolve.

Wwise review rules

Detection is structural, not name-based allow-lists: any call into /Script/Ak* / /Script/Wwise* owners (PostAkEvent, PostEvent, SetRTPCValue*, SetSwitchGroupValue, SetStateValue, ...), any Ak*/Wwise* typed variable/component/pin, any default object under /Game/WwiseAudio/. Issues checked: orphaned pins (stale signatures), compile messages, missing referenced assets, empty Event/RTPC pins, post-events reachable from Tick.

Troubleshooting

• "BPToolkit plugin is not loaded" — run bpt install-plugin, rebuild the editor target, retry.

• UBT error about rules assembly / DLSSUtility — delete Intermediate/Build/Win64/x64/<Target>/Development/Makefile.bin in the project and rebuild.

• MSVC 14.44+ compile error in ConcurrentLinearAllocator.h — UE 5.4 header needs a guard; patch is one line: #elif __has_feature(address_sanitizer) → #elif defined(__has_feature) && __has_feature(address_sanitizer). (Short-circuit && in the same #if does not work — use a nested #if defined(__has_feature) / #if __has_feature(...).)

Security & caveats

• bp_eval is arbitrary code. bp_eval runs unrestricted Python inside the headless editor (unreal module + BPL library in scope). Treat the MCP server as a local-only tool. Do not expose it on a network or to untrusted clients; do not point it at a .uproject you don't trust.

• bp_generate mutates your project. A bad spec can create/delete/save blueprint assets inside the target project. Always run against a project you own and ideally under version control.

• Editor binaries are not in this repo. You must build UEPlugin/BPToolkit inside your own UE 5.4+ project before the first session (see Install above). The prebuilt .dll/.pdb shipped here is gitignored on purpose.

• Windows-only runner. The host launches UnrealEditor-Cmd.exe. Linux/macOS support is on the roadmap.

Roadmap

• Mac/Linux editor support (runner is Windows-only today)

• Wwise bank/event cross-checks against the generated Wwise project data

• Blueprint diffing (two dumps → semantic diff)

• Macro / interface scaffolding in generate

• Remote TCP transport inside the editor (alternative to the file queue)

License

MIT — see LICENSE.