runeape-sats/unreal-mcp

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
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:
bash
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 unrealmcp package importable.
### 3. Configure MCP server
if you are using Claude Desktop → File → Settings → Developer → Edit Config claudedesktopconfig.json and add the following, adjusting the path to your local repository:
json
"mcpServers": {
"unreal-mcp": {
"command": "uv",
"args": ["--directory", "\\path\\to\\unreal-mcp", "run", "unrealmcpserver.py"],
"env": {}
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
unrealmcp/ # 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)
testcastleassets.py
testcastleworkflow.py
testunrealcli.py
Root-level shim modules (unrealmcpserver.py, unrealcli.py, etc.) re-export from unrealmcp. 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"