使用说明

虚幻MCP桥接器

🎮 表示电子游戏或玩电子游戏的符号 基于AI的虚幻引擎开发桥梁 - 基于MCP的开发工具，用于连接Claude Code和Unreal Engine

📋 项目概述

Unreal MCP Bridge使得AI开发工具（Claude Code）与Unreal Engine 5.6之间能够实现顺畅通信 模型上下文协议（MCP） 这是基础桥接系统。通过这个项目，AI可以直接在Unreal编辑器中生成和操作蓝图节点。

🎯 核心功能

🤖 原生AI蓝图创建AI直接生成蓝图节点
🔗 实时通信Claude Code ↔ MCP 服务器 ↔ Unreal 插件实时通信
🛡️ 类型安全集成基于FastMCP的安全类型检查
⚡ 简单即最佳以最小的复杂性实现最大的效果

🏗️ 系统架构

graph TB
    subgraph "AI Development Environment"
        CC[Claude Code]
        AI[AI Assistant]
    end

    subgraph "MCP Bridge Layer"
        MCP[MCP Server<br/>FastMCP + Python]
        HTTP[HTTP Client<br/>aiohttp]
    end

    subgraph "Unreal Engine Environment"
        UE[Unreal Editor 5.6]
        PLUGIN[UnrealMCP Plugin<br/>C++ + Blueprint API]
        BP[Blueprint Assets]
    end

    CC -->|MCP Protocol| MCP
    AI -->|Tool Calls| MCP
    MCP -->|HTTP POST| HTTP
    HTTP -->|localhost:8080| PLUGIN
    PLUGIN -->|Blueprint API| BP
    PLUGIN -->|Response| HTTP
    HTTP -->|JSON Response| MCP
    MCP -->|MCP Response| CC

    style CC fill:#e1f5fe
    style MCP fill:#f3e5f5
    style PLUGIN fill:#e8f5e8
    style BP fill:#fff3e0

🔄 数据流序列

sequenceDiagram
    participant AI as AI Assistant
    participant CC as Claude Code
    participant MCP as MCP Server
    participant HTTP as HTTP Client
    participant UE as Unreal Plugin
    participant BP as Blueprint System

    AI->>CC: "Create PrintString node in /Game/MyBP"
    CC->>MCP: MCP Tool Call: add_blueprint_node()
    MCP->>HTTP: HTTP POST localhost:8080/add_node
    HTTP->>UE: JSON: {"blueprint_path": "/Game/MyBP", "node_type": "PrintString"}
    UE->>BP: Blueprint Asset Creation/Modification
    BP-->>UE: Blueprint Updated Successfully
    UE-->>HTTP: HTTP 200: {"success": true, "node_id": "..."}
    HTTP-->>MCP: aiohttp Response
    MCP-->>CC: MCP Success Response
    CC-->>AI: "✅ PrintString node added successfully"

🗂️ 文件夹结构

unreal_mcp\
├── 📁 mcp_server\                             # MCP 서버 (Python)
│   └── 📄 main.py                             # FastMCP 기반 서버 구현
├── 📁 unreal_plugin\                          # 언리얼 플러그인 소스
│   └── 📁 UnrealMCP\                          # 플러그인 루트
│       ├── 📄 UnrealMCP.uplugin               # 플러그인 메타데이터
│       └── 📁 Source\UnrealMCP\               # C++ 소스 코드
│           ├── 📁 Public\                     # 헤더 파일
│           │   ├── 📄 IUnrealMCP.h            # 모듈 인터페이스
│           │   ├── 📄 MCPBlueprintLibrary.h   # Blueprint 함수 라이브러리
│           │   ├── 📄 UnrealMCPSettings.h     # 플러그인 설정
│           │   └── 📄 UnrealMCPEditorSubsystem.h # 에디터 서브시스템
│           └── 📁 Private\                    # 구현 파일
│               ├── 📄 UnrealMCP.cpp           # 모듈 구현
│               ├── 📄 MCPBlueprintLibrary.cpp # Blueprint 함수 구현
│               ├── 📄 MCPHttpServer.cpp       # HTTP 서버 구현
│               └── 📄 UnrealMCPEditorSubsystem.cpp # 서브시스템 구현
├── 📄 .mcp.json                               # Claude Code MCP 설정
└── 📄 README.md                               # 이 파일

