Content
<div align="center">
# Unreal Engine MCP Toolkit
[](LICENSE)
[](https://www.unrealengine.com)
[](https://www.python.org)
[](#)
[](CONTRIBUTING.md)
**Control Unreal Engine from an AI assistant via the Model Context Protocol.**
</div>
This project lets MCP clients (Claude Code, Claude Desktop, Cursor, Windsurf, ...) drive the Unreal Engine editor through natural language: spawn and configure actors, build Blueprints, wire up event graphs node-by-node, edit Data Assets, and more — all through a native C++ plugin talking to a Python MCP server over TCP.
It grew out of the broader "MCP for Unreal Engine" idea that a few community projects have explored, then went considerably further on the Blueprint-graph-editing side: casting, branching, sequencing, variable get/set, pin splitting/breaking/deleting, and a real compile-error reporting path, all reachable from an AI assistant instead of hand-wiring nodes in the editor.
## ⚠️ Experimental Status
- Breaking changes may occur without notice.
- Features may be incomplete or unstable.
- Not recommended for production use.
- Tested primarily on UE 5.5–5.7, Windows.
## 🌟 What you can do with it
| Category | Capabilities |
|----------|-------------|
| **Actor Management** | Spawn/delete actors, set transforms, query properties, find actors by name, list level contents, assign meshes. |
| **Blueprint Development** | Create Blueprint classes, add/configure components, set physics properties, compile with real error/warning reporting, spawn Blueprint actors, duplicate assets, list a Blueprint's full function set (including inherited). |
| **Blueprint Node Graph** | Add event/function nodes, connect pins, add typed variables — plus [extended graph ops](Docs/Tools/blueprint_graph_extensions.md): dynamic casts, branches, execution sequences, self-context variable get/set, pin splitting/breaking/removing, node deletion, literal default-value injection, and full-graph node dumps (including interface graphs) for tracing execution chains. |
| **Data Assets** | Read/write arbitrary Data Asset properties (including nested struct arrays), dump DataTable rows as JSON, dump a Widget Blueprint's full widget tree. |
| **UMG** | Create widget Blueprints, add buttons/text blocks, bind events and text. |
| **Editor Control** | Focus and orient the viewport. |
See [Docs/Tools](Docs/Tools/README.md) for the full tool reference.
## 🧩 Components
- **`UnrealMCP/`** — the C++ Editor plugin. Runs a native TCP server inside the Unreal Editor, receives commands, executes them against the editor/engine APIs, and returns structured JSON.
- **`Python/`** — the MCP server (FastMCP-based). Bridges an MCP client to the plugin's TCP socket (port `55557` by default), and organizes tools into modules under `Python/tools/`.
- **`Docs/`** — tool reference and setup notes.
## 🚀 Quick Start
### Prerequisites
- Unreal Engine 5.5+
- Python 3.12+
- [uv](https://docs.astral.sh/uv/)
- An MCP client (Claude Code, Claude Desktop, Cursor, Windsurf, ...)
### 1. Install the plugin
Copy `UnrealMCP/` into your Unreal project's `Plugins/` folder (create that folder if it doesn't exist yet), so you end up with `YourProject/Plugins/UnrealMCP/`.
Then:
1. Right-click your `.uproject` file → **Generate Visual Studio project files**.
2. Open the generated `.sln`, select **Development Editor**, and build.
3. Open the project in the Unreal Editor. If prompted, enable the **UnrealMCP** plugin under Edit → Plugins → Editor, and restart the editor.
> Changed the plugin's C++ code afterwards? Use Live Coding (`Ctrl+Alt+F11`) for a quick iteration loop while the editor is open — but note that Live Coding patches don't survive an editor restart unless a full rebuild has baked them in. If a tool you just added mysteriously reports "Unknown command" after restarting the editor, touch the source file to force a full recompile.
### 2. Set up the Python server
```bash
cd Python
uv sync
```
See [Python/README.md](Python/README.md) for direct-connection vs. server-based setup options.
### 3. Configure your MCP client
```json
{
"mcpServers": {
"unrealMCP": {
"command": "uv",
"args": [
"--directory",
"absolute/path/to/this/repository/Python",
"run",
"unreal_mcp_server.py"
]
}
}
}
```
An example is in [`mcp.json`](mcp.json). Where this file lives depends on your client — see the table below.
| MCP Client | Configuration File Location |
|------------|------------------------------|
| Claude Desktop | `%USERPROFILE%\.config\claude-desktop\mcp.json` (Windows) |
| Cursor | `.cursor/mcp.json` in your project root |
| Windsurf | `%USERPROFILE%\.config\windsurf\mcp.json` (Windows) |
### 4. Verify
With the Unreal Editor open (plugin loaded) and the Python server pointed at it, ask your MCP client to list actors in the current level, or spawn a cube. If it works end-to-end, you're set.
## 🤝 Contributing
Issues and pull requests are very welcome — this is genuinely a community tool, not a solo project I'm precious about. See [CONTRIBUTING.md](CONTRIBUTING.md) for how to get set up, the (light) coding conventions, and what makes a good bug report or PR. If you're not sure whether something's worth a PR, open an issue first and ask.
## Acknowledgments
This project builds on the general idea of exposing Unreal Engine to MCP clients that a few community projects explored first. No specific attribution is requested by any of them, but if you're looking for other tools in this space, searching "Unreal Engine MCP" on GitHub will turn up several.
## License
[MIT](LICENSE)
