GitHub - chongdashu/unreal-mcp: Enable AI assistant clients like Cursor, Windsurf and Claude Desktop to control Unreal Engine through natural language using the Model Context Protocol (MCP).
This project enables AI assistant clients like Cursor, Windsurf, and Claude Desktop to control Unreal Engine through natural language using the Model Context Protocol (MCP).
⚠️ Experimental Status
This project is currently in an experimental state. The API, functionality, and implementation details are subject to significant changes. While we encourage testing and feedback, please be aware that:
- Breaking changes may occur without notice.
- Features may be incomplete or unstable.
- Documentation may be outdated or missing.
- Production use is not recommended at this time.
🌟 Overview
The Unreal MCP integration provides comprehensive tools for controlling Unreal Engine through natural language:
| Category | Capabilities |
|---|---|
| Actor Management | Create/delete actorsSet actor transformsQuery actor propertiesList all actors in the current level |
| Blueprint Development | Create new Blueprint classes with custom componentsConfigure componentsCompile Blueprints and spawn Blueprint actorsCreate input mappings for player controls |
| Blueprint Node Graph | Add event nodesCreate function call nodes and connect themAdd variables with custom types and default valuesCreate component and self referencesFind and manage nodes in the graph |
| Editor Control | Focus viewport on specific actors or locationsControl viewport camera orientation and distance |
All these capabilities are accessible through natural language commands via AI assistants, making it easy to automate and control Unreal Engine workflows.
🧩 Components
Sample Project (MCPGameProject)
- MCPGameProject: Based off the Blank Project, but with the UnrealMCP plugin added.
- Plugin (UnrealMCP): MCPGameProject/Plugins/UnrealMCP - Native TCP server for MCP communication Integrates with Unreal Editor subsystemsImplements actor manipulation toolsHandles command execution and response handling
- Python MCP Server: Python/unreal_mcp_server.py - Manages TCP socket connections to the C++ plugin (port 55557)Handles command serialization and response parsingProvides error handling and connection managementLoads and registers tool modules from the tools directoryUses the FastMCP library to implement the Model Context Protocol
📂 Directory Structure
MCPGameProject/
- Example Unreal project
Plugins/UnrealMCP/
- C++ plugin source
Source/UnrealMCP/
- Plugin source code
UnrealMCP.uplugin - Plugin definition
Python/
- Python server and tools
tools/
- Tool modules for actor, editor, and blueprint operations
scripts/
- Example scripts and demos
Docs/
- Comprehensive documentation
(See Docs/README.md for documentation index)
🚀 Quick Start Guide
Prerequisites:
- Unreal Engine 5.5+
- Python 3.12+
- MCP Client (e.g., Claude Desktop, Cursor, Windsurf)
For getting started quickly, feel free to use the starter project in MCPGameProject. This is a UE 5.5 Blank Starter Project with the UnrealMCP.uplugin already configured.
Prepare the project:
- Right-click your .uproject file.
- Generate Visual Studio project files.
- Build the project (including the plugin).
- Open solution (
.sln). - Choose
Development Editoras your target. - Build Plugin Otherwise, if you want to use the plugin in your existing project:
- Copy the plugin to your project.
- Copy
MCPGameProject/Plugins/UnrealMCPto your project’s Plugins folder. - Enable the plugin - Edit > Plugins Find “UnrealMCP” in Editor category Enable the plugin.
- Restart editor when prompted.
- Build the plugin.