📦 安装指南

1️⃣ 预先要求

虚幻引擎5.6 （安装路径： Program Files\Epic Games\UE_5.6)
Visual Studio 2022 企业版 (C++ 开发环境)
Python 3.10+ （用于MCP服务器）
克劳德·科德 （AI开发工具）

2️⃣ 设置Python虚拟环境

# 프로젝트 디렉토리로 이동
cd unreal_mcp

# 가상환경 생성 (이미 존재함)
python -m venv mcp_server_env

# 가상환경 활성화
mcp_server_env\Scripts\activate

# 의존성 설치
pip install fastmcp>=0.5.0 aiohttp>=3.8.0

3️⃣ 安装Unreal插件

# 플러그인 폴더를 언리얼 프로젝트에 복사
# 소스: unreal_mcp\unreal_plugin\UnrealMCP
# 대상: [언리얼 프로젝트]\Plugins\UnrealMCP

# 예시 (PowerShell):
Copy-Item -Path "unreal_mcp\unreal_plugin\UnrealMCP" -Destination "[YourUnrealProject]\Plugins\" -Recurse

# 예시 (Command Prompt):
robocopy "unreal_mcp\unreal_plugin\UnrealMCP" "[YourUnrealProject]\Plugins\UnrealMCP" /E

4️⃣ Unreal插件构建

# 프로젝트 빌드 (Live Coding 비활성화 필요)
"D:\Program Files\Epic Games\UE_5.6\Engine\Build\BatchFiles\Build.bat" [YourProject]Editor Win64 Development -Project="[YourUnrealProject]\[YourProject].uproject" -WaitMutex

5️⃣ MCP客户端设置

🔧 Claude Code 设置

.mcp.json 确认文件是否正确设置：

{
  "mcpServers": {
    "unreal_mcp": {
      "command": "mcp_server_env\\Scripts\\python.exe",
      "args": ["mcp_server\\main.py"],
      "env": {}
    }
  }
}

🖥️ Claude Desktop 设置

您也可以在Claude Desktop中使用此MCP服务器：

设置文件位置：

Windows: %APPDATA%\Claude\claude_desktop_config.json
macOS（苹果电脑操作系统）： ~/Library/Application Support/Claude/claude_desktop_config.json

claude_desktop_config.json 配置：

{
  "mcpServers": {
    "unreal_mcp": {
      "command": "D:\\_Source\\unreal_mcp\\mcp_server_env\\Scripts\\python.exe",
      "args": ["D:\\_Source\\unreal_mcp\\mcp_server\\main.py"],
      "cwd": "D:\\_Source\\unreal_mcp"
    }
  }
}

注意事项：

在Claude Desktop中 绝对路径必须使用
cwd 建议明确设置（工作目录）
设置后需重启Claude Desktop以加载MCP服务器

🤖 设置Gemini CLI

在Gemini CLI中也可以使用此MCP服务器：

设置文件: settings.json

Gemini CLI settings.json 设置：

{
  "mcpServers": {
    "unreal_mcp": {
      "command": "D:\\_Source\\unreal_mcp\\mcp_server_env\\Scripts\\python.exe",
      "args": ["D:\\_Source\\unreal_mcp\\mcp_server\\main.py"],
      "timeout": 15000,
      "trust": false
    }
  }
}

Gemini CLI 使用方法：

# MCP 도구 사용 예시
gemini "Create a PrintString node in /Game/TestBP using the unreal_mcp tool"

