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 -- 120+ commands and tools to spawn actors, edit Blueprints, inspect materials and MetaSounds, build UMG screens, read and patch UE config files, run Play-In-Editor sessions, capture token-efficient screenshots, profile performance, and inspect local Unreal assets.

Two connection paths. One package. Bridge tools when Unreal is running, offline tools when it is not, and a command catalog that tells agents which command families are supported, which runtime/editor requirements apply, and which optional Unreal plugins are required.

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
           -> asset inspect-file, asset diff-file, 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 120+ tool surface 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.
• Agents that can see each other -- when several sessions drive one editor, the session family gives them a shared roster derived from bridge traffic, so one agent stops rebuilding the editor out from under another's PIE test. Advisory only: it informs, it never blocks.
• 120+ commands and tools covering actors, Blueprints, materials, MetaSounds, StateTrees, Mutable/CustomizableObject, widgets, assets, config files, PIE sessions, profiling, screenshots, and local Unreal file analysis.
• Command families, not one-off names -- UMG, capture, Mutable, StateTree, MetaSound, animation, asset, and Blueprint workflows are grouped under umg, capture, mutable, statetree, metasound, anim, asset, and blueprint.
• Plugin-aware metadata -- soft-ue-cli commands --json reports bridge/editor/PIE requirements plus optional Unreal plugin dependencies, and bridge tools return structured plugin_unavailable errors when a plugin is missing.
• Token-aware visual feedback -- viewport and screenshot capture can resize output by scale, width, or height and can emit color, grayscale, or monochrome images for lower LLM token cost.
• 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.
• UMG authoring loop -- draft editable Widget Blueprint trees, wire navigation contracts, run PIE interaction checks, and compare designer/runtime layout artifacts.
• 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.
• Small dependency footprint -- only requires httpx and Pillow. 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.

Current Direction

Recent releases moved soft-ue-cli from a flat list of one-off bridge calls toward a discoverable automation surface for agents:

• commands is the source of truth for command status, replacement names, runtime requirements, optional plugin requirements, and examples.
• Canonical families (umg, capture, mutable, statetree, metasound, anim, asset, blueprint) are the supported public command surface.
• UMG and screenshot workflows now support the full agent loop: author, inspect, run PIE, capture visual evidence, compare layout, and keep image payloads small.
• Optional plugin workflows are expected to compile cleanly without those plugins installed, then fail at runtime with actionable plugin_unavailable diagnostics.
• CLI/Python/bridge probing is treated as the exploration layer; durable gameplay regressions should move into project-native C++ Automation Specs.

Release highlights: 1.45.0

• Legacy cloth apply-weightmap accepts every weight-map target exposed by the active Chaos clothing runtime, including tether, drag/lift, stiffness, pressure, and flatness targets. For a merged cloth asset, repeat --section-index or pass comma-separated indices to update only those source sections; weights outside the selection are preserved.

  soft-ue-cli cloth apply-weightmap /Game/Characters/SK_Cape --asset-name CapeCloth \
    --target edge-stiffness --rule constant --value 0.75 \
    --section-index 1,3 --section-index 5 --save
  

• AnimGraph property-path failures from blueprint node property and blueprint node add now identify the node class, searched inner struct, unresolved field, available fields, and settable pins. Invalid array indices are rejected with a focused error.

• cloth query keeps its existing response fields and adds binding_warnings plus binding_warning_count when imported section clothing metadata is malformed or unsupported.

• find-references node rejects results that may be incomplete while Find in Blueprints is still indexing or has failed cache entries and no complete fallback traversal is possible. Intentional --limit truncation remains valid.

• Multi-client PIE state is discoverable through pie-session get-state, which adds worlds and world_count while keeping the first world's legacy top-level fields. Target one PIE client and one of its local players explicitly when executing a console command:

  soft-ue-cli pie-session get-state
  soft-ue-cli exec-console-command --pie-instance 1 --player-index 0 stat net
  

