Model Context Protocol server for Unreal Editor automation

Claireon is an Unreal Engine editor plugin that runs a Model Context Protocol (MCP) server inside the editor, exposing hundreds of editor automation tools for AI-assisted development workflows behind a deliberately small MCP surface (tool_search + python_execute). It enables AI assistants like Claude Code to read, search, inspect, and edit Unreal assets directly.

• Hybrid Tool Discovery — tool_search ranks the full tool catalog with SQLite FTS5 + a vendored embedding model, so agents find the right tool without a giant tool list
• Blueprint Editing — Read and modify Blueprint graphs, properties, components, and connections
• Animation Authoring — Anim sequences, montages, notifies, blend spaces/aim offsets, and AnimBP graphs
• State Tree Editing — Inspect and edit State Tree assets, nodes, and runtime state
• Behavior Tree & EQS — Inspect and edit Behavior Trees, Blackboards, and Environment Query Systems
• Widget Blueprint Editing — Read and modify UMG widget hierarchies and animations
• Niagara & PCG — Inspect and edit Niagara particle systems and PCG graphs
• Data Tables — Full CRUD operations on Data Table assets with CSV/JSON import/export
• Audio & MetaSounds — Sound placement, attenuation, audio components, and MetaSound inspection
• Sequences, Cameras & More — Level Sequences (incl. actor rebinding), camera assets, chooser/proxy tables, gameplay tags, Enhanced Input, landscape/terrain
• Asset Management — Search, list, validate, resave, cook, and fix up redirectors
• PIE Integration — Start/stop Play-In-Editor, query actors, spawn enemies, test abilities, take screenshots
• Trace Analysis — Open and analyze Unreal Insights trace files for performance profiling
• Blueprint Diffing — Compare Blueprint and State Tree assets between revisions
• Python Execution — Run arbitrary Python scripts in the editor with audit logging
• Built-in REPL — In-editor AI chat assistant with Claude integration (optional)
• Session Management — Exclusive-per-asset locking with automatic timeout cleanup

• Unreal Engine 5.x (tested with 5.5+)
• Windows (Win64) — other platforms may work but are untested
• Python 3 plugin enabled in the editor
• Claude Code or any MCP-compatible client

1. Clone this repository directly into your project's Plugins/ folder (the plugin lives at the repository root): git clone <repo-url> Plugins/Claireon
2. Regenerate project files and build

YourProject/
  Plugins/
    Claireon/
      Claireon.uplugin
      Source/
      Content/
      ...

3. Enable the plugin in the editor under Edit > Plugins > Claireon

The MCP server can be started in two ways:

• Command line: Launch the editor with -StartMCPServer to auto-start on load
• Toolbar button: Click the Claireon button in the editor toolbar to open the Claireon panel, which also starts the server

The server binds a deterministic per-worktree port: SHA-256 of the canonicalized project root, folded into the ephemeral range 49152-65535. Every checkout gets a stable, collision-free port with no configuration, and multiple worktrees on one machine never fight over a shared default. The live port and PID are written to Saved/Claireon/MCPServer.json on startup. -MCPServerPort=<port> remains as a developer escape hatch to force a specific port.

