Unreal MCP

Connect AI assistants directly to the Unreal Editor via MCP

Features · Installation · Usage · Tools Reference · Troubleshooting

Unreal MCP bridges AI assistants (Claude, Cursor, VS Code Copilot) and the Unreal Editor through the Model Context Protocol. Spawn actors, edit materials, build Blueprint graphs, construct Behavior Trees, design UMG Widget Blueprints — all from natural language.

_{Click to watch the demo on YouTube}

Features

68 tools across 9 categories — all accessible through natural language.

Installation

Prerequisites

• Unreal Engine 5.6+
• Python 3.11+
• uv — fast Python package manager
• An MCP client (Claude Desktop, VS Code, Cursor, etc.)

Step 1 — Install the Plugin

Option A: Clone from GitHub (Recommended)

cd YourProject/Plugins
git clone https://github.com/GenOrca/unreal-mcp.git

YourProject/
└── Plugins/
    └── unreal-mcp/
        ├── Source/
        ├── Content/
        ├── mcp-server/        ← MCP server included
        └── UnrealMCPython.uplugin

Option B: Install from Fab

[!NOTE]
The Fab version may lag behind the latest GitHub release. After installing from Fab, you still need the mcp-server/ folder from this repository.

Step 2 — Enable Plugins in Unreal

1. Open your project in Unreal Engine
2. Edit > Plugins — enable Unreal-MCPython and Python Editor Script Plugin
3. Restart the editor

Step 3 — Configure your MCP Client

Add the server to your MCP client config:

{
  "mcpServers": {
    "unreal-mcpython": {
      "command": "uv",
      "args": [
        "--directory",
        "C:/absolute/path/to/unreal-mcp/mcp-server",
        "run",
        "src/unreal_mcp/main.py"
      ]
    }
  }
}

[!IMPORTANT]
Replace the path with the actual absolute path to your mcp-server folder.

Step 4 — Connect

1. Restart your MCP client
2. The MCP server starts automatically
3. Verify — you should see Unreal-MCPython tools listed in your client

Usage

Just describe what you want in natural language:

"Place 10 trees randomly on the terrain surface"
"Find all static meshes with 'rock' in the name"
"Set the base color of MI_Ground to dark brown"
"Explain what the selected Blueprint nodes do"
"Add a PrintString node to BP_Player's EventGraph and connect it to BeginPlay"
"Build a Blueprint graph with event tick, delta time, and a timeline node"
"Create a Behavior Tree with a Selector root, two Sequences, and MoveTo/Wait tasks"
"Create a HUD widget with a health bar and score label, set the text to 'Score: 0'"
"Add a CanvasPanel root to WBP_MainMenu and place a TextBlock at position (200, 100) with font size 48"

Tools Reference

Supported widget types: CanvasPanel, TextBlock, Button, Image, HorizontalBox, VerticalBox, Border, Overlay, ScrollBox, SizeBox, CheckBox, EditableText, EditableTextBox, ProgressBar, Slider

Canvas slot properties (when parent is CanvasPanel): slot_position, slot_size, slot_alignment, slot_z_order

How It Works

┌─────────────────┐         MCP         ┌─────────────────┐   TCP/JSON   ┌──────────────────┐
│   AI Assistant   │  ◄──────────────►  │   MCP Server    │  ◄────────►  │  Unreal Engine   │
│ (Claude, Cursor) │                     │   (Python/uv)   │              │  (Plugin + Python)│
└─────────────────┘                     └─────────────────┘              └──────────────────┘

The MCP server translates AI tool calls into Python commands executed inside Unreal Engine's embedded Python interpreter.

Troubleshooting

References

• Model Context Protocol
• Unreal Engine Python API

Contributing

Issues, feature requests, and pull requests are welcome on GitHub.

License

Apache-2.0