JinDaGe - unreal_mcp MCP Details

article

README

🚀 虚幻引擎MCP服务器

这是一个全面的模型上下文协议（MCP）服务器，它允许AI助手通过远程控制API来控制虚幻引擎。该服务器使用TypeScript构建，专为游戏开发自动化而设计。

🚀 快速开始

前提条件

Node.js 18+
虚幻引擎 5.0 - 5.6
必需的UE插件（通过 编辑 ▸ 插件 启用）：
- 远程控制API – 核心远程控制HTTP/WS端点
- 远程控制Web界面 – 启用此服务器使用的WebSocket桥接
- Python编辑器脚本插件 – 为自动化暴露Python运行时
- 编辑器脚本实用工具 – 解锁工具中使用的编辑器Actor/资产子系统
- Sequencer（内置） – 为电影工具保持启用状态
- 关卡序列编辑器 – manage_sequence 操作必需

💡 使用建议

切换任何插件后，重启编辑器以完成激活。在连接之前，请保持 编辑器脚本实用工具 和 Python编辑器脚本插件 启用，否则许多基于子系统的工具（如Actor生成、音频、植被、UI小部件）出于安全考虑将拒绝运行。

插件功能映射

| 插件 | 位置 | 使用方 | 注意事项 | |------|------|--------|----------| | 远程控制API | 开发者工具 ▸ 远程控制 | 所有工具 | 提供MCP桥接使用的HTTP/WS端点 | | 远程控制Web界面 | 开发者工具 ▸ 远程控制 | 所有工具 | 启用持久的WebSocket会话 | | Python编辑器脚本插件 | 脚本编写 | 地形、灯光、音频、物理、序列、UI | 每个Python执行路径都必需 | | 编辑器脚本实用工具 | 脚本编写 | Actor、植被、资产、地形、UI | 在UE5.6中提供编辑器Actor/资产子系统 | | Sequencer | 内置 | Sequencer工具 | 确保在项目设置中未禁用 | | 关卡序列编辑器 | 动画 | Sequencer工具 | 在调用 manage_sequence 操作之前激活 |

安装

选项1：NPM包（推荐）

# 全局安装
npm install -g unreal-engine-mcp-server

# 或在项目中本地安装
npm install unreal-engine-mcp-server

选项2：克隆并构建

# 克隆仓库
git clone https://github.com/ChiR24/Unreal_mcp.git
cd Unreal_mcp

# 安装依赖并构建
npm install
npm run build

# 直接运行
node dist/cli.js

虚幻引擎配置

将以下内容添加到项目的 Config/DefaultEngine.ini 文件中：

[/Script/PythonScriptPlugin.PythonScriptPluginSettings]
bRemoteExecution=True
bAllowRemotePythonExecution=True

[/Script/RemoteControl.RemoteControlSettings]
bAllowRemoteExecutionOfConsoleCommands=True
bEnableRemoteExecution=True
bAllowPythonExecution=True

然后在：编辑 > 项目设置 > 插件 > 远程控制中启用Python执行。

📦 MCP客户端配置

Claude桌面版 / Cursor

对于NPM安装（本地）

{
  "mcpServers": {
    "unreal-engine": {
      "command": "npx",
      "args": ["unreal-engine-mcp-server"],
      "env": {
        "UE_HOST": "127.0.0.1",
        "UE_RC_HTTP_PORT": "30010",
        "UE_RC_WS_PORT": "30020",
        "UE_PROJECT_PATH": "C:/Users/YourName/Documents/Unreal Projects/YourProject"
      }
    }
  }
}

对于克隆/构建安装

{
  "mcpServers": {
    "unreal-engine": {
      "command": "node",
      "args": ["path/to/Unreal_mcp/dist/cli.js"],
      "env": {
        "UE_HOST": "127.0.0.1",
        "UE_RC_HTTP_PORT": "30010",
        "UE_RC_WS_PORT": "30020",
        "UE_PROJECT_PATH": "C:/Users/YourName/Documents/Unreal Projects/YourProject"
      }
    }
  }
}

✨ 主要特性

核心功能

资产管理 - 浏览、导入和创建材质
Actor控制 - 生成、删除和操作带有物理效果的Actor
编辑器控制 - PIE会话、相机和视口管理
关卡管理 - 加载/保存关卡、灯光和环境构建
动画与物理 - 蓝图、状态机、布娃娃、约束
视觉效果 - Niagara粒子、GPU模拟、程序效果
Sequencer - 电影制作、相机动画和时间轴控制
控制台命令 - 安全执行，过滤危险命令

📄 可用工具（13个）

| 工具 | 描述 | |------|------| | manage_asset | 列出、创建材质，导入资产 | | control_actor | 生成、删除Actor，应用物理效果 | | control_editor | PIE控制、相机、视图模式 | | manage_level | 加载/保存关卡、灯光 | | animation_physics | 动画蓝图、布娃娃 | | create_effect | 粒子、Niagara、调试形状 | | manage_blueprint | 创建蓝图，添加组件 | | build_environment | 地形、地貌、植被 | | system_control | 性能分析、质量、UI、截图、输出日志读取 | | console_command | 直接执行控制台命令 | | manage_rc | 远程控制预设 | | manage_sequence | Sequencer/电影制作 | | inspect | 对象内省 |

🔧 关键特性

优雅降级 - 即使没有与UE连接，服务器也能启动
自动重连 - 每10秒尝试重新连接
连接超时 - 5秒超时，可配置重试次数
非侵入式健康检查 - 每30秒使用回显命令
命令安全 - 阻止危险的控制台命令
输入灵活性 - 向量/旋转器接受对象或数组格式
资产缓存 - 10秒TTL以提高性能

📚 支持的资产类型

蓝图、材质、纹理、静态/骨骼网格体、关卡、声音、粒子、Niagara系统

💻 示例控制台命令

基础用法

统计信息 - stat fps、stat gpu、stat memory
视图模式 - viewmode wireframe、viewmode unlit
游戏玩法 - slomo 0.5、god、fly
渲染 - r.screenpercentage 50、r.vsync 0

📋 配置

环境变量

UE_HOST=127.0.0.1              # 虚幻引擎主机
UE_RC_HTTP_PORT=30010          # 远程控制HTTP端口
UE_RC_WS_PORT=30020            # 远程控制WebSocket端口
UE_PROJECT_PATH="C:/Users/YourName/Documents/Unreal Projects/YourProject"  # .uproject文件的绝对路径
LOG_LEVEL=info                 # debug | info | warn | error

Docker

docker build -t unreal-mcp .
docker run -it --rm unreal-mcp

从Docker Hub拉取

docker pull mcp/server/unreal-engine-mcp-server:latest
docker run --rm -it mcp/server/unreal-engine-mcp-server:latest

🛠️ 开发

npm run build          # 构建TypeScript
npm run lint           # 运行ESLint
npm run lint:fix       # 修复linting问题

🤝 贡献

欢迎贡献代码！请遵循以下规则：

包含重现问题的步骤
保持PR聚焦且规模较小
遵循现有的代码风格

📄 许可证

本项目采用MIT许可证，请参阅 LICENSE 文件获取详细信息。

unreal_mcp