UE 5.8 MCP Positioning

UE 5.8 official MCP is preferred when it covers native execution for the workflow you need.

UE 5.8 is adding first-party Unreal MCP support. Use it when you want an Epic-managed, UE 5.8-native MCP endpoint and it already covers the workflow you need.

soft-ue-cli's main development target is now Unreal Engine 5.8. UE 5.7 compatibility remains maintained, so fixes and bridge code should continue to compile and run on UE 5.7 unless a release note explicitly says otherwise.

soft-ue-cli is intentionally a different layer rather than a replacement for first-party MCP:

• It works as both a normal terminal CLI and an MCP server, so the same automation can run from Claude Code, shell scripts, CI, or any MCP client.
• It includes offline commands for .uasset, .uexp, .ini, .uproject, .uplugin, and BuildConfiguration.xml files, even when the editor is closed.
• It ships curated LLM skill prompts and a test-tools smoke workflow for repeatable agent execution, not just raw editor operations.
• It supports UE 5.7 today and also runs in Development/DebugGame cooked builds, while still exposing a normal terminal CLI and an MCP server from the same package.
• Runtime bridge support and future binary install/update workflows are treated as primary post-UE-5.8-MCP differentiators, especially for packaged Development/DebugGame builds and CI automation.
• It reports command requirements and optional plugin dependencies in structured metadata so agents can choose the right workflow without guessing.
• It reports optional plugin requirements and missing-plugin failures in structured JSON so agents can recover instead of guessing.

The two can coexist: use UE's first-party MCP for native UE 5.8 editor coverage when it fits, and use soft-ue-cli for UE 5.7 projects, cooked Development/DebugGame builds, CLI/CI automation, offline inspection, curated workflows, visual capture transforms, optional plugin diagnostics, and bridge tools that move independently of engine releases.

Run soft-ue-cli mcp-surface-status inside a project workspace to probe the local UE 5.8 official MCP endpoint and SoftUEBridge health endpoint. It reports official-only, bridge-only, both, or neither, plus a recommendation without executing editor mutations.

Private soft-ue-expert Pro distribution is separate from this public package. Expert Packs provide skills, cases, rules, agents, and verification through local owner operation; hosted Pro is deferred.

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

4. 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 120+ 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
           -> asset inspect-file, asset diff-file, 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.

Automation commands return structured JSON to stdout (except get-logs --raw). Discovery and support commands use human-readable output by default where that is more useful, and expose --json where applicable. 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 (blueprint inspect, blueprint graph inspect, ...)
    |
    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].

Command Discovery And Taxonomy

Use soft-ue-cli commands to inspect the public command surface without connecting to Unreal:

soft-ue-cli commands
soft-ue-cli commands --json
soft-ue-cli commands --category umg
soft-ue-cli commands --category mutable
soft-ue-cli commands --category statetree
soft-ue-cli commands --plugin Mutable --json

The README uses a conservative 120+ count. For exact numbers in the installed version, use soft-ue-cli commands --json for the full catalog and soft-ue-cli mcp-serve for the MCP-exposed leaf tools.

The JSON output marks each command's status and includes whether it needs the bridge, editor, PIE, or optional Unreal plugins. Plugin-dependent bridge tools use a structured unavailable response when a plugin is missing:

{
  "success": false,
  "error_code": "plugin_unavailable",
  "plugin": "StateTree",
  "command": "statetree inspect",
  "recovery": "Enable the StateTree plugin, rebuild if prompted, and restart the editor."
}

The public command system is organized by domain:

Use soft-ue-cli <family> --help to see the family, then drill down with subcommands such as soft-ue-cli blueprint graph inspect --help, soft-ue-cli mutable graph add-node --help, or soft-ue-cli anim pose-search inspect --help.

Complete Command Reference

Canonical commands are grouped under command families such as blueprint, asset, mutable, metasound, anim, cloth, capture, umg, and statetree. Run soft-ue-cli <family> --help or soft-ue-cli <family> <subcommand> --help for detailed options.

