UnrealMCPHub
Standalone MCP Hub for managing Unreal Engine development lifecycle - build, launch, monitor, and proxy UE MCP instances
Ask AI about UnrealMCPHub
Powered by Claude ยท Grounded in docs
I know everything about UnrealMCPHub. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
UnrealMCPHub
Central management platform for Unreal Engine MCP instances โ bridge between AI agents and UE across the full development lifecycle.
Works with RemoteMCP (UE Editor plugin that exposes engine capabilities via MCP protocol). The Hub manages everything around it: install the plugin, compile, launch the editor, detect crashes, and transparently proxy all tool calls โ so the AI agent only needs one MCP endpoint.
AI Agent โโโบ UnrealMCPHub โโโบ UE Editor + RemoteMCP plugin
(this repo) (blackplume233/UnrealRemoteMCP)
RemoteMCP runs inside UE Editor and provides 17+ tools across 6 domains (level, blueprint, umg, edgraph, behaviortree, slate). UnrealMCPHub runs outside UE Editor and can compile, launch, monitor, and proxy โ even when UE is not running.
Features
- Project setup โ Configure
.uprojectonce; engine auto-detected from registry - Build & launch โ Compile via UBT, launch editor, wait for MCP readiness
- Plugin install โ One-click RemoteMCP installation (local copy or GitHub download)
- Instance discovery โ Scan ports to find running UE editors
- UE tool proxy โ
ue_run_python,ue_call,ue_list_toolsand domain dispatch - Crash resilience โ Crash detection, report retrieval, restart flow
- Multi-instance โ Switch between multiple UE editors via
use_editor - Session notes โ Persist context for crash recovery
- One-click overview โ
hub_statusshows project, plugin, instances, and watcher state
Quick Install
Option A: One-line install from PyPI (recommended)
# uv (recommended)
uv tool install unrealhub
# or pip
pip install unrealhub
Then add to .cursor/mcp.json:
{
"mcpServers": {
"unrealhub": {
"command": "unrealhub",
"args": ["serve"]
}
}
}
Option B: Zero-install (auto-fetch on first launch)
No download, no clone, no install. Paste this single block into .cursor/mcp.json and restart Cursor:
{
"mcpServers": {
"unrealhub": {
"command": "uvx",
"args": ["unrealhub", "serve"]
}
}
}
Requires uv (
pip install uvorwinget install astral-sh.uv). Cursor will auto-fetch the Hub on first launch.
Option C: Standalone executable (no Python needed)
Download the latest executable for your platform from GitHub Releases, then:
{
"mcpServers": {
"unrealhub": {
"command": "/path/to/unrealhub",
"args": ["serve"]
}
}
}
| Platform | File |
|---|---|
| Windows x64 | unrealhub-windows-amd64.exe |
| macOS ARM | unrealhub-macos-arm64 |
| Linux x64 | unrealhub-linux-amd64 |
Option D: Clone for development
git clone https://github.com/blackplume233/UnrealMCPHub.git
cd UnrealMCPHub
uv sync # or: pip install -e .
{
"mcpServers": {
"unrealhub": {
"command": "uv",
"args": ["--directory", "/path/to/UnrealMCPHub", "run", "unrealhub", "serve"]
}
}
}
Quick Start
For AI Agents (Cursor / Claude / etc.)
This is the primary use case. Add UnrealMCPHub as an MCP server in your AI tool, then the agent handles everything through natural language.
Step 1: Install & Configure MCP (see Quick Install above)
HTTP mode (for shared / remote / multi-client use):
unrealhub serve --http --port 9422
{
"mcpServers": {
"unrealhub": {
"url": "http://127.0.0.1:9422/mcp"
}
}
}
Step 2: Talk to the agent
Once configured, the AI agent has full access to all Hub tools. Example conversations:
You: "ๅธฎๆ็ผ่ฏๅนถๅฏๅจ UE ้กน็ฎ D:/Projects/MyGame/MyGame.uproject"
Agent: [calls setup_project, compile_project, launch_editor automatically]
You: "ๅจ UE ้ๅๅปบไธไธช่ๅพ Actor"
Agent: [calls ue_get_dispatch to find blueprint tools, then ue_call_dispatch]
You: "UE ๅดฉๆบไบๆไนๅ"
Agent: [calls get_crash_report, shows crash info, offers restart_editor]
Step 3: What happens behind the scenes
Agent โ Hub (setup_project) # One-time project config, persisted
Agent โ Hub (compile_project) # Compiles via UBT, even without UE running
Agent โ Hub (launch_editor) # Starts UE, waits for MCP readiness
Agent โ Hub (ue_run_python) # Hub forwards to UE's RemoteMCP
โ
UE Editor (port 8422) # Executes Python, returns result
The agent only needs to know about the Hub โ it never talks to UE directly.
AI Agent Decision Flow
Is project configured?
โโโ No โ Ask user for .uproject path โ setup_project()
โโโ Yes โ Is UE Editor online?
โโโ No โ Need plugin? โ install_plugin() โ compile_project() โ launch_editor()
โโโ Yes โ Use ue_* tools directly
โโโ Crashed? โ get_crash_report() โ restart_editor()
For Humans (CLI)
unrealhub setup /path/to/MyProject.uproject # Configure project
unrealhub serve # Start MCP server (stdio)
unrealhub serve --http --port 9422 # Start MCP server (HTTP)
unrealhub status # Show instance status
unrealhub discover # Discover running UE instances
unrealhub compile # Build active project
unrealhub launch # Launch editor
Tool Reference
Hub Management (always available, even without UE)
| Tool | Description |
|---|---|
setup_project | Configure project path (once, persisted to ~/.unrealhub) |
get_project_config | View current project configuration |
hub_status | One-stop overview of everything |
compile_project | Compile project via UBT |
launch_editor | Start UE Editor, wait for MCP readiness |
restart_editor | Restart a crashed editor |
install_plugin | Install RemoteMCP plugin |
set_plugin_source | Configure plugin download URL or local path |
discover_instances | Scan ports for running UE instances |
use_editor | Switch active UE instance (multi-instance) |
get_crash_report | Get crash details |
add_note / get_notes | Session notes for crash recovery context |
UE Proxy Tools (forwarded to active UE instance)
| Tool | Description |
|---|---|
ue_run_python | Execute Python script in UE |
ue_call | Call any UE MCP tool by name |
ue_list_tools | List all tools from UE instance |
ue_get_dispatch | List domain tools (level, blueprint, umg, etc.) |
ue_call_dispatch | Call a domain-specific tool |
ue_test_state | Test connection to UE |
ue_status | Get active instance status |
Architecture
โโโโโโโโโโโโโโโโโโโ stdio/HTTP โโโโโโโโโโโโโโโโโโโโ
โ Cursor / Agent โ โโโโโโโโโโโโโโโโโโโบ โ UnrealMCPHub โ
โโโโโโโโโโโโโโโโโโโ โ (FastMCP Server) โ
โโโโโโโโโโฌโโโโโโโโโโ
โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโผโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ โ โ
โผ โผ โผ
โโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโ
โ Project Mgmt โ โ Lifecycle โ โ UE Proxy โ
โ setup_project โ โ compile โ โ ue_run_python โ
โ install_pluginโ โ launch/restartโ โ ue_call โ
โ hub_status โ โ discover โ โ ue_list_tools โ
โโโโโโโโโโโโโโโโโ โโโโโโโโโฌโโโโโโโโ โโโโโโโโโฌโโโโโโโโ
โ โ โ
โผ โ Streamable HTTP โ
โโโโโโโโโโโโโโโโโ โโโโโโโโผโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโผโโโโโโโโโ
โ ~/.unrealhub โ โ UE Editor + RemoteMCP (port 8422) โ
โ config.json โ โ 17+ tools: run_python, get_dispatch, etc. โ
โ state.json โ โ 6 domains: level, blueprint, umg, edgraph, โ
โโโโโโโโโโโโโโโโโ โ behaviortree, slate โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
Development
git clone https://github.com/blackplume233/UnrealMCPHub.git
cd UnrealMCPHub
uv sync --extra dev # Install with dev dependencies
uv run pytest tests/ -v # Run tests (129 tests)
Requirements
- Python >= 3.11
- Unreal Engine 5.x
- RemoteMCP โ UE Editor plugin (Hub can auto-install it via
install_plugin)
License
MIT
