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).
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/chongdashu--unreal-mcp)HTML
<a href="/listings/chongdashu--unreal-mcp"><img src="/api/listings/chongdashu--unreal-mcp/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
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.
{
"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.
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 155 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- <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)
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.