This repository contains a Model Context Protocol (MCP) Python server that allows Claude Desktop to interact with Unreal Engine 5.3 (via Remote Control API), creating and manipulating 3D objects based on text prompts. This integration enables Claude to build and modify 3D scenes in Unreal Engine through natural language, representing an early step toward text-to-game-generation technology.
Current Features:
use Claude Desktop text prompts to arrange assets in Unreal Engine Editor
pure python Unreal Engine MCP server
ดาว
47
เครื่องมือ
—
อัปไทม์
—
create static meshes for assembling primitive shapes
look up Unreal project folder for assets
list actors in the current level and inspect the current editor selection
save the current level from MCP
call arbitrary Unreal Remote Control functions
read and write Unreal object properties through the Remote Control property endpoint
direct CLI with per-command --help for non-MCP agents
shared castle workflow, sample agent skill, and TLA+ use-case model
castle reset workflow and first-class castle MCP tools
Quick Start
1. Requirements
Python 3.10+
Unreal Engine 5.3 with Remote Control API (plugin) enabled
2. Installation
Clone the repository and install in editable mode:
git clone https://github.com/runeape-sats/unreal-mcp.git
cd unreal-mcp
pip install -e .
This installs the unreal-mcp-cli command and makes the unreal_mcp package importable.
3. Configure MCP server
if you are using Claude Desktop → File → Settings → Developer → Edit Config claude_desktop_config.json and add the following, adjusting the path to your local repository:
If you already have other MCP servers configured (like blender-mcp), you may need to disable them to ensure they don't conflict.
4. Launch Unreal Engine
Open Unreal Engine with your project and ensure the Remote Control API plugin is enabled.
5. Launch MCP client (such as Claude Desktop)
Restart Claude Desktop (i.e., need a clean exit without Claude's icon in the system tray) to load the new configuration. You can verify if it's connected by asking Claude to create objects in Unreal Engine.
Project Structure
unreal_mcp/ # Core package
__init__.py
server.py # MCP server — registers all tools
cli.py # Direct CLI with subcommands and --help
connection.py # HTTP connection to Unreal Remote Control API
actors.py # Actor create / modify / delete helpers
assets.py # Asset discovery and level info
remote.py # Generic Remote Control and editor helpers
utils.py # Shared constants and parsing utilities
examples/ # Example workflows (separate from core)
castle/
workflow.py # Castle build / verify / reset workflow
assets/castle-plan.json
specs/CastleConstruction.tla
tests/ # Unit tests (20 tests)
test_castle_assets.py
test_castle_workflow.py
test_unreal_cli.py
Root-level shim modules (unreal_mcp_server.py, unreal_cli.py, etc.) re-export from unreal_mcp.* for backward compatibility.
Features
Basic Object Creation
Create primitive shapes with a variety of parameters:
Cubes, Spheres, Cylinders, Planes, Cones
Custom position, rotation, scale
Custom colors and materials
Example prompt: "Create a red cube at position 100, 200, 50"
Blueprint Actor Creation
Spawn actors from Blueprint classes:
Buildings, props, characters, etc.
Custom parameters like in Basic Object Creation
Example prompt: "Spawn a bench from the blueprint at /Game/CustomAsset/Blueprints/BP_Bench01"
Scene Manipulation
Modify existing objects:
Change position, rotation, scale
Adjust colors and materials
Toggle visibility
Example prompt: "Move the cube to position 0, 0, 100 and rotate it 45 degrees"
Editor Introspection And Selection
Inspect the current level and editor selection:
List all actors in the current level, optionally with transforms
Read the actors currently selected in the editor
Select actors by label from MCP
Save the current level after a batch of changes
Example prompt: "List all actors with 'Bench' in the label and then select them"
Generic Remote Control Access
The server now exposes a generic Remote Control escape hatch so you can reach Unreal functionality that does not yet have a dedicated MCP tool:
Call arbitrary functions on any object path
Resolve an actor label to an object path automatically
Target a component by class when reading or writing properties
Read and write properties through /remote/object/property
This is useful for driving lights, post process volumes, components, editor subsystems, and custom Blueprint-exposed APIs without adding a new Python wrapper first.
Direct CLI Access
Agents that do not speak MCP can use the direct CLI instead:
unreal-mcp-cli --help lists all commands
unreal-mcp-cli <command> --help shows how to use one function
Commands route directly to the same Unreal helper modules used by the MCP server
If you have not installed the editable script yet, use .venv\Scripts\python.exe unreal_cli.py --help.
Castle Skill And TLA+ Model
The repo now includes:
a reusable castle plan in examples/castle/assets/castle-plan.json
a sample skill in .github/skills/unreal-castle-builder/SKILL.md
a TLA+ use-case model in examples/castle/specs/CastleConstruction.tla
dedicated castle create, verify, and reset entry points in both the CLI and MCP server
The castle workflow is designed so an agent can inspect CLI help, build a castle from basic shapes, and verify the result by listing actors.
The build workflow removes old castle actors with the same planned labels before placing the new ones by default. It now supports deterministic variation presets for layout, size, palette, and yaw while keeping the same required core actor set. The reset workflow deletes a castle by prefix, and the TLA+ model now covers retries, rebuilds, and variant selection as well as successful completion.
Asset Discovery
Search for and list available assets:
Filter by asset type (blueprints, meshes, materials)
Search in specific paths
Find assets matching certain terms
Example prompt: "List all bench static meshes in the project"
Example Prompts
Here are some example prompts you can use with Claude:
Create a blue sphere at position 0, 100, 50 with scale 2, 2, 2
Create a scene with a red cube at 0,0,0, a green sphere at 100,0,0, and a blue cylinder at 0,100,0
List all blueprint assets in the /Game/CustomAsset folder
Get information about the current level
Create a cylinder and then change its color to yellow
List all actors whose label contains Bench
Show me the actors currently selected in the editor
Select actors Bench_A, Bench_B, and Bench_C
Save the current level
Set the intensity property on actor KeyLight to 5000
Call a remote function on actor SkyLight to recapture the scene
Use the CLI help for the castle workflow
Create a castle from basic shapes with prefix SkillCastle
Create a grand sandstone courtyard castle at a new placement
Verify the SkillCastle actors exist in the level
Reset the SkillCastle actors after verification
New MCP Tools
In addition to the existing spawn, modify, delete, and asset lookup tools, the server now exposes:
list_level_actors: List actors with optional filtering and transform data
get_selected_actors: Inspect the current Unreal Editor selection
select_actors: Select actors by label
save_current_level: Save the open map
remote_call: Call any Unreal Remote Control function by object path or actor label
get_object_property: Read any Unreal object property
set_object_property: Write any Unreal object property
create_basic_castle: Build the shared primitive castle workflow directly from MCP
verify_basic_castle: Verify the expected castle actor set by prefix
reset_basic_castle: Delete castle actors by prefix or strict plan labels
The castle create entry point accepts layout, size, palette, origin, and yaw so agents can generate deliberate castle variants while the verification step still checks for the same required labels.
For complex remote_call or property writes, prefer JSON-shaped arguments so nested parameter structs survive parsing cleanly.
CLI Setup
Install the project in editable mode inside your virtual environment to get the unreal-mcp-cli command:
create-basic-castle replaces matching old castle actors by default. Use --keep-existing only if you explicitly want overlapping duplicates.
Named presets provide controlled variation: --layout changes the footprint, --size changes the overall scale, --palette changes default colors, and --origin or --yaw change placement/orientation.