UEMCP - Unreal Engine Model Context Protocol

UEMCP bridges AI assistants with Unreal Engine through a two-tier architecture that separates the MCP server (Node.js) from the Python Editor Plugin, enabling remote deployment of Unreal Engine editors. This implementation provides optimized wrappers around common UE Python API operations, reducing code generation by up to 85%. The repository includes automated setup for AI clients, comprehensive development context, and three specialized Claude agents for enhanced UE workflows. Unlike package-managed MCP servers, this repo is designed to be cloned and potentially forked for maximum customization and development flexibility.

<img src="https://github.com/atomantic/UEMCP/releases/download/v1.0.0/uemcp-demo.gif" alt="UEMCP Demo" width="100%">

🚀 Quick Start (2 minutes)

# Clone and setup
git clone https://github.com/atomantic/UEMCP.git
cd UEMCP
./setup.sh

# Restart Claude Desktop or Claude Code and test:
# "List available UEMCP tools"
# "Organize the actors in the current map into a sensible folder structure and naming convention"

The setup script automatically:

• ✅ Checks and installs Node.js if needed (via Homebrew, apt, yum, or nvm)
• ✅ Installs dependencies and builds the server
• ✅ Detects and configures AI development tools (Claude Desktop, Claude Code, Amazon Q, Gemini Code Assist, OpenAI Codex)
• ✅ Sets up your Unreal Engine project path
• ✅ Optionally installs the UEMCP plugin to your project

The script will detect which AI tools you have installed and offer to configure them:

• Claude Desktop & Claude Code: Native MCP support
• Amazon Q: MCP support via ~/.aws/amazonq/agents/default.json
• Google Gemini (CLI & Code Assist): MCP support via ~/.gemini/settings.json
• OpenAI Codex: Trusted projects via ~/.codex/config.toml
• GitHub Copilot: Usage instructions provided

📝 Windows Users

Recommended: Use WSL (Windows Subsystem for Linux)

# Install WSL if you haven't already
wsl --install

# In WSL/Ubuntu terminal:
git clone https://github.com/atomantic/UEMCP.git
cd UEMCP
./setup.sh

Alternative: Git Bash

• Install Git for Windows which includes Git Bash
• Run ./setup.sh in Git Bash terminal

Note: The setup script will copy (not symlink) the plugin to your UE project on Windows to avoid permission issues.

Advanced options:

# Specify UE project (automatically installs plugin via copy)
./setup.sh --project "/path/to/project.uproject"

# Install with symlink for UEMCP plugin development
./setup.sh --project "/path/to/project.uproject" --symlink

# Non-interactive mode (for CI/CD)
./setup.sh --project "/path/to/project.uproject" --no-interactive

Prompt Examples

The sky is the limit with what you can ask the agent to do. Here are example prompts organized by complexity:

Basic Commands

• Show me all wall meshes in the ModularOldTown folder
• Spawn a cube at location 1000, 500, 0
• Take a screenshot of the current viewport
• List all actors with 'Door' in their name
• Focus the camera on the player start
• Check the UE logs for any errors

Complex Tasks

• Add the Rive Unreal plugin to this project: https://github.com/rive-app/rive-unreal
• Use the OldModularTown assets in this project to build the first floor of a house
• Find all the maze walls and invert them on the X axis to flip the maze over
• Add a textured and colored material to the HorseArena floor

Advanced Python Control

• Use python_proxy to get all actors of type StaticMeshActor
• Execute Python to change all lights to blue
• Run Python code to analyze material usage in the level
• Batch rename all actors to follow a consistent naming convention
• Create a custom layout algorithm for procedural level generation

🎯 Key Feature: Full Python Access in Editor Mode

The python_proxy tool provides complete, unrestricted access to Unreal Engine's Python API. This means AI assistants can execute ANY Python code within the UE editor - from simple queries to complex automation scripts. All other MCP tools are essentially convenience wrappers around common operations that could be done through python_proxy.

Why have other tools if python_proxy can do everything?

1. Efficiency: Specific tools like actor_spawn or viewport_screenshot are optimized shortcuts for common tasks that remove the need for your AI to write larger amounts of python code.
2. Clarity: Named tools make AI intent clearer (e.g., "spawn an actor" vs "execute Python code")
3. Error Handling: Dedicated tools provide better validation and error messages
4. Performance: Less overhead than parsing and executing arbitrary Python for simple operations
5. Discoverability: AI assistants can easily see available operations without knowing the UE Python API

