unrealhub 0.1.0

UnrealMCPHub - Central management platform for Unreal Engine MCP instances

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 .uproject once; 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_tools and 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_status shows 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 uv or winget 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