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, 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 surface is canonical, which removed flat names map to which canonical tools, 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.
• 120+ commands and tools covering actors, Blueprints, materials, StateTrees, Mutable/CustomizableObject, widgets, assets, config files, PIE sessions, profiling, screenshots, and local Unreal file analysis.
• Canonical command families only -- UMG, capture, Mutable, StateTree, animation, asset, and Blueprint workflows are grouped under umg, capture, mutable, statetree, anim, asset, and blueprint. Removed flat names are discoverable with commands --include-removed.
• 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, anim, asset, blueprint) are now the supported public command surface. Removed flat commands are listed only as migration metadata via commands --include-removed.
• 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.

UE 5.8 MCP Positioning

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 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.
• It reports removed flat command migrations through commands --include-removed instead of keeping duplicate public command names alive.
• 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.

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 err