UnrealEngine Bridge

不真实的发动机桥

让克劳德代码完全控制虚幻引擎5.7。 生成演员、调整材质、捕捉视口、关键帧动画——所有这些都是通过自然语言通过 模型上下文协议.

51个MCP工具| 12个工具模块| 372个测试| Python 3.11+

______________________________________________________________________

运作原理

graph LR
    subgraph Claude Code
        A[MCP Client]
    end

    subgraph Python
        B[MCP Server
FastMCP · stdio]
        B --> C[Tool Modules
12 modules · 51 tools]
        C --> D[Remote Control Bridge
httpx · circuit breaker]
    end

    subgraph Unreal Engine 5.7
        E[Remote Control API
localhost:30010]
        E --> F[Editor Runtime]
        G[ViewportPerception
localhost:30011]
        G --> F
    end

    A -- stdio --> B
    D -- HTTP --> E
    C -. viewport capture .-> G

    style A fill:#6C47FF,color:#fff
    style B fill:#1a1a2e,color:#fff
    style C fill:#1a1a2e,color:#fff
    style D fill:#1a1a2e,color:#fff
    style E fill:#0d47a1,color:#fff
    style F fill:#0d47a1,color:#fff
    style G fill:#0d47a1,color:#fff

______________________________________________________________________

快速开始

先决条件

1.克隆和安装

git clone https://github.com/JosephOIbrahim/UnrealEngine_Bridge.git
cd UnrealEngine_Bridge
pip install -e .

2.打开UE5项目

1. 打开 UnrealEngine_Bridge.uproject 虚幻引擎5.7
2. 验证 远程控制API 插件已启用（编辑>插件）
3. 确认 localhost:30010 可访问（检查输出日志中的“远程控制Web服务器已启动”）

3.连接克劳德代码

将此添加到您的Claude Code MCP配置中(~/.claude/settings.json 或项目 .mcp.json):

{
  "mcpServers": {
    "unreal": {
      "command": "python",
      "args": ["-m", "ue_mcp.mcp_server"],
      "cwd": "/path/to/UnrealEngine_Bridge"
    }
  }
}

4.开始建设

打开克劳德代码并尝试：

*在原点生成一个立方体，使其变红，并将其旋转45度*

克劳德将使用 ue_spawn_actor, ue_create_material, ue_assign_material，以及 ue_set_transform 自动。

______________________________________________________________________

MCP工具参考

演员（6个工具）

场景理解（4个工具）

材料（4个工具）

蓝图（7个工具）

序列器和动画（4个工具）

感知（4种工具）

级别（4个工具）

资产（3个工具）

运动图形（3个工具）

编辑器实用程序（5个工具）

属性（2个工具）

Python执行（1个工具）

______________________________________________________________________

建筑