Setup and Diagnostics

Actor and Level Operations

Blueprint Inspection and Editing

Asset Management

Material Inspection

Chaos Cloth Automation

Class and Type Inspection

Play-In-Editor (PIE) Control

Screenshot and Visual Capture

Logging and Console Variables

Gameplay Tags

Python Scripting in UE

StateTree Editing

Widget Blueprint Inspection

DataTable Editing

Performance Profiling (UE Insights)

Rewind Debugger (Animation Debugging)

Requires the Animation Insights (GameplayInsights) plugin enabled in Edit > Plugins.

Build and Live Coding

Cross-Session Coordination

Several LLM coding sessions can drive the same Unreal Editor at once -- one mid-PIE-test while another runs build-and-relaunch and takes the editor down under it. The session family gives them a shared roster derived from bridge traffic: a session appears the moment it makes its first bridge call, under a machine-derived name, before it ever announces anything. session announce is for giving that entry a readable name and stating intent the bridge cannot observe on its own -- not for becoming visible in the first place. PIE state is derived the same way: pie-session start/stop claims the pie resource automatically, so filter the roster with --resource pie to find who would lose a running test, not --intent pie (that only matches sessions that declared it by hand). The family also lets a session ask before disruptive work such as rebuilding, restarting the editor, or stopping a running PIE session.

Pick one short readable name and pass it as an environment prefix on every command, session or not. That is what keeps your PIE claim and your name on the same roster row:

export SOFT_UE_SESSION=cape-cloth   # or prefix each command, see the note below

SOFT_UE_SESSION=cape-cloth soft-ue-cli session announce --status "Converting SK_Cape to Chaos cloth" --intent write --resources /Game/Characters/SK_Cape
SOFT_UE_SESSION=cape-cloth soft-ue-cli pie-session start
SOFT_UE_SESSION=cape-cloth soft-ue-cli session list
SOFT_UE_SESSION=cape-cloth soft-ue-cli session broadcast --message "Saving all assets in 30s" --tag warning
SOFT_UE_SESSION=builder    soft-ue-cli session ask --to cape-cloth --question "Can I rebuild and relaunch?" --timeout 120
SOFT_UE_SESSION=cape-cloth soft-ue-cli session answer --id a-77 --decision wait --answer "3 more minutes, mid-PIE"
SOFT_UE_SESSION=cape-cloth soft-ue-cli session inbox --unread-only
SOFT_UE_SESSION=cape-cloth soft-ue-cli session leave --reason "cloth conversion done"

The --as <name> flag does the same thing but exists only on session leaves -- pie-session start --as cape-cloth is an argparse error. Mixing the two forms splits one agent across two roster rows: the pie claim lands on a nameless unknown:<origin> entry while your name sits on another, so session list --resource pie reports a session nobody can address. Some agent harnesses give each shell invocation a fresh environment, in which case export will not survive between calls -- use the per-command prefix shown above. MCP clients have no shell at all: there, pass session_as to session announce once and every later call from that server inherits it.

It is advisory only. Nothing in this family blocks any command, vetoes another session, or acquires a lock -- it tells a session who else is here and what they are doing, and the calling LLM always decides what to do with that information. Run soft-ue-cli skills get session-protocol for the full protocol: identity, liveness grading, how to treat silence, and the post-mortem shown when the editor disappears mid-call.

Skills (LLM Workflow Prompts)

Skills are markdown prompts that teach an LLM client how to perform complex multi-step workflows using soft-ue-cli commands. They include step-by-step instructions, type mapping tables, and pre-filled CLI commands.

Available skills:

MCP Server Mode

Exposes 120+ commands as MCP tools and skills as MCP prompts. Compatible with Claude Desktop, Claude Code, Cursor, Windsurf, and other MCP clients. Requires the optional mcp extra:

pip install soft-ue-cli[mcp]

Usage Examples

Spawn an actor at a specific location

