# Model Context Protocol for Unreal Engine unreal-mcp [![Unreal Engine](https://camo.githubusercontent.com/2cef887fc33175dbaf89b3e671798133b7237158846a570f6d5b17fa47efd86a/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f556e7265616c253230456e67696e652d352e352532422d6f72616e6765)](https://www.unrealengine.com) [![Python](https://camo.githubusercontent.com/310ed715dabff1abfd901bfc719b0b15beb9de8f440f7fb0f01c6763535b67c2/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f507974686f6e2d332e31322532422d79656c6c6f77)](https://www.python.org) [![Status](https://camo.githubusercontent.com/85d17b66b0b6a470b6ac1d9d1fbbc395df5538ab63b7c5a32e92c467339a6d20/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5374617475732d4578706572696d656e74616c2d726564)](https://github.com/chongdashu/unreal-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 and delete actors (cubes, spheres, lights, cameras, etc.)
• Set actor transforms (position, rotation, scale)
• Query actor properties and find actors by name
• List all actors in the current level | | **Blueprint Development** | • Create new Blueprint classes with custom components
• Add and configure components (mesh, camera, light, etc.)
• Set component properties and physics settings
• Compile Blueprints and spawn Blueprint actors
• Create input mappings for player controls | | **Blueprint Node Graph** | • Add event nodes (BeginPlay, Tick, etc.)
• Create function call nodes and connect them
• Add variables with custom types and default values
• Create component and self references
• Find and manage nodes in the graph | | **Editor Control** | • Focus viewport on specific actors or locations
• Control 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 subsystems - Implements actor manipulation tools - Handles command execution and response handling ### Python MCP Server `Python/unreal_mcp_server.py` - Implemented in `unreal_mcp_server.py` - Manages TCP socket connections to the C++ plugin (port 55557) - Handles command serialization and response parsing - Provides error handling and connection management - Loads and registers tool modules from the `tools` directory - Uses 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](https://github.com/chongdashu/unreal-mcp/blob/main/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) ### Sample project 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. 1. **Prepare the project** - Right-click your .uproject file - Generate Visual Studio project files 2. **Build the project (including the plugin)** - Open solution (`.sln`) - Choose `Development Editor` as your target. - Build ### Plugin Otherwise, if you want to use the plugin in your existing project: 1. **Copy the plugin to your project** - Copy `MCPGameProject/Plugins/UnrealMCP` to your project's Plugins folder 2. **Enable the plugin** - Edit > Plugins - Find "UnrealMCP" in Editor category - Enable the plugin - Restart editor when prompted 3. **Build the plugin** - Right-click your .uproject file - Generate Visual Studio project files - Open solution (`.sln) - Build with your target platform and output settings ### Python Server Setup See [Python/README.md](https://github.com/chongdashu/unreal-mcp/blob/main/Python/README.md) for detailed Python setup instructions, including: - Setting up your Python environment - Running the MCP server - Using direct or server-based connections ### Configuring your MCP Client Use the following JSON for your mcp configuration based on your MCP client. ```json { "mcpServers": { "unrealMCP": { "command": "uv", "args": [ "--directory", "", "run", "unreal_mcp_server.py" ] } } } ``` An example is found in `mcp.json` ### MCP Configuration Locations Depending on which MCP client you're using, the configuration file location will differ: | MCP Client | Configuration File Location | Notes | |------------|------------------------------|-------| | Claude Desktop | `~/.config/claude-desktop/mcp.json` | On Windows: `%USERPROFILE%\.config\claude-desktop\mcp.json` | | Cursor | `.cursor/mcp.json` | Located in your project root directory | | Windsurf | `~/.config/windsurf/mcp.json` | On Windows: `%USERPROFILE%\.config\windsurf\mcp.json` | Each client uses the same JSON format as shown in the example above. Simply place the configuration in the appropriate location for your MCP client. ## License MIT ## Questions For questions, you can reach me on X/Twitter: [@chongdashu](https://www.x.com/chongdashu)