Grimoire — UE5 Context Bridge

Read-only MCP server that gives Claude (or any MCP client) live access to your UE5 project — Blueprints, interfaces, variables, functions, event graphs, materials, structs, and Data Assets.

Claude → MCP Server (stdio) → IPC Bridge (TCP) → Unreal Host (in editor)

• MCP Server: Exposes tools to the client, routes requests over TCP

• Unreal Host: Runs inside the UE5 editor, executes queries via Unreal Python API

Status: Actively evolving. Inventory tools are solid; bounded live flow / symbol / references query is promoted and sealed on real project assets, but fidelity is still incomplete in places (see Known Limitations and CHANGELOG.md). Prefer bounded tools over dumping whole graphs.

How It Works

See METHODOLOGY.md for how the UE5 Python API surface was mapped — including the dead ends.

At a high level Grimoire combines:

1. SubobjectDataSubsystem — component hierarchy

2. JsonObjectGraphFunctionLibrary.stringify() — variables, types, Data Asset values, live graph capture

3. AssetExportTask T3D export — function signatures, thin exec summaries, bindings

4. Live pin decode + canonical index — exact pin identity, links, and bounded flow walks

Requires the Json Blueprint Utilities plugin (built-in, free).

Related MCP server: unreal-engine-mcp

What This Unlocks

Grimoire gives Claude live read access to your UE5 project. Combined with other MCP servers:

• Grimoire + Notion — architecture notes grounded in live Blueprints

• Grimoire + GitHub — issues / PR descriptions from actual graph state

• Grimoire + Slack — technical summaries without hand-describing systems

• Grimoire alone — in-editor reasoning, bug hunting, refactors

The pattern: Grimoire provides UE5 context; other MCP servers act on it.

Prerequisites

• Python 3.10+

• UE5 project with Python Script Plugin enabled

• Json Blueprint Utilities plugin enabled (built-in, free, Epic Games)

• Claude Desktop or another MCP client

Installation

1. Install Python dependencies

pip install -r requirements.txt

2. Configure the project

Copy the example config and set your UE5 project path (the folder containing your .uproject file):

cp config.toml.example config.toml

On Windows (PowerShell): Copy-Item config.toml.example config.toml

Edit config.toml and set root under [project]. config.toml is gitignored — keep your real paths local only. See config.toml.example for all available keys.

3. Install the Unreal Host

The editor must be able to import ue5_host on its Python path. Two common approaches:

• Copy — Copy the entire ue5_host folder into your project (e.g. paste it at YourProject/Content/Python/ue5_host/). No symlink required; this is the simplest option on Windows.

• Symlink — Point Content/Python/ue5_host at a single checkout elsewhere if you prefer not to duplicate files.

Target layout inside your UE5 project:

YourProject/
└── Content/
    └── Python/
        └── ue5_host/
            ├── ue5_host.py
            ├── handlers.py
            └── __init__.py

You can also skip copy/symlink and pass a full absolute path to the startup script instead (see step 4).

4. Enable the Host in UE5

• Open your UE5 project

• Edit → Project Settings → Plugins → Python

• Under Startup Scripts, add: ue5_host.ue5_host

  • Or the full path, e.g. C:/path/to/grimoire-ue5/ue5_host/ue5_host

• Restart the editor (or run the script manually once)

5. Register the MCP Server with Claude Desktop

Edit your Claude Desktop config (%APPDATA%\Claude\claude_desktop_config.json on Windows):

{
  "mcpServers": {
    "ue5-context": {
      "command": "python",
      "args": ["-m", "ue5_mcp.mcp_server"],
      "cwd": "C:/path/to/grimoire-ue5",
      "env": {
        "UE5_MCP_CONFIG": "C:/path/to/grimoire-ue5/config.toml"
      }
    }
  }
}

Replace cwd and UE5_MCP_CONFIG with your actual paths. Add other MCP servers (Notion, GitHub, Slack etc) to the same config to enable multi-server workflows.

After pulling host changes, call reload_host(confirm=True) (or restart the editor). New MCP tool schemas (for example Rank 4 query tools) require restarting the MCP server process, not only reload_host.

Tools

Inventory (thin by default)

Opt-in depth on get_blueprint

Rank 4 — bounded query (preferred for graphs)

Retrieval rule: never ask for an entire EventGraph or raw serial dump as the answer format. Expand with include_flow / Rank 4 tools and raise max_depth / max_records intentionally when a walk comes back FRONTIER_TRUNCATED or record/byte-capped.