soft-ue-cli spawn-actor BP_Enemy --location 100,200,50 --rotation 0,90,0

Query all actors of a specific class

soft-ue-cli query-level --class-filter StaticMeshActor --limit 50
soft-ue-cli query-level --world pie --search "BP_Player*"
soft-ue-cli get-property BP_Player_C_0 Health --world pie

Call a BlueprintCallable function

soft-ue-cli call-function BP_GameMode SetDifficulty --args '{"Level": 3}'

Compose deterministic runtime steps with one batch

soft-ue-cli batch-call --calls '[
  {"tool":"pie-tick","args":{"frames":1}},
  {"tool":"query-level","args":{"limit":5}},
  {"tool":"get-logs","args":{"lines":5}}
]'

Sweep a pure callable on a transient instance

soft-ue-cli call-function --class-path /Script/Engine.Actor --function-name K2_GetActorLocation --spawn-transient

Validate a class path before spawning

soft-ue-cli validate-class-path /Game/Characters/BP_Hero.BP_Hero_C

Tick PIE and inspect animation state

soft-ue-cli pie-tick --frames 30
soft-ue-cli anim instance inspect --actor-tag TestCharacter --include state_machines,montages

Execute a console command directly in PIE

soft-ue-cli exec-console-command stat fps
soft-ue-cli exec-console-command --pie-instance 1 --player-index 0 MyGame.MyCommand arg1 arg2

Inspect possession state during PIE

soft-ue-cli inspect-pawn-possession
soft-ue-cli inspect-pawn-possession --class-filter Character

Inspect a Blueprint's components and variables

soft-ue-cli blueprint inspect /Game/Blueprints/BP_Player --include components,variables

Build an editable UMG Designer tree

soft-ue-cli umg designer apply /Game/UI/WBP_MainMenu --spec-file menu_tree.json --compile --save
soft-ue-cli umg navigation wire /Game/UI/WBP_MainMenu --bindings-file navigation.json --compile --save
soft-ue-cli umg workflow run --plan umg_workflow_plan.json
soft-ue-cli umg layout extract --source concept-image --input concept.png --output concept_layout.json
soft-ue-cli umg layout extract --source designer --asset-path /Game/UI/WBP_MainMenu --output umg_expected_layout.json
soft-ue-cli umg layout extract --source runtime --root-widget WBP_MainMenu_C_0 --full-geometry --output umg_runtime_layout.json
soft-ue-cli umg layout compare --mode geometry --subset concept_layout.json umg_runtime_layout.json --output umg_layout_report.json
soft-ue-cli umg layout fit --concept concept_layout.json --actual umg_runtime_layout.json --spec menu_tree.json --output corrected_menu_tree.json
soft-ue-cli umg designer inspect /Game/UI/WBP_MainMenu --include-defaults --depth-limit 8
soft-ue-cli skills get author-umg

umg navigation wire fails fast while PIE is active or the editor is saving/garbage collecting because it mutates WidgetBlueprint assets. Stop PIE first, wait until the editor is idle, or pass --allow-pie / --allow-busy when you intentionally accept that risk.

Inspect and diff local .uasset files offline

soft-ue-cli asset inspect-file D:/Project/Content/Blueprints/BP_Player.uasset --sections all
soft-ue-cli asset inspect-file D:/Project/Content/Characters/SK_Mannequin_Skeleton.uasset --sections properties
soft-ue-cli asset inspect-file D:/Project/Content/__ExternalActors__/Maps/OpenWorld/5/TQ/ABC123.uasset --sections summary,properties
soft-ue-cli asset diff-file D:/snapshots/BP_Player_before.uasset D:/Project/Content/Blueprints/BP_Player.uasset --sections variables,functions
soft-ue-cli asset diff-file D:/snapshots/SK_before.uasset D:/Project/Content/Characters/SK_Mannequin_Skeleton.uasset --sections properties
soft-ue-cli asset diff-file D:/snapshots/Actor_before.uasset D:/Project/Content/__ExternalActors__/Maps/OpenWorld/5/TQ/ABC123.uasset --sections summary,properties

