Unreal Engine MCP Bridge

<div align="center"> # Model Context Protocol for Unreal Engine <span style="color: #555555">unreal-mcp</span> [](https://opensource.org/licenses/MIT) [](https://www.unrealengine.com) [](https://www.python.org) [](https://github.com/chongdashu/unreal-mcp) </div> 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.)<br>• Set actor transforms (position, rotation, scale)<br>• Query actor properties and find actors by name<br>• List all actors in the current level | | **Blueprint Development** | • Create new Blueprint classes with custom components<br>• Add and configure components (mesh, camera, light, etc.)<br>• Set component properties and physics settings<br>• Compile Blueprints and spawn Blueprint actors<br>• Create input mappings for player controls | | **Blueprint Node Graph** | • Add event nodes (BeginPlay, Tick, etc.)<br>• Create function call nodes and connect them<br>• Add variables with custom types and default values<br>• Create component and self references<br>• Find and manage nodes in the graph | | **Editor Control** | • Focus viewport on specific actors or locations<br>• 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](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](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", "<path/to/the/folder/PYTHON>", "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)