graph TB
    subgraph "Python Layer"
        MCP["MCP Server
ue_mcp/mcp_server.py"]
        Tools["Tool Modules (12)
ue_mcp/tools/"]
        RC["Remote Control Bridge
remote_control/"]
        Val["Validation & Sandbox
_validation.py"]
        Met["Metrics & Circuit Breaker
metrics.py"]
        Log["JSON Logger
logging.py"]
    end

    subgraph "File Bridge Layer"
        Orch["Bridge Orchestrator
bridge_orchestrator.py"]
        USD["USD Bridge
usd_bridge/"]
        FS[("~/.translators/
bridge_state.usda
heartbeat.json")]
    end

    subgraph "C++ Plugins (UE5)"
        Sub["UEBridgeSubsystem
State machine · polling"]
        Ed["BridgeEditorSubsystem
File watching · process mgmt"]
        VP["ViewportPerception
GPU readback · ring buffer"]
        RCAPI["Remote Control API
REST · port 30010"]
    end

    MCP --> Tools
    Tools --> Val
    Tools --> RC
    RC --> Met
    MCP --> Log
    RC -- "HTTP" --> RCAPI
    RCAPI --> Sub
    Orch --> USD
    USD --> FS
    FS --> Sub
    Sub --> Ed
    VP -- "HTTP :30011" --> Tools

    style MCP fill:#6C47FF,color:#fff
    style Tools fill:#6C47FF,color:#fff
    style RCAPI fill:#0d47a1,color:#fff
    style Sub fill:#0d47a1,color:#fff
    style VP fill:#0d47a1,color:#fff

韧性

安全

在UE5中执行的所有Python代码都通过多层沙箱进行验证：

• 模块堵塞: os, sys, subprocess, shutil, socket, pickle, importlib，以及20+以上
• 堵塞的建筑: exec, eval, open, getattr, globals, __import__
• 已阻止的属性: system, popen, rmtree, kill，再加上危险的扣篮
• 路径验证：内容路径遍历(..)预防所有输入
• 控制台安全：已阻止的命令(exit, quit, crash)防止换行

______________________________________________________________________

项目结构

UnrealEngine_Bridge/
├── ue_mcp/                        # MCP server package
│   ├── mcp_server.py              # FastMCP entry point (stdio)
│   ├── metrics.py                 # Telemetry + observability
│   ├── logging.py                 # Structured JSON logging
│   └── tools/                     # 12 tool modules (51 tools)
│       ├── actors.py              # Spawn, delete, list, transform
│       ├── scene.py               # Query, details, hierarchy
│       ├── materials.py           # Create, set params, assign
│       ├── blueprints.py          # Create, compile, components
│       ├── sequencer.py           # Animation / Level Sequence
│       ├── perception.py          # Viewport capture + diff
│       ├── editor.py              # Console, undo/redo, focus
│       ├── level.py               # Save, load, world info
│       ├── assets.py              # Find, create, delete
│       ├── mograph.py             # Cloner, Niagara, PCG
│       ├── properties.py          # Get/set UObject properties
│       ├── python_exec.py         # Sandboxed Python execution
│       ├── _validation.py         # Input sanitization + AST sandbox
│       ├── _codegen.py            # Shared code generation snippets
│       ├── _console_parsers.py    # Structured stat output parsers
│       └── _types.py              # Protocol types
│
├── remote_control/                # UE5 HTTP bridge package
│   ├── circuit_breaker.py         # CLOSED/OPEN/HALF_OPEN state machine
│   ├── async_client.py            # AsyncUnrealRemoteControl (MCP)
│   ├── sync_client.py             # UnrealRemoteControl (standalone)
│   ├── codegen.py                 # UE5 Python script generation
│   ├── execution.py               # File-based result polling
│   └── constants.py               # URLs, timeouts, pool config
│
├── usd_bridge/                    # USD file I/O package
│   ├── io.py                      # Atomic writes, locking, paths
│   ├── question.py                # Question read/write
│   ├── transition.py              # State transitions, finales
│   ├── signals.py                 # Behavioral signal extraction
│   ├── profile.py                 # Cognitive profiling + checksums
│   └── validation.py              # Bridge state validation
│
├── Plugins/
│   ├── UEBridge/                  # Core bridge C++ plugin
│   │   ├── UEBridgeRuntime/       # Subsystem, types, UI, style
│   │   └── UEBridgeEditor/        # File watching, process management
│   └── ViewportPerception/        # GPU readback, ring buffer, HTTP endpoint
│
├── bridge_orchestrator.py         # Game flow orchestration
├── remote_control_bridge.py       # Backward-compat shim → remote_control/
├── usd_bridge.py                  # Backward-compat shim → usd_bridge/
├── tests/                         # 372 tests (pytest)
├── pyproject.toml                 # Build config, dependencies, tooling
└── .github/workflows/ci.yml       # CI: Python 3.11/3.12, coverage, lint

______________________________________________________________________

发展

运行测试

pip install -e ".[dev]"
python -m pytest tests/ -v

有保障地跑步

python -m pytest tests/ --cov=ue_mcp --cov=remote_control --cov-report=term-missing

代码检查

pip install ruff
ruff check ue_mcp/ remote_control/ tests/

添加新工具

1. 创建 ue_mcp/tools/your_module.py
2. 定义a register(server: MCPServer, ue: UEBridge) -> None 功能
3. 使用 @server.tool() 室内装饰师 register()
4. 使用来自的消毒剂验证输入 _validation.py
5. 注册于 ue_mcp/tools/__init__.py
6. 在中添加测试 tests/

______________________________________________________________________

许可证

版权所有2026约瑟夫·易卜拉欣。保留所有权利。