# 또는 -y 플래그로 자동 승인
gemini -y "Add a blueprint node to my Unreal project"

Gemini CLI 配置选项：

timeout请求超时（毫秒）
trust设置为true则跳过工具调用确认
includeTools仅允许特定工具（可选）
excludeTools排除特定工具（可选）

🚀 使用方法

0️⃣ 直接运行MCP服务器（可选）

MCP服务器由AI工具自动运行，但也可以为了调试或测试而直接运行：

# 가상환경 활성화
mcp_server_env\Scripts\activate

# MCP 서버 직접 실행
python mcp_server/main.py

# 또는 절대 경로로 실행
D:\_Source\unreal_mcp\mcp_server_env\Scripts\python.exe D:\_Source\unreal_mcp\mcp_server\main.py

MCP服务器状态检查：

# 서버가 올바르게 시작되었는지 확인
curl http://localhost:8080/status

# 또는 PowerShell에서
Invoke-RestMethod -Uri "http://localhost:8080/status"

1️⃣ 运行Unreal编辑器

# 언리얼 에디터 실행 (플러그인 자동 로드)
"D:\Program Files\Epic Games\UE_5.6\Engine\Binaries\Win64\UnrealEditor.exe" "[YourUnrealProject]\[YourProject].uproject"

2️⃣ 在Claude Code中与AI互动

在Claude Code中，向AI发出如下请求：

AI: "Create a PrintString node in the blueprint located at /Game/TestBP"

AI会自动调用MCP工具，在Unreal编辑器中生成蓝图节点。

3️⃣ 支持的AI命令

创建蓝图节点： "Add a [NodeType] node to [BlueprintPath]"
连接测试： "Test the MCP connection to Unreal Engine"
检查服务器状态: "Check if the Unreal MCP server is running"

🔧 各组件的作用

🤖 人工智能工具 (AI Tools)

🔧 克劳德代码

角色AI助手与用户之间的开发环境集成接口
功能通过MCP协议的工具调用管理、代码编辑集成
通信基于JSON-RPC的MCP协议
特点针对开发环境的工作流

🖥️ Claude 桌面版

角色桌面AI助手应用程序
功能与MCP服务器的直接集成，用户友好的界面
通信MCP协议（基于绝对路径）
特点独立桌面应用程序，重启后加载MCP

🤖 Gemini 命令行界面 (CLI)

角色基于命令行的AI助手工具
功能可在终端直接调用MCP工具，实现脚本集成
通信MCP协议（基于settings.json）
特点自动批准模式(-y)，支持工具过滤

🐍 MCP 服务器（Python + FastMCP）

角色将AI工具调用转换为HTTP请求的桥梁
功能：
- add_blueprint_node() 提供工具
- 通过aiohttp的异步HTTP客户端
- 错误处理及超时管理
通信:
- 输入：MCP 协议（STDIO）
- 输出：HTTP POST → localhost:8080

🎮 Unreal 插件（C++ + HTTP 服务器）

角色在虚幻引擎中实际执行蓝图操作
核心组件：
- MCPHttpServer（可译为）：MCP网络服务器HTTP服务器（localhost:8080)
- MCP蓝图库Blueprint API 封装器
- **UnrealMCPEditorSubsystem（可译为“虚幻MCPEditor子系统”）**编辑综合管理
功能：
- /add_node 通过端点创建蓝图节点
- 通过UE5.6蓝图API进行实际资产操作
- 实时服务器状态监控

🔍 技术栈

层级	技术	版本	角色
人工智能接口	Claude Code	最新	人工智能开发工具
协议	MCP（模型上下文协议）	1.0	AI工具通信协议
MCP框架	FastMCP	最新版本	Python MCP 服务器框架
HTTP 客户端	aiohttp	3.8+	异步HTTP通信
游戏引擎	Unreal Engine	5.6	游戏开发平台
插件语言	C++	17	Unreal插件开发
HTTP服务器	UE5 HTTP模块	内置	虚幻内置HTTP服务器

