Skip to content
Back to search

unreal-mcp

SkillWorks with Claude CodeGitHub

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.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/chongdashu--unreal-mcp/badge.svg)](/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

i

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)

  1. <div align="center">
  2. # Model Context Protocol for Unreal Engine
  3. <span style="color: #555555">unreal-mcp</span>
  4. [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
  5. [![Unreal Engine](https://img.shields.io/badge/Unreal%20Engine-5.5%2B-orange)](https://www.unrealengine.com)
  6. [![Python](https://img.shields.io/badge/Python-3.12%2B-yellow)](https://www.python.org)
  7. [![Status](https://img.shields.io/badge/Status-Experimental-red)](https://github.com/chongdashu/unreal-mcp)
  8. </div>
  9. 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).
  10. ## ⚠️ Experimental Status
  11. 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:
  12. - Breaking changes may occur without notice
  13. - Features may be incomplete or unstable
  14. - Documentation may be outdated or missing
  15. - Production use is not recommended at this time
  16. ## 🌟 Overview
  17. The Unreal MCP integration provides comprehensive tools for controlling Unreal Engine through natural language:
  18. | Category | Capabilities |
  19. |----------|-------------|
  20. | **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 |
  21. | **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 |
  22. | **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 |
  23. | **Editor Control** | • Focus viewport on specific actors or locations<br>• Control viewport camera orientation and distance |
  24. All these capabilities are accessible through natural language commands via AI assistants, making it easy to automate and control Unreal Engine workflows.
  25. ## 🧩 Components
  26. ### Sample Project (MCPGameProject) `MCPGameProject`
  27. - Based off the Blank Project, but with the UnrealMCP plugin added.
  28. ### Plugin (UnrealMCP) `MCPGameProject/Plugins/UnrealMCP`
  29. - Native TCP server for MCP communication
  30. - Integrates with Unreal Editor subsystems
  31. - Implements actor manipulation tools
  32. - Handles command execution and response handling
  33. ### Python MCP Server `Python/unreal_mcp_server.py`
  34. - Implemented in `unreal_mcp_server.py`
  35. - Manages TCP socket connections to the C++ plugin (port 55557)
  36. - Handles command serialization and response parsing
  37. - Provides error handling and connection management
  38. - Loads and registers tool modules from the `tools` directory
  39. - Uses the FastMCP library to implement the Model Context Protocol
  40. ## 📂 Directory Structure
  41. - **MCPGameProject/** - Example Unreal project
  42. - **Plugins/UnrealMCP/** - C++ plugin source
  43. - **Source/UnrealMCP/** - Plugin source code
  44. - **UnrealMCP.uplugin** - Plugin definition
  45. - **Python/** - Python server and tools
  46. - **tools/** - Tool modules for actor, editor, and blueprint operations
  47. - **scripts/** - Example scripts and demos
  48. - **Docs/** - Comprehensive documentation
  49. - See [Docs/README.md](Docs/README.md) for documentation index
  50. ## 🚀 Quick Start Guide
  51. ### Prerequisites
  52. - Unreal Engine 5.5+
  53. - Python 3.12+
  54. - MCP Client (e.g., Claude Desktop, Cursor, Windsurf)
  55. ### Sample project
  56. 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.
  57. 1. **Prepare the project**
  58. - Right-click your .uproject file
  59. - Generate Visual Studio project files
  60. 2. **Build the project (including the plugin)**
  61. - Open solution (`.sln`)
  62. - Choose `Development Editor` as your target.
  63. - Build
  64. ### Plugin
  65. Otherwise, if you want to use the plugin in your existing project:
  66. 1. **Copy the plugin to your project**
  67. - Copy `MCPGameProject/Plugins/UnrealMCP` to your project's Plugins folder
  68. 2. **Enable the plugin**
  69. - Edit > Plugins
  70. - Find "UnrealMCP" in Editor category
  71. - Enable the plugin
  72. - Restart editor when prompted
  73. 3. **Build the plugin**
  74. - Right-click your .uproject file
  75. - Generate Visual Studio project files
  76. - Open solution (`.sln)
  77. - Build with your target platform and output settings
  78. ### Python Server Setup
  79. See [Python/README.md](Python/README.md) for detailed Python setup instructions, including:
  80. - Setting up your Python environment
  81. - Running the MCP server
  82. - Using direct or server-based connections
  83. ### Configuring your MCP Client
  84. Use the following JSON for your mcp configuration based on your MCP client.
  85. ```json
  86. {
  87. "mcpServers": {
  88. "unrealMCP": {
  89. "command": "uv",
  90. "args": [
  91. "--directory",
  92. "<path/to/the/folder/PYTHON>",
  93. "run",
  94. "unreal_mcp_server.py"
  95. ]
  96. }
  97. }
  98. }
  99. ```
  100. An example is found in `mcp.json`
  101. ### MCP Configuration Locations
  102. Depending on which MCP client you're using, the configuration file location will differ:
  103. | MCP Client | Configuration File Location | Notes |
  104. |------------|------------------------------|-------|
  105. | Claude Desktop | `~/.config/claude-desktop/mcp.json` | On Windows: `%USERPROFILE%\.config\claude-desktop\mcp.json` |
  106. | Cursor | `.cursor/mcp.json` | Located in your project root directory |
  107. | Windsurf | `~/.config/windsurf/mcp.json` | On Windows: `%USERPROFILE%\.config\windsurf\mcp.json` |
  108. Each client uses the same JSON format as shown in the example above.
  109. Simply place the configuration in the appropriate location for your MCP client.
  110. ## License
  111. MIT
  112. ## Questions
  113. 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 in

Free to use. If it’s helped, pass it on.