Unreal Niagara Mcp

Unreal Niagara MCP

Experimental Unreal Engine 5.8 tooling for turning human-readable VFX intent into deterministic, reviewable Niagara authoring operations.

This repository is not a wrapper around arbitrary Unreal Python. It uses Epic's UE 5.8 ModelContextProtocol, ToolsetRegistry, NiagaraToolsets, and FileSandbox plugins, then adds a narrow NiagaraAuthoring toolset with typed contracts, deterministic plans, and explicit stage/persist/rollback boundaries.

> Alpha warning: the safety foundation is implemented and tested, but end-to-end Niagara structural creation/editing is not complete. Do not use this branch as an unattended production asset writer.

[한국어 연구 보고서](docs/UE5.8NiagaraMCPResearchReportko.md) · [Architecture](docs/ARCHITECTURE.md) · [Claude MCP guide](docs/CLAUDEMCPGUIDE.md) · [Roadmap](docs/ROADMAP.md) · [Tool contracts](docs/TOOLCONTRACTS.md)

Why this design

The original idea—give an AI a Niagara “feel,” let it write YAML values, and generate an effect—is useful at the intent layer but unsafe as the engine contract. YAML is deliberately kept human-facing. Execution uses a strict pipeline:

text / image / video references
        ↓
semantic Intent YAML (human review)
        ↓
recipe resolution + lockfile
        ↓
typed canonical JSON IR
        ↓
observe → deterministic diff plan
        ↓
File Sandbox + editor transaction
        ↓
compile / topology / budget / preview evidence
        ↓
explicit approval → selected-file persist

This separates three kinds of truth: creative intent, actual engine topology, and deterministic validation evidence. A vision model may suggest changes; it cannot declare a build valid or persist files by itself.

Current implementation status

Verified on Windows with Unreal Engine 5.8.0, changelist 55116800.

| Area | Status | Evidence | |---|---|---| | UE 5.8 toolchain and plugin packaging | Implemented | verify-toolchain.ps1, BuildPlugin | | File Sandbox create/revert/selective persist/recovery detection | Implemented | Unreal Automation tests | | Intent YAML → typed IR + lockfile | Implemented | Python contract tests | | Canonical JSON and cross-language SHA-256 vectors | Implemented | Python and UE tests | | Niagara observe/export with bounded pagination | Implemented | UE tests against real Niagara fixtures | | Deterministic stable-ID planner | Implemented | minimal diff, dependency order, ambiguity and deletion-risk tests | | Atomic apply safety core | Limited alpha | existing-system SetSystemProperty; forced operation-7 failure, stale-plan, retry, staged persist, rollback tests | | Structural emitter/module/renderer create/update/delete | Not implemented | planned Gates 8–10 | | Compile gate, deterministic preview, image metrics | Not implemented | planned Gate 7 | | Claude end-to-end acceptance workflow | Not implemented | planned Gate 11 |

niagara_capabilities reports only the operations whose current runtime paths have passed automation. niagara_validate and niagara_preview remain registered to keep the public seven-tool surface stable, but return gate_not_verified today.

Requirements

• Windows 10/11
• Unreal Engine 5.8 installed at C:\Program Files\Epic Games\UE_5.8 (override script parameters if different)
• Visual Studio 2022 with the UE C++ toolchain and Windows 10 SDK
• Python 3.12 for the intent compiler and contract tests
• A local MCP client such as Claude Code or Claude Desktop for later interactive use

The required Epic plugins ship with UE 5.8 and are marked Experimental or Developer tooling. Minor engine updates can change their APIs; rerun the complete verification suite after every engine update.

Quick start for developers

git clone https://github.com/Chang-Jin-Lee/unreal-niagara-mcp.git
Set-Location unreal-niagara-mcp

# Detect UE 5.8, Python, Visual Studio, and required Epic plugins.
.\scripts\verify-toolchain.ps1

# Create the Python venv automatically and run schema/compiler tests.
.\scripts\test-contracts.ps1

# Build the test editor and run every NiagaraMCP Automation test.
.\scripts\test-unreal.ps1

# Package the editor plugin under artifacts/NiagaraMCP.
.\scripts\build-plugin.ps1

Run everything with:

.\scripts\verify.ps1

Generated binaries, test logs, sandboxes, local virtual environments, and the 51 research clones are intentionally excluded from Git.

Install the plugin in a UE 5.8 project

