Unreal MCP

🚀 虚幻引擎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小部件）出于安全考虑将拒绝运行。

插件功能映射

安装

选项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个）

🔧 关键特性

• 优雅降级 - 即使没有与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 文件获取详细信息。