soft-ue-cli (+mcp)

Built and maintained by a solo developer. Support this project if it saves you time.

Control Unreal Engine 5 from your AI agent or terminal. soft-ue-cli gives any LLM — via MCP server or CLI — 60+ tools to spawn actors, edit Blueprints, inspect materials, read and patch UE config files, run Play-In-Editor sessions, capture screenshots, profile performance, and more inside a running UE5 editor or packaged build.

Two connection paths. Same package. Bridge tools when Unreal is running, offline tools when it is not.

LLM client / shell / CI
    |
    v
soft-ue-cli  (CLI or MCP server)
    |
    +-- Live bridge path ----------------------------------------------+
    |      HTTP / JSON-RPC
    |      -> SoftUEBridge plugin inside UE editor / PIE / dev build
    |      -> Actor, Blueprint, material, widget, PIE, profiling tools
    |
    +-- Offline local path --------------------------------------------+
           Direct local parsing
           -> .uasset / .uexp / .ini / .uproject / BuildConfiguration.xml
           -> inspect-uasset, diff-uasset, config tree/get/diff/audit, skills

Why soft-ue-cli?

• MCP server + CLI in one package -- use as an MCP server (mcp-serve) for Claude Desktop, Cursor, Windsurf, and other MCP clients, or as a standard CLI for Claude Code, shell scripts, and CI/CD. Same 60+ tools either way.
• AI-native UE automation -- purpose-built so LLM agents can read, modify, and test Unreal Engine projects without a human touching the editor.
• 60+ tools covering actors, Blueprints, materials, StateTrees, widgets, assets, config files, PIE sessions, profiling, and more.
• Online + offline workflows -- bridge-backed UE mutation and runtime inspection when Unreal is open, plus direct local inspection, diff, and config tooling when it is not.
• Config-aware workflows — inspect hierarchy, trace overrides, diff layers, and patch .ini, BuildConfiguration.xml, and .uproject data from one config command group.
• LLM skill prompts -- ships with markdown workflows (e.g. Blueprint-to-C++ conversion) exposed as MCP prompts or CLI commands.
• Works everywhere UE runs -- editor, cooked builds, Windows, macOS, Linux.
• Single dependency -- only requires httpx. Add [mcp] extra for MCP server mode.
• Team-friendly -- conditional compilation via SOFT_UE_BRIDGE environment variable means only developers who need the bridge get it compiled in.

Quick Start

1. Install

pip install soft-ue-cli          # CLI only
pip install soft-ue-cli[mcp]     # CLI + MCP server

2. Install the plugin into your UE project

Run the setup command inside your LLM client (Claude Code, Cursor, etc.) — it outputs step-by-step instructions that the AI agent will follow to copy the plugin, edit your .uproject, and configure itself:

soft-ue-cli setup /path/to/YourProject

If you're running manually (not via an LLM), follow the printed instructions yourself: copy the plugin directory, add the "Plugins" entry to your .uproject, and create the CLAUDE.md snippet.

3. Rebuild and launch Unreal Engine

After regenerating project files and rebuilding, launch the editor. Look for this log line to confirm the bridge is running:

LogSoftUEBridge: Bridge server started on port 8080

5. Verify the connection

soft-ue-cli check-setup

You should see all checks pass:

[OK]   Plugin files found.
[OK]   SoftUEBridge enabled in YourGame.uproject.
[OK]   Bridge server reachable.

5. (Optional) Connect your MCP client

Add to your MCP client config (Claude Desktop, Cursor, Windsurf, etc.):

{
  "mcpServers": {
    "soft-ue-cli": {
      "command": "soft-ue-cli",
      "args": ["mcp-serve"]
    }
  }
}

The AI editor now has direct access to all 60+ UE tools and skill prompts — no terminal needed.

How It Works

soft-ue-cli command
    |
    +-- Bridge-backed commands ----------------------------------------+
    |      HTTP / JSON-RPC
    |      -> SoftUEBridge plugin (UGameInstanceSubsystem inside UE)
    |      -> UE APIs on the game thread
    |      -> Runtime/editor operations such as spawn-actor, PIE, query-level
    |
    +-- Offline commands ----------------------------------------------+
           Local parsers and file readers
           -> Package tables / tagged properties / config hierarchy
           -> inspect-uasset, diff-uasset, config *, skills get/list

