Unreal MCP Hub

虚幻MCPHub

虚幻引擎MCP实例的中央管理平台——在整个开发生命周期中连接AI代理和UE的桥梁。

适用于 远程MCP （通过MCP协议公开引擎功能的UE编辑器插件）。Hub管理周围的一切：安装插件、编译、启动编辑器、检测崩溃，并透明地代理所有工具调用——因此AI代理只需要一个MCP端点。

AI Agent ──► UnrealMCPHub ──► UE Editor + RemoteMCP plugin
              (this repo)       (blackplume233/UnrealRemoteMCP)

远程MCP 跑 里面 UE编辑器，提供6个领域（关卡、蓝图、umg、边缘图、行为树、板岩）的17多种工具。 虚幻MCPHub 跑 外面 UE编辑器，可以编译、启动、监视和代理——即使UE没有运行。

特性

• 项目设置 --配置 .uproject 一次；从注册表中自动检测到引擎
• 构建和发布 --通过UBT编译，启动编辑器，等待MCP准备就绪
• 插件安装 --一键安装RemoteMCP（本地副本或GitHub下载）
• 实例发现 --扫描端口以查找正在运行的UE编辑器
• UE工具代理 — ue_run_python, ue_call, ue_list_tools 以及域调度
• 碰撞弹性 --碰撞检测、报告检索、重启流程
• 多实例 --通过以下方式在多个UE编辑器之间切换 use_editor
• 会议记录 --为崩溃恢复保留上下文
• 一键概览 — hub_status 显示项目、插件、实例和观察者状态

快速安装

选项A：从PyPI进行一行安装（推荐）

# uv (recommended)
uv tool install unrealhub

# or pip
pip install unrealhub

然后添加到 .cursor/mcp.json:

{
  "mcpServers": {
    "unrealhub": {
      "command": "unrealhub",
      "args": ["serve"]
    }
  }
}

选项B：零安装（首次启动时自动获取）

不下载，不克隆，不安装。将此单个块粘贴到 .cursor/mcp.json 并重新启动Cursor：

{
  "mcpServers": {
    "unrealhub": {
      "command": "uvx",
      "args": ["unrealhub", "serve"]
    }
  }
}

需要 紫外线 (pip install uv 或 winget install astral-sh.uv).Cursor将在首次启动时自动获取Hub。

选项C：独立可执行文件（不需要Python）

从下载适用于您平台的最新可执行文件 那么：

{
  "mcpServers": {
    "unrealhub": {
      "command": "/path/to/unrealhub",
      "args": ["serve"]
    }
  }
}

选项D：克隆用于开发

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"]
    }
  }
}

快速开始

适用于AI代理（光标/克劳德等）

这是主要用例。在您的AI工具中添加UnrealMCPHub作为MCP服务器，然后代理通过自然语言处理一切。

步骤1：安装和配置MCP （参见 快速安装 以上）

HTTP模式 （用于共享/远程/多客户端使用）：

unrealhub serve --http --port 9422

{
  "mcpServers": {
    "unrealhub": {
      "url": "http://127.0.0.1:9422/mcp"
    }
  }
}

第二步：与代理人交谈

配置后，AI代理可以完全访问所有Hub工具。对话示例：

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]

第三步：幕后发生了什么

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

代理只需要知道Hub——它从不直接与UE对话。

AI代理决策流程

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()

面向人类（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

工具参考

集线器管理（即使没有UE，也始终可用）

UE代理工具（转发到活动UE实例）

建筑

┌─────────────────┐     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               │
                                        └──────────────────────────────────────────────┘

发展

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)

需求

• Python>=3.11
• 虚幻引擎5.x
• 远程MCP --UE编辑器插件（Hub可以通过以下方式自动安装 install_plugin)

许可证

麻省理工学院