🌐 HTTP API 端点

Unreal 插件的 HTTP 服务器 localhost:8080提供以下REST API端点：

📋 终端点列表

🔧 POST /add_node（添加节点）

在蓝图中创建一个新的节点。

请求格式：

POST http://localhost:8080/add_node
Content-Type: application/json

{
  "blueprint_path": "/Game/MyBlueprint",
  "node_type": "PrintString"
}

回答格式：

{
  "success": true,
  "message": "Blueprint created with PrintString node at '/Game/MyBlueprint'",
  "blueprint_path": "/Game/MyBlueprint",
  "node_type": "PrintString"
}

参数：

blueprint_path (字符串)：要创建的蓝图的路径（例如：“/Game/TestBP”）
node_type (string): 要创建的节点类型（目前仅支持"PrintString"）

响应代码：

200 OK成功处理
400 Bad Request错误的JSON格式或参数

📊 GET /status（中文翻译：获取/状态）

检查服务器状态。

请求格式：

GET http://localhost:8080/status

回答格式：

{
  "server_running": true,
  "port": 8080,
  "status": "UnrealMCP server is running",
  "version": "1.0"
}

响应代码：

200 OK服务器正在正常运行

🧪 API测试示例

使用cURL进行测试：

# 서버 상태 확인
curl http://localhost:8080/status

# 블루프린트 노드 생성
curl -X POST http://localhost:8080/add_node \
  -H "Content-Type: application/json" \
  -d '{"blueprint_path": "/Game/TestBP", "node_type": "PrintString"}'

使用PowerShell进行测试：

# 서버 상태 확인
Invoke-RestMethod -Uri "http://localhost:8080/status"

# 블루프린트 노드 생성
$body = @{
    blueprint_path = "/Game/TestBP"
    node_type = "PrintString"
} | ConvertTo-Json

Invoke-RestMethod -Uri "http://localhost:8080/add_node" -Method POST -Body $body -ContentType "application/json"

⚠️ 当前限制事项

支持节点类型目前 PrintString仅支持
编辑专用蓝图生成仅在编辑器构建中起作用
端口固定目前固定使用8080端口（未来计划扩展以支持设置）

🎯 开发哲学：“简单即最好”

这个项目 “简约即最佳” 严格遵守原则：

✅ 实现的简洁性原则

实现最小功能仅支持创建PrintString节点（可扩展结构）
使用标准模式遵循UE5官方开发规范
清晰的界面各层级间简单明了的API
单一职责每个组件只执行一个明确的角色

📊 复杂性指标

MCP 服务器用84行Python代码实现完整功能
HTTP服务器使用125行函数生成蓝图（合理的复杂性）
蓝图库三个函数提供所有必要功能
整体评价9.5/10（近乎完美的实现了“简单即最好”的理念）

🛠️ 开发与调试

查看日志

# 언리얼 에디터 로그와 함께 실행
"D:\Program Files\Epic Games\UE_5.6\Engine\Binaries\Win64\UnrealEditor.exe" "[YourUnrealProject]\[YourProject].uproject" -log

连接测试

来自Claude Code：

"Test MCP connection to check if everything is working"

一般问题解决

连接失败确认Unreal编辑器是否正在运行
端口冲突检查8080端口是否可用
插件加载失败项目构建后重新启动编辑器

🚀 可扩展性

目前的实现是 可扩展的架构提供：

新的节点类型： MCPHttpServer::CreateBlueprintWithPrintString() 函数扩展
额外的终端节点在HTTP服务器上添加新的REST API
复杂的蓝图逻辑节点连接、变量设置等高级功能
其他非虚幻系统整合了关卡编辑器、材质编辑器等

📄 许可证

这个项目是为开发和学习目的而制作的。

🎮 用心打造，助力AI驱动的游戏开发

“简单即美”——在复杂中寻找简洁的旅程