Copy plugin/NiagaraMCP to /Plugins/NiagaraMCP, regenerate project files, build the Editor target, and enable Niagara MCP Authoring. Its descriptor enables the required Niagara, MCP, Toolset Registry, Niagara Toolsets, and File Sandbox dependencies.

The repository's test-project/NiagaraMCPTest.uproject is a source-only unattended acceptance harness. It references the plugin through AdditionalPluginDirectories and is the best starting point for confirming a local engine update.

Compile an intent document

Set-Location tools\niagara-intent
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e ".[test]"
.\.venv\Scripts\niagara-intent.exe compile `
  ..\..\contracts\examples\arcane-burst.intent.yml `
  --ir-output ..\..\contracts\examples\arcane-burst.ir.json `
  --lock-output ..\..\contracts\examples\arcane-burst.lock.json

The compiler does not contact Unreal. It rejects untyped values, invalid paths, duplicate IDs, particle-budget violations, and policy-disallowed Custom HLSL before an editor write is possible.

Public MCP surface

Exactly seven AICallable functions are registered:

• niagara_capabilities
• niagara_observe
• niagara_plan
• niagara_apply
• niagara_validate
• niagara_preview
• niagara_rollback

See [docs/TOOLCONTRACTS.md](docs/TOOLCONTRACTS.md) before calling them. In particular, the current alpha planner can describe structural Niagara operations that the limited apply executor intentionally refuses. Treat that refusal as a safety boundary, not a bug to bypass.

Safety model

• /Game allowlisted package paths only; traversal and /Engine writes are denied.
• Planning is read-only and asserts that package dirty flags do not change.
• Stable engine GUIDs or locked stable ID + source signature are required; display-name-only matching is rejected.
• One mutation writer at a time on the game thread.
• A stale baseSnapshotHash is rejected before opening a sandbox.
• Stage recomputes planHash from the complete canonical plan (excluding only the planHash field) and binds request ID, target package, and base snapshot before mutation.
• Writes first land in a NiagaraMCP-owned File Sandbox.
• Persist requires a token bound to request, plan, and base snapshot hashes.
• Only manifest-selected /Game files can be persisted.
• Arbitrary Python, shell, console, C++, and Custom HLSL execution are not exposed by this toolset.

The current approvalToken is a plan-correlation/two-step protocol token returned with the staged result. It is not proof that a human clicked an editor-owned approval UI; Claude/client instructions must withhold the persist call until the user explicitly approves. A trusted editor approval surface remains Gate 10 work.

Read [SECURITY.md](SECURITY.md) before connecting an MCP client.

Repository layout

contracts/                 Versioned intent, IR, plan schemas and vectors
plugin/NiagaraMCP/         UE 5.8 editor-only Toolset Registry plugin
tools/niagara-intent/      Python 3.12 intent compiler and contract models
test-project/              Source-only UE 5.8 Automation harness
scripts/                   Toolchain, test, and packaging entry points
docs/                      Architecture, research, roadmap, and operating docs
research/                  Dated inventory only; cloned repositories are ignored

Research basis

The design was derived from a dated comparison of 51 repositories: 31 Unreal/MCP automation candidates, 9 Niagara compatibility fixtures, and 11 cross-DCC MCP references. Star counts were used only as a discovery signal. Local UE 5.8 builds, source inspection, transaction behavior, licensing, and test evidence determined the recommendation.

The clone inventory is in [research/REPOSITORYINVENTORY.md](research/REPOSITORYINVENTORY.md), and the documentation-policy comparison is in [docs/REPOSITORYDOCUMENTATIONCOMPARISONko.md](docs/REPOSITORYDOCUMENTATIONCOMPARISONko.md). No third-party clone or copied source is distributed in this repository.

Contributing and support

See [CONTRIBUTING.md](CONTRIBUTING.md), [SUPPORT.md](SUPPORT.md), and [CODEOFCONDUCT.md](CODEOFCONDUCT.md). Security issues must follow [SECURITY.md](SECURITY.md), not the public issue tracker.

License and trademarks

Project-authored source and documentation are licensed under the [MIT License](LICENSE). Unreal Engine and the required Epic plugins are not included and remain subject to Epic's terms. Unreal Engine and Niagara are trademarks or registered trademarks of Epic Games, Inc. This independent project is not endorsed by Epic Games.

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Chang-Jin-Lee
• Source: Chang-Jin-Lee/unreal-niagara-mcp
• License: MIT

Install and usage instructions live in the source repository linked above.