For workflows where the editor restarts often (rebuilds, crashes, live-coding reloads), an optional always-on proxy (Content/Python/claireon_proxy.py, run with UE's vendored Python) can front the editor: Claude Code stays connected to the worktree's deterministic port while editors come and go behind it. Opt in with -EnableMCPProxy on the command line, or via Editor Preferences > Plugins > Claireon > MCP Proxy > Enable MCP Proxy (off by default). When enabled, the proxy holds the worktree port, and the editor binds an ephemeral port and registers with the proxy; editor ingress is then gated by a per-session bearer token so the proxy is the sole entry point. A single proxy instance serves all worktrees on the machine (registration port 43017). Even with the setting off, an editor that finds its port already held by a Claireon proxy auto-promotes into proxy-attached mode.

The proxy can also run without any editor: Scripts/Utilities/Start-MCPProxy.ps1 spawns (or attaches to) the singleton and binds the current worktree's port, no Unreal launch required. Editor-less, the proxy serves the proxy meta-tool and the file-backed prompts (e.g. workflow) directly from disk; tool_search and python_execute answer once an editor registers (start one from the client with proxy(command='launch_editor')).

Once the server is running, configure Claude Code to connect. Take the port from Saved/Claireon/MCPServer.json -- it is stable for a given checkout path, so the config can be committed to your project's .mcp.json once and forgotten:

{
  "mcpServers": {
    "claireon": {
      "type": "http",
      "url": "http://127.0.0.1:<port>/mcp"
    }
  }
}

The MCP surface is intentionally two tools: tool_search to discover what is available, and python_execute to run editor Python (where every catalog tool is callable as claireon.<tool_name>(...)). Discover tools with:

> tool_search blueprint
> tool_search state tree
> tool_search(tool_name="bp_apply_delta")   # full detail for one tool

Once the plugin is loaded, open the Claireon panel (toolbar button, or Window > General > Miscellaneous > Claireon); its status strip exposes a Claude Code launch button (toggleable via the Show Claude Code Button setting). Clicking it:

1. Resolves the live MCP server port (from the in-process server, falling back to Saved/Claireon/MCPServer.json).
2. Writes a per-launch MCP config to Saved/Claireon/claude-code-mcp.json so the committed .mcp.json stays untouched.
3. Spawns a PowerShell window at the project root and runs claude --mcp-config <path> against that config. On Windows 11 with Windows Terminal as the default console host, the new window automatically opens in Terminal.

Two optional settings under Editor Preferences > Plugins > Claireon > Claude Code Launch let teams customize the flow:

• Initial Prompt — string sent to Claude Code on launch (typically a slash command like /mcp-connect-claireon to auto-fire a project-specific init skill). Empty by default.
• Skip Permission Prompts on Launch — when true, passes --dangerously-skip-permissions so the initial-prompt skill can run unattended. Off by default.

Project-wide defaults can be committed via Config/DefaultEditorPerProjectUserSettings.ini:

[/Script/Claireon.ClaireonSettings]
LaunchInitialPrompt=/mcp-connect-claireon
bLaunchSkipPermissions=True

First-run requirements (per machine):

• Install Claude Code: https://docs.anthropic.com/en/docs/claude-code/quickstart
• Run claude /login once to authenticate against your Claude.ai subscription. Inference then bills against your Pro/Max/Team seat instead of the Anthropic API.

Claireon works standalone, but can integrate with these plugins when present:

<repository root>/
  Source/Claireon/
    Public/
      ClaireonModule.h          # Module entry point, server lifecycle
      ClaireonServer.h          # HTTP server, JSON-RPC dispatch
      ClaireonSessionManager.h  # Per-asset exclusive locking
      IClaireonToolProvider.h   # Modular-feature interface for external tool providers
      Tools/
        IClaireonTool.h         # Tool interface — implement this to add tools
    Private/
      Tools/                    # Tool implementations (hundreds of operations)
      Tests/                    # Unit tests (requires Untested)
  Content/
    Python/                     # Multi-worktree MCP proxy (claireon_proxy.py)
    MCP/Instructions/           # Instruction documents served as MCP resources
  Resources/
    Models/                     # Vendored bge-small-en-v1.5-int8 embedding model (MIT)

Other modules contribute tools without including server internals by implementing the modular-feature provider interface:

#include "IClaireonToolProvider.h"
#include "Tools/IClaireonTool.h"

class FMyToolProvider : public IClaireonToolProvider
{
public:
    TArray<TSharedPtr<IClaireonTool>> GetTools() const override;
    FName GetProviderName() const override { return TEXT("MyPlugin"); }
};

// In your module's StartupModule():
IModularFeatures::Get().RegisterModularFeature(IClaireonToolProvider::FeatureName, &MyProvider);

Providers are discovered at server start and dynamically as they register/unregister at runtime. A provider can also extend bare-name resolution with project-specific module names and class-prefix conventions via the optional GetKnownModules() / GetClassPrefixMap() overrides. For one-off registrations, FClaireonModule::Get().RegisterExternalTool() also works; tools registered before the server starts are queued and flushed on startup.

Claireon builds as a standard Unreal Engine editor plugin. No special build steps are required beyond the usual:

# Generate project files (if using a .uproject)
UnrealBuildTool -projectfiles -project="YourProject.uproject" -game -engine

# Build
UnrealBuildTool YourProjectEditor Win64 Development -project="YourProject.uproject"

1. Create a class implementing IClaireonTool (see Tools/IClaireonTool.h)
2. Implement GetCategory(), GetOperation(), GetDescription(), GetInputSchema(), and Execute() — the tool name is always <category>_<operation> (GetName() is sealed)
3. Register it with the built-in provider in ClaireonModule.cpp (or via your own IClaireonToolProvider if it lives in another module)

class MyTool : public IClaireonTool
{
public:
    FString GetCategory() const override { return TEXT("custom"); }
    FString GetOperation() const override { return TEXT("my_tool"); }   // name: "custom_my_tool"
    FString GetDescription() const override { return TEXT("Does something useful"); }

    TSharedPtr<FJsonObject> GetInputSchema() const override
    {
        auto Schema = MakeShared<FJsonObject>();
        Schema->SetStringField(TEXT("type"), TEXT("object"));
        // ... define properties
        return Schema;
    }

    FToolResult Execute(const TSharedPtr<FJsonObject>& Arguments) override
    {
        // Your implementation here
        auto Data = MakeShared<FJsonObject>();
        Data->SetStringField(TEXT("result"), TEXT("success"));
        return MakeSuccessResult(Data, TEXT("Tool completed successfully"));
    }
};

The Scripts/ directory contains PowerShell utilities and Claude Code instruction documents for working with Unreal Engine projects.

PowerShell scripts for common Unreal Engine development tasks. All scripts auto-detect the project and engine location — run them from anywhere inside your project directory.

The shared module ClaireonCommon.psm1 provides core functions used by all scripts: Find-UnrealProject, Find-UnrealEngine (SHA-aware custom engine detection), Get-EditorBuildTarget, Invoke-UnrealCommandlet, and more.

Markdown documents that serve as structured prompts for AI assistants (e.g., Claude Code). Each document describes a multi-step workflow that an AI agent can follow autonomously. Invoke them by asking your AI assistant to follow the instructions in a specific file.

Git Workflows:

• AutoPushChangesAsNewBranch.md — Move local changes to a new branch with standardized naming
• CleanupBranchesAfterMerge.md — Rebase all local branches onto main after merges
• ResetWorktreeToMain.md — Park current branch and reset to latest main

Unreal Engine Workflows:

• ConnectToUnrealEditorMCP.md — Connect Claude Code to the MCP server in the editor
• FixDeprecatedBlueprintAPIs.md — Parse editor logs for deprecated API warnings
• FixNaniteMaterialCompatibility.md — Identify Nanite/material incompatibility issues
• FixDuplicateGameplayCueTags.md — Find duplicate GameplayCue tag registrations
• ResaveAssetsWithLoadErrors.md — Resave assets with broken references
• UnrealPythonPatterns.md — Quick reference for correct Unreal Python API patterns
• PSD-to-UMG-Workflow.md — Convert Photoshop PSD designs into UMG widget blueprints

Development Workflows:

• BreakDownWorkProposal.md — Break a proposal into skeleton-test-implement stages
• CheckDocumentationStaleness.md — Scan HTML docs for staleness vs. source files
• VerifyTestBehavior.md — Walk through test cases and verify intended behavior

Documentation Generation:

• CreateInteractiveArchitecture.md — Generate interactive SVG architecture diagrams
• CreateInteractivePipelineDiagram.md — Generate interactive pipeline stage diagrams

Claireon runs an unauthenticated HTTP server intended for localhost-only use. This is by design for seamless local AI assistant integration, but you should be aware of the implications:

• "Localhost-only" is enforced in software, not by the socket bind. The editor's HTTP listener (Unreal's FHttpServerModule) binds all interfaces; loopback-only access is enforced by Origin/Host header validation, which is best-effort. A host firewall blocking inbound connections to the MCP ports is the real network boundary.
• Never expose the MCP port externally. Do not use port forwarding, reverse proxies, or tunnels to make the server (or the Claireon proxy, ports 43017 and 49152-65535) accessible from other machines.
• Python execution is unrestricted. The python_execute tool has full access to the filesystem, network, and editor APIs — equivalent to the editor's built-in Python console.
• Execution timeout is best-effort. A watchdog injects a TimeoutError between Python bytecodes after Python Execution Timeout (default 60 s, settable in Editor Preferences); a blocking native call is not interrupted mid-call, and the error surfaces only when it returns to Python.
• No authentication. Any process on localhost can call the MCP server. (In proxy mode the editor itself only accepts proxy traffic carrying a per-session bearer token, but the proxy's own MCP endpoint is equally unauthenticated on localhost.)

For full details, see SECURITY.md.

This project is licensed under the MIT License — see the LICENSE file for details.

Third-party dependencies retain their own licenses. The vendored embedding model ships with its license at Resources/Models/bge-small-en-v1.5-int8/LICENSE.txt.