Inspect UserDefinedEnum and UserDefinedStruct assets

soft-ue-cli query-enum /Game/Data/E_TraversalActionType
soft-ue-cli query-struct /Game/Data/S_TraversalCheckResult

Inspect Mutable / CustomizableObject assets safely

soft-ue-cli mutable inspect graph /Game/Characters/CO_Hero.CO_Hero
soft-ue-cli mutable inspect parameters /Game/Characters/CO_Hero.CO_Hero
soft-ue-cli mutable inspect diagnostics /Game/Characters/CO_Hero.CO_Hero

Edit Mutable / CustomizableObject assets

soft-ue-cli mutable graph add-parameter /Game/Characters/CO_Hero.CO_Hero BodyHeight --parameter-type float
soft-ue-cli mutable graph add-mesh-option /Game/Characters/CO_Hero.CO_Hero /Game/Meshes/SKM_Boots.SKM_Boots
soft-ue-cli mutable graph add-group-child /Game/Characters/CO_Hero.CO_Hero <group-node-guid> <child-node-guid>
soft-ue-cli mutable graph set-layout-blocks /Game/Characters/CO_Hero.CO_Hero <remove-blocks-node-guid> --grid-size 4,4 --blocks '[{"min":[0,0],"size":[1,1]}]' --parent-layout-index 0 --parent-material-node <base-material-node-guid>
soft-ue-cli mutable graph set-layout-blocks /Game/Characters/CO_Hero.CO_Hero <skeletal-mesh-node-guid> --grid-size 4,4 --blocks '[{"min":[0,0],"size":[1,1]}]' --lod-index 0 --section-index 0 --uv-channel 0
soft-ue-cli mutable graph regenerate-node-pins /Game/Characters/CO_Hero.CO_Hero <node-guid>
soft-ue-cli mutable graph connect-pins /Game/Characters/CO_Hero.CO_Hero <source-node-guid> Value <target-node-guid> Input
soft-ue-cli mutable compile /Game/Characters/CO_Hero.CO_Hero
soft-ue-cli mutable graph remove-node /Game/Characters/CO_Hero.CO_Hero <node-guid>

Generate investigation diagnostics

soft-ue-cli diagnose asset /Game/Blueprints/BP_Hero --kind blueprint --include-graph
soft-ue-cli diagnose character /Game/Characters/BP_MetaHuman --anim-blueprint /Game/Anim/ABP_MetaHuman --target-mesh /Game/Characters/SKM_Target
soft-ue-cli diagnose build-log Saved/Logs/Build.log
soft-ue-cli diagnose p4 --opened-file opened.txt
soft-ue-cli diagnose issue --source jira --input-file ticket.json
soft-ue-cli diagnose probe --map /Game/Maps/Test --script "print('probe')" --frames 30 --capture --stop
soft-ue-cli diagnose data Content/Data/DT_Items.csv Config/DefaultGame.ini
soft-ue-cli diagnose handoff --title "Retargeting crash" --summary "Crash after retargeting" --next-step "Run anim montage inspect"

Start a PIE session and send input

soft-ue-cli pie-session start --mode SelectedViewport
soft-ue-cli trigger-input key --key SpaceBar
soft-ue-cli trigger-input action --action-name IA_SwitchCharacter
soft-ue-cli pie-session stop

Capture a screenshot of the editor viewport

soft-ue-cli capture screenshot --source viewport --output file
soft-ue-cli capture viewport --source editor --scale 50 --color-mode grayscale --output file
soft-ue-cli capture viewport --source editor --width 960 --color-mode monochrome --output file

Edit a Blueprint graph programmatically

soft-ue-cli blueprint node add /Game/BP_Player K2Node_CallFunction \
  --properties '{"FunctionReference": {"MemberName": "PrintString"}}'