LLM-oriented QA expectations and reason codes: qa/QA_BRIEF.md.

What Grimoire Can Read

Blueprints

• Parent class, components, variables (with additive type_normalized / container)

• Function / event signatures; implemented interfaces when gen_class or ImplementedInterfaces JSON yields them

• Additive BPI contracts on implementors — functions[].interface_contract (native inputs/outputs are never overwritten)

• Opt-in T3D body summaries (flat opcodes — not branch-attributed truth)

• Bounded live flow — nodes, hops, unwired pin defaults / inbound data provenance on visited nodes

• Reason-coded warnings when data is omitted, partial, or budget-limited

Data Assets

• Configured instance properties (not Blueprint class definitions)

• Wrong-kind matches fail fast with DATA_ASSET_WRONG_KIND

Structs & materials

• UserDefinedStruct fields; material parameters, outputs, and function calls

Cache

• SQLite persistence across sessions; dirty-flag invalidation after asset saves

Thin body format (include_body)

When body is present, it is a flat T3D exec summary, not a full attributed CFG:

call SubscribeToStats_Player
set CachedInvComp
bind_delegate(OnInventorySheetUpdate)
branch
macro:IsValid

For branch conditions, wired producers, and pin literals, use include_flow / query_blueprint_flow.

Known Limitations

Honest gaps — not silent failures:

• Attributed control/data flow — use Rank 4 / include_flow. Multi-event include_body is hard-omitted (EVENTGRAPH_BODY_UNATTRIBUTED) so LLMs do not treat mixed T3D chunks as per-event truth.

• T3D LinkedTo gaps — some macro / custom-event chains still yield EVENTGRAPH_PARTIAL when a body remains.

• Flat body summaries — include_body does not nest true/false branches.

• Interface list still incomplete on some assets — many Blueprints populate interfaces[]; some (e.g. certain components) still return empty with INTERFACE_DATA_UNAVAILABLE. find_event_bindings / Rank 4 references remain the fallback.

• Collapsed graphs — many recover to COMPLETE via JSON stringify fill; large merges may stay PARTIAL.

• Ubergraph / tick-continuation — unsupported / deferred; prefer scoped path_prefix / blueprint_name / max_assets.

• Thin variables vs pin containers — Map/Set fidelity lives on decoded pins / flow; thin lists expose additive container but still lean on element/key category in type.

• Materials / levels / writes / cross-project — not the current milestone (parked).

Some of these track UE5 Python / T3D export limits. Others are Grimoire scope choices (bounded retrieval over full-graph dumps).

Switching Projects

• Update config.toml: change [project].root and optionally [ipc].port

• For multiple editors: set UE5_MCP_PORT per project (e.g. 65432, 65433)

• Restart Claude Desktop after config changes

Troubleshooting

Editor offline / Connection refused

• Ensure the UE5 editor is open with your project loaded

• Confirm the host started (check Output Log for UE5 Context Bridge: listening on...)

• Verify config.toml port matches the host (default 65432)

Port conflict

• Use a different port in config.toml and set UE5_MCP_PORT in environment

• Or run only one UE5 editor at a time

Timeout

• Increase timeout_sec in config.toml for large scans

• First call after MCP restart / reload_host can hit a short cold-start timeout — retry once

• Do not raise timeouts to “fix” wrong get_data_asset args; wrong-kind should fail fast

Python startup script not running

• Check that the Python Script Plugin is enabled

• Use the full absolute path to ue5_host in Startup Scripts if a relative path fails

New tools missing from the client

• Restart the MCP server process after pulling (schema is process-lifetime). reload_host alone is not enough for new tool definitions

Cache stale after host code changes

• Prefer reload_host(confirm=True)

• Cache DB: YourProject/Saved/Grimoire/cache.db (watchdog invalidates on asset save)

Direction / Roadmap

Done / in tree (see CHANGELOG.md): thin default Blueprint inspection, opt-in body/flow, Rank 4 bounded query, LLM UX honesty (body omit, inbound provenance, additive BPI contracts, budget reason codes), COLLAPSED promote path, Map/Set pin corpus, FPC delegate handler harden.

Next (not claimed done): broader interface-list coverage, deeper pure-chain provenance, anim graphs, write ops, levels, cross-project diff, setup automation.

License & contributing

Grimoire is dual-licensed. AGPL-3.0 applies by default; see LICENSE for the full text and DUAL_LICENSE.md for commercial licensing.

Contributions, issues, and PR expectations: CONTRIBUTING.md.