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 ways to connect. Same 60+ tools. One pip install. One plugin copy.

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.
• 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

Claude Code
    |
    |  (runs CLI commands in terminal)
    v
soft-ue-cli  (Python process)
    |
    |  HTTP / JSON-RPC requests
    v
SoftUEBridge plugin  (C++ UGameInstanceSubsystem, inside UE process)
    |
    |  Native UE API calls on the game thread
    v
Unreal Engine 5 editor or runtime

The SoftUEBridge plugin is a lightweight C++ UGameInstanceSubsystem that starts an embedded HTTP server on port 8080 when UE launches. The CLI sends JSON-RPC requests to this server, and the plugin executes the corresponding UE operations on the game thread, returning structured JSON responses.

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.

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 | | 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 | | 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 assets | | diff-uasset | Diff two local .uasset files offline by parsed metadata, with best support for Blueprint assets | | add-graph-node | Add a node to a Blueprint or Material graph (supports AnimLayerFunction for ALIs) | | modify-interface | Add or remove an implemented interface on a Blueprint or AnimBlueprint | | remove-graph-node | Remove a node from a graph | | connect-graph-pins | Connect two pins between graph nodes | | disconnect-graph-pin | Disconnect pin connections (all or specific with --target-node/--target-pin) | | insert-graph-node | Atomically insert a node between two connected nodes | | set-node-position | Batch-set node positions for graph layout | | compile-blueprint | Compile a Blueprint or AnimBlueprint and return the result | | compile-material | Compile a Material, MaterialInstance, or MaterialFunction | | save-asset | Save a modified asset to disk (with optional --checkout for source control) | | set-node-property | Set properties on a graph node by GUID (UPROPERTY, inner structs, pin defaults) |

Asset Management

| Command | Description | |---------|-------------| | query-asset | Search the Content Browser by name, class, or path -- also inspect DataTables | | create-asset | Create new Blueprint, Material, DataTable, World (Level), or other asset types | | delete-asset | Delete an asset | | set-asset-property | Set a property on a Blueprint CDO or component | | get-asset-diff | Get property-level diff of an asset vs. source control | | get-asset-preview | Get a thumbnail/preview image of an asset | | open-asset | Open an asset in the editor | | find-references | Find assets, variables, or functions referencing a given asset |

Material Inspection

| Command | Description | |---------|-------------| | query-material | Inspect Material, Material Instance, or Material Function -- parameters, nodes, connections, --parent-chain | | query-mpc | Read or write Material Parameter Collection scalar/vector values |

Class and Type Inspection

| Command | Description | |---------|-------------| | class-hierarchy | Inspect class inheritance chains -- ancestors, descendants, or both |

Play-In-Editor (PIE) Control

| Command | Description | |---------|-------------| | pie-session | Start, stop, pause, resume PIE -- also query actor state during play | | trigger-input | Send input events to a running game (PIE or packaged build) |

Screenshot and Visual Capture

| Command | Description | |---------|-------------| | capture-screenshot | Capture the editor view