soft-ue-cli blueprint pin connect /Game/BP_Player node1 "exec" node2 "execute"

Manage Blueprint interfaces

soft-ue-cli blueprint interface modify /Game/ABP_Character add ALI_Locomotion
soft-ue-cli blueprint interface modify /Game/ABP_Character remove ALI_Locomotion
soft-ue-cli blueprint inspect /Game/ABP_Character --include interfaces

Create an anim layer function on an AnimLayerInterface

soft-ue-cli blueprint node add /Game/ALI_Locomotion AnimLayerFunction --graph-name FullBody

Create an AnimBlueprint state machine

soft-ue-cli anim state-machine add /Game/ABP_Hero Locomotion --default-state Idle
soft-ue-cli anim state add /Game/ABP_Hero Locomotion Run --position 500,0
soft-ue-cli anim transition add /Game/ABP_Hero Locomotion Idle Run --rule true
soft-ue-cli blueprint node add /Game/ABP_Hero AnimGraphNode_SequencePlayer --graph-name Run

Repair an AnimMontage slot segment

soft-ue-cli anim montage set-slot-animation /Game/Anim/AM_Attack /Game/Anim/AS_Attack_RTG \
  --slot-name UpperBody --section Attack --save

Inspect an AnimMontage

soft-ue-cli anim montage inspect /Game/Anim/AM_Attack --include notifies,sections,slots

Retarget one AnimSequence

soft-ue-cli anim retarget sequence /Game/Anim/AS_Attack /Game/Anim/RTG/AS_Attack_RTG \
  --source-mesh /Game/Characters/SKM_Source --target-mesh /Game/Characters/SKM_Target \
  --ik-retargeter /Game/Characters/RTG_SourceToTarget --overwrite --save

Insert a node between two connected nodes

soft-ue-cli insert-graph-node /Game/ABP_Hero AnimGraphNode_LinkedAnimLayer \
  {source-guid} OutputPose {target-guid} InputPose --graph-name AnimGraph

Save and compile after edits

soft-ue-cli blueprint compile /Game/ABP_Hero
soft-ue-cli asset save /Game/ABP_Hero

Refresh GameplayTags after editing config

soft-ue-cli reload-gameplay-tags
soft-ue-cli request-gameplay-tag Status.Effect.Burning

Disconnect a specific wire (preserving others)

soft-ue-cli blueprint pin disconnect /Game/ABP_Hero {node-guid} OutputPose \
  --target-node {other-guid} --target-pin InputPose

Convert a Blueprint to C++ using the LLM skill

# List available skills
soft-ue-cli skills list

# Feed the blueprint-to-cpp skill to your LLM client
soft-ue-cli skills get blueprint-to-cpp
# The LLM reads the skill instructions, then runs:
#   soft-ue-cli query-enum /Game/Data/E_Dependency
#   soft-ue-cli query-struct /Game/Data/S_Dependency
#   soft-ue-cli blueprint inspect /Game/BP_Player --include all --include-inherited
#   soft-ue-cli blueprint graph inspect /Game/BP_Player --list-callables
# ...and generates the .h/.cpp files from the JSON responses

Populate a level from a reference image

# Get the level-from-image skill instructions
soft-ue-cli skills get level-from-image
# The LLM analyzes the image, searches for matching assets, places them,
# then enters a visual feedback loop:
#   soft-ue-cli set-viewport-camera --preset top --ortho-width 8000
#   soft-ue-cli capture viewport --source editor --output file
#   soft-ue-cli capture viewport --source editor --scale 50 --color-mode grayscale
# Compares screenshot to reference, auto-corrects, then asks for human feedback

Profile with UE Insights

soft-ue-cli insights-capture start --channels CPU,GPU
# ... run your scenario ...
soft-ue-cli insights-capture stop
soft-ue-cli insights-analyze latest --analysis-type cpu

Use as an MCP server (Claude Desktop, Cursor, etc.)

# Install with MCP support
pip install soft-ue-cli[mcp]