Example: Taking a Screenshot

Using the convenient viewport_screenshot mcp tool:

// One line, clear intent, automatic file handling
viewport_screenshot({ width: 1920, height: 1080, quality: 80 })

Using python_proxy for the same task:

# Much more complex, requires knowing UE Python API
import unreal
import os
import time

# Get project paths
project_path = unreal.Paths.project_saved_dir()
screenshot_dir = os.path.join(project_path, "Screenshots", "MacEditor")

# Ensure directory exists
if not os.path.exists(screenshot_dir):
    os.makedirs(screenshot_dir)

# Generate filename with timestamp
timestamp = int(time.time() * 1000)
filename = f"uemcp_screenshot_{timestamp}.png"
filepath = os.path.join(screenshot_dir, filename)

# Take screenshot with proper settings
unreal.AutomationLibrary.take_high_res_screenshot(
    1920, 1080,
    filepath,
    camera=None,
    capture_hdr=False,
    comparison_tolerance=unreal.ComparisonTolerance.LOW
)

# Would need additional error handling, JPEG conversion for quality, etc.
result = f"Screenshot saved to: {filepath}"

Think of it like this: python_proxy is the powerful command line, while other tools are the convenient GUI buttons.

📊 See detailed comparison of MCP tools vs python_proxy → (average 80%+ code reduction!)

🛠 Available Tools

UEMCP provides 36 MCP tools across 7 categories for comprehensive Unreal Engine control:

📦 Project & Asset Management (3 tools)

• project_info - Get current UE project information
• asset_list - List project assets with filtering
• asset_info - Get detailed asset information (bounds, sockets, materials)

🎭 Actor Management (8 tools)

• actor_spawn - Spawn actors in the level
• actor_duplicate - Duplicate existing actors with offset
• actor_delete - Delete actors by name
• actor_modify - Modify actor properties (location, rotation, scale, mesh)
• actor_organize - Organize actors into World Outliner folders
• actor_snap_to_socket - Snap actors to socket positions for modular building
• batch_spawn - Efficiently spawn multiple actors in one operation
• placement_validate - Validate modular component placement (gaps, overlaps)

🏗️ Level Operations (3 tools)

• level_actors - List all actors in level with properties
• level_save - Save the current level
• level_outliner - Get World Outliner folder structure

📹 Viewport Control (8 tools)

• viewport_screenshot - Capture viewport images
• viewport_camera - Set camera position and rotation
• viewport_mode - Switch to standard views (top, front, side, perspective)
• viewport_focus - Focus camera on specific actor
• viewport_render_mode - Change rendering mode (lit, wireframe, etc.)
• viewport_bounds - Get current viewport boundaries
• viewport_fit - Fit actors in viewport automatically
• viewport_look_at - Point camera at specific coordinates/actor

🎨 Material System (4 tools)

• material_list - List project materials with filtering
• material_info - Get detailed material information and parameters
• material_create - Create new materials or material instances
• material_apply - Apply materials to actor mesh components

🔷 Blueprint System (5 tools)

• blueprint_create - Create new Blueprint classes
• blueprint_list - List project Blueprints with metadata
• blueprint_info - Get Blueprint structure (components, variables, functions)
• blueprint_compile - Compile Blueprints and report errors
• blueprint_document - Generate comprehensive Blueprint documentation

⚙️ System & Advanced (5 tools)

• python_proxy ⭐ - Execute arbitrary Python code with full UE API access
• test_connection - Test Python listener connection and status
• restart_listener - Restart Python listener (hot reload)
• ue_logs - Fetch recent Unreal Engine log entries
• help 📚 - Get comprehensive help and tool documentation

🔧 MCP Server Layer Tools (Additional tools handled by Node.js)

• undo - Undo last operation(s)
• redo - Redo previously undone operations
• history_list - Show operation history with timestamps
• checkpoint_create - Create named save points
• checkpoint_restore - Restore to named checkpoints
• batch_operations - Execute multiple operations in single request

🔍 Validation Feature

All actor manipulation tools (actor_spawn, actor_modify, actor_delete, actor_duplicate) now support automatic validation to ensure operations succeeded as expected:

• validate parameter (default: true) - Verifies changes were applied correctly in Unreal Engine
• Checks location, rotation, scale, mesh, and folder values match requested values
• Returns validation results including any errors or warnings