The SoftUEBridge plugin is a lightweight C++ UGameInstanceSubsystem that starts an embedded HTTP server on port 8080 when UE launches. Bridge-backed commands send JSON-RPC requests to this server, and the plugin executes the corresponding UE operations on the game thread, returning structured JSON responses. Offline commands bypass the bridge entirely and operate directly on local files.

All commands output JSON to stdout (except get-logs --raw). Exit code 0 means success, 1 means error.

Skills Architecture

LLM client (Claude Code, Cursor, etc.)
    |
    |  soft-ue-cli skills get <name>
    v
Skill file  (markdown shipped with CLI pip package)
    |
    |  LLM reads instructions, type mappings, pre-filled commands
    v
LLM executes soft-ue-cli commands (query-blueprint, query-blueprint-graph, ...)
    |
    v
LLM generates output (e.g. .h/.cpp files) following the skill's rules

Skills are markdown files at cli/soft_ue_cli/skills/*.md, shipped as package data in the pip distribution. Each skill is self-contained: workflow instructions, reference tables, example CLI commands, and verification test cases. The CLI discovers them via skills list / skills get. When running as an MCP server, the same files are exposed via the prompts/list and prompts/get protocol.

Test Workflow

Use soft-ue-cli to explore and debug a gameplay bug quickly, then move the final regression into the project's C++ Automation Spec suite.

CLI + bridge + Python exploration
    -> find the signal
    -> validate the repro
    -> identify the exact assertion
    -> write the committed C++ Automation Spec in the project test module

The CLI is the exploration layer. The committed regression gate should live in project-native C++ tests rather than depending on the CLI, bridge, or Python runtime.

MCP Server Architecture

MCP Client (Claude Desktop, Cursor, Windsurf, etc.)
    |
    |  stdio (JSON-RPC, MCP protocol)
    v
soft-ue-cli mcp-serve  (FastMCP server)
    |
    |  Reuses call_tool() — HTTP/JSON-RPC
    v
SoftUEBridge plugin (inside UE)

Running soft-ue-cli mcp-serve starts an MCP server over stdio. It auto-generates MCP tool schemas from the CLI's argparse parser and forwards tool calls to the UE bridge. Skills are exposed as MCP prompts. Install the optional extra: pip install soft-ue-cli[mcp].

Complete Command Reference

Every command is available via soft-ue-cli <command>. Run soft-ue-cli <command> --help for detailed options.

Setup and Diagnostics

| Command | Description | |---------|-------------| | setup | Copy SoftUEBridge plugin into a UE project | | check-setup | Verify plugin files, .uproject settings, and bridge server reachability | | status | Health check -- returns server status | | wait-for-ready | Poll the same bridge health probe as status until it is ready (await-bridge alias) | | project-info | Get project name, engine version, target platforms, and module info |

Actor and Level Operations

| Command | Description | |---------|-------------| | spawn-actor | Spawn an actor by class at a given location and rotation | | query-level | List actors in the current level with transforms, filtering by class or name | | call-function | Call any BlueprintCallable UFUNCTION on an actor, class default object, or transient instance | | batch-call | Dispatch multiple bridge tool calls in-process with one HTTP roundtrip | | set-property | Set a UPROPERTY value on an actor by name | | get-property | Read a UPROPERTY value from an actor or component using reflection | | add-component | Add a component to an existing actor |

Blueprint Inspection and Editing

| Command | Description | |---------|-------------| | query-blueprint | Inspect a Blueprint asset -- components, variables, functions, interfaces, event dispatchers | | query-blueprint-graph | Inspect event graphs, function graphs, and node connections | | inspect-uasset | Inspect a local .uasset file offline by parsed metadata, with best support for Blueprint and External Actor assets | | diff-uasset | Diff two local .uasset files offline by parsed metadata, with best support for Blueprint and External Actor assets | | add-graph-node | Add a node to a Blueprint or Material graph (supports `AnimLay