# Run the MCP server (used in MCP client config, not run manually)
soft-ue-cli mcp-serve

Add to your MCP client config (e.g. claude_desktop_config.json):

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

Configuration

Environment Variables

Server Discovery Order

The CLI finds the bridge server using this priority:

1. --server command-line flag
2. SOFT_UE_BRIDGE_URL environment variable
3. SOFT_UE_BRIDGE_PORT environment variable (constructs http://127.0.0.1:<port>)
4. .soft-ue-bridge/instance.json file (searched upward from the current working directory -- written automatically by the plugin at startup)
5. http://127.0.0.1:8080 (default fallback)

Conditional Compilation for Teams

If you want only specific developers to compile the bridge plugin (to avoid any overhead for artists or designers), use the SOFT_UE_BRIDGE environment variable in your Target.cs:

// MyGameEditor.Target.cs
if (Environment.GetEnvironmentVariable("SOFT_UE_BRIDGE") == "1")
{
    ExtraModuleNames.Add("SoftUEBridge");
}

Developers who need the bridge set SOFT_UE_BRIDGE=1 in their environment. Everyone else builds without it.

Compatibility

Development

git clone https://github.com/softdaddy-o/soft-ue-cli
cd soft-ue-cli
pip install -e .
pytest -v

Feedback

Report a bug

soft-ue-cli report-bug \
  --title "Short bug summary" \
  --description "Detailed description"

Do not include project-specific information, personal information, or any clue that could identify your project. Replace project names, internal paths, asset names, emails, tokens, and other sensitive details with generic placeholders.

Optional flags: --steps, --expected, --actual, --severity critical|major|minor, --no-system-info.

Request a feature

soft-ue-cli request-feature \
  --title "Short feature summary" \
  --description "What the feature should do"

Do not include project-specific information, personal information, or any clue that could identify your project. Replace project names, internal paths, asset names, emails, tokens, and other sensitive details with generic placeholders.

Optional flags: --use-case, --priority enhancement|nice-to-have.

Share a testimonial

soft-ue-cli submit-testimonial \
  --message "Great tool for UE automation!" \
  --agent-name "Claude Code" \
  --rating 5

Opens a GitHub Issue (label: testimonial) with auto-collected metadata (CLI version, usage streak, top tools). A consent prompt appears before posting unless --yes is passed.

All feedback commands require GitHub auth: set GITHUB_TOKEN env var or run gh auth login.

Frequently Asked Questions

What is soft-ue-cli?

soft-ue-cli is a Python tool that gives AI agents and developers 120+ commands and tools for Unreal Engine 5 automation. It works as an MCP server (for Claude Desktop, Cursor, Windsurf, and other MCP clients) or as a standard CLI (for Claude Code, shell scripts, CI/CD). It communicates with a C++ plugin (SoftUEBridge) running inside UE via HTTP/JSON-RPC for live editor/runtime work, and it also includes offline parsers for local Unreal files.

How do AI agents use soft-ue-cli?

MCP clients (Claude Desktop, Cursor, Windsurf): Connect via soft-ue-cli mcp-serve. The agent sees 120+ tools with typed schemas and skill prompts -- it can directly call UE operations without going through a terminal.

Claude Code: Runs soft-ue-cli commands in the terminal. Add a CLAUDE.md file to your UE project describing available commands, and Claude Code autonomously queries your level, spawns actors, edits Blueprints, runs PIE sessions, and iterates on your game.

Can I use soft-ue-cli without an AI agent?

Yes. soft-ue-cli is a standard Python CLI. You can use it in shell scripts, CI/CD pipelines, custom automation tools, or any workflow that can invoke command-line programs. Every command outputs structured JSON, making it easy to parse and integrate.

Does it work with packaged/cooked Unreal Engine builds?

Yes, in Development and DebugGame packaged builds by default. The bridge module now uses Unreal's DeveloperTool module type, so Shipping builds exclude it unless the target explicitly enables developer tools (for example via bBuildDeveloperTools = true).

The plugin descriptor restricts SoftUEBridge's editor-only dependency plugins to Editor targets, so Python/editor scripting dependencies are not enabled for packaged game targets.

What Unreal Engine versions are supported?

soft-ue-cli's main development target is Unreal Engine 5.8, while UE 5.7 compatibility remains maintained. That matters if your project cannot move to UE 5.8 yet but still needs an agent-friendly CLI/MCP automation surface.

Is there any runtime performance impact?

The SoftUEBridge plugin adds a lightweight HTTP server that listens on a single port. When no requests are being made, the overhead is negligible. The server processes requests on the game thread to ensure thread safety with UE APIs. Shipping builds exclude the bridge by default; if you intentionally need it there, enable developer tools for that target.

How do I change the default port?

Set the SOFT_UE_BRIDGE_PORT environment variable before launching UE, or use the --server flag when running CLI commands. The default port is 8080.

Can multiple UE instances run simultaneously?

Yes. Each UE instance writes its port to a .soft-ue-bridge/instance.json file in the project directory. Use SOFT_UE_BRIDGE_URL or --server to target a specific instance when multiple are running.

How do I edit Blueprints from the command line?

Use blueprint graph inspect to inspect existing graph nodes, blueprint node add to create new nodes, blueprint pin connect to wire them together, and blueprint node remove to delete nodes. This enables fully programmatic Blueprint construction -- useful for AI-driven development and automated testing.

What is the difference between soft-ue-cli and Unreal Engine Remote Control?

Unreal Engine's built-in Remote Control API focuses on property access and preset-based workflows. soft-ue-cli provides a broader command set specifically designed for AI coding agents -- including Blueprint graph editing, StateTree manipulation, PIE session control, UE Insights profiling, widget inspection, and asset creation -- with a simpler setup process (one pip install, one plugin copy).

What is the difference between soft-ue-cli and UE 5.8's first-party MCP?

UE 5.8's first-party MCP support is the right first stop if your project is already on UE 5.8 and you want Epic's native editor MCP endpoint. soft-ue-cli remains useful when you need UE 5.7 support, cooked Development/DebugGame build support, the same commands from a terminal or CI job, offline .uasset/config inspection, packaged LLM workflow prompts, or structured command metadata and missing-plugin recovery across a broader curated tool surface.

They are complementary. Use the official MCP surface where it covers the editor action directly; use soft-ue-cli when the workflow spans UE 5.7 projects, cooked non-Shipping builds, CLI automation, offline files, canonical command scripts, visual capture transforms, UMG verification, or optional plugin diagnostics.

How do I use soft-ue-cli with Claude Desktop or Cursor?

Run pip install soft-ue-cli[mcp] to install MCP support, then add the server to your MCP client config. For Claude Desktop, add to claude_desktop_config.json:

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

The MCP server exposes 120+ commands as MCP tools and skills as MCP prompts. The AI editor can then directly call UE operations without going through the terminal.

What is the difference between soft-ue-cli and other UE MCP servers?

Support this project

soft-ue-cli is free, open-source, and maintained by one person. If it saves you hours of manual editor work or helps your AI workflow, consider supporting continued development:

• Sponsor on GitHub ??recurring or one-time
• Buy me a coffee on Ko-fi ??quick one-time donation

Using soft-ue-cli in your project? Share your experience ??I'd love to hear about it.

Roadmap

• Track UE 5.8 compatibility and first-party MCP overlap, keeping soft-ue-cli focused on CLI/CI, offline inspection, and curated bridge workflows.
• More LLM skills (Material-to-HLSL, Animation Blueprint automation)
• Visual diff for Blueprint changes
• CI/CD integration examples

License

MIT License. See LICENSE for details.

Links

• PyPI: pypi.org/project/soft-ue-cli
• GitHub: github.com/softdaddy-o/soft-ue-cli
• Claude Code: docs.anthropic.com/en/docs/claude-code