Model Context Protocol for Unreal Engine

本项目可让 Cursor、Windsurf 和 Claude Desktop 等 AI 助手客户端通过 Model Context Protocol（MCP）使用自然语言控制 Unreal Engine。

⚠️ 实验性状态

本项目目前处于实验性状态。API、功能和实现细节都可能发生重大变化。我们鼓励大家进行测试并提供反馈，但请注意：

• 可能会在不另行通知的情况下引入破坏性变更
• 功能可能不完整或不稳定
• 文档可能过时或缺失
• 目前不建议用于生产环境

🌟 概述

Unreal MCP 集成提供了全面的工具，可通过自然语言控制 Unreal Engine：

类别	功能
Actor 管理	• 创建和删除 Actor（立方体、球体、灯光、摄像机等） • 设置 Actor 变换（位置、旋转、缩放） • 查询 Actor 属性并按名称查找 Actor • 列出当前关卡中的所有 Actor
蓝图开发	• 创建带有自定义组件的新蓝图类 • 添加和配置组件（网格体、摄像机、灯光等） • 设置组件属性和物理设置 • 编译蓝图并生成蓝图 Actor • 为玩家控制创建输入映射
蓝图节点图	• 添加事件节点（BeginPlay、Tick 等） • 创建函数调用节点并将其连接起来 • 添加具有自定义类型和默认值的变量 • 创建组件引用和自身引用 • 查找和管理图表中的节点
编辑器控制	• 将视口焦点移至指定 Actor 或位置 • 控制视口摄像机的朝向和距离

所有这些功能都可以通过 AI 助手使用自然语言命令访问，让自动化和控制 Unreal Engine 工作流变得简单。

🧩 组件

示例项目（MCPGameProject）MCPGameProject

• 基于空白项目创建，并添加了 UnrealMCP 插件。

插件（UnrealMCP）MCPGameProject/Plugins/UnrealMCP

• 用于 MCP 通信的原生 TCP 服务
• 与 Unreal Editor 子系统集成
• 实现 Actor 操作工具
• 处理命令执行和响应

Python MCP 服务端 Python/unreal_mcp_server.py

• 在 unreal_mcp_server.py 中实现
• 管理与 C++ 插件的 TCP 套接字连接（端口 55557）
• 处理命令序列化和响应解析
• 提供错误处理和连接管理
• 从 tools 目录加载并注册工具模块
• 使用 FastMCP 库实现 Model Context Protocol

📂 目录结构

• MCPGameProject/ - Unreal 示例项目

  • Plugins/UnrealMCP/ - C++ 插件源代码
    • Source/UnrealMCP/ - 插件源代码
    • UnrealMCP.uplugin - 插件定义

• Python/ - Python 服务端和工具

  • tools/ - 用于 Actor、编辑器和蓝图操作的工具模块
  • scripts/ - 示例脚本和演示

• Docs/ - 完整文档

  • 查看 Docs/README.md 获取文档索引

🚀 快速入门指南

前提条件

• Unreal Engine 5.5+
• Python 3.12+
• MCP 客户端（例如 Claude Desktop、Cursor、Windsurf）

示例项目

如需快速上手，可以使用 MCPGameProject 中的入门项目。这是一个 UE 5.5 空白入门项目，已配置好 UnrealMCP.uplugin。

1. 准备项目
   • 右键单击你的 .uproject 文件
   • 生成 Visual Studio 项目文件
2. 构建项目（包括插件）
   • 打开解决方案（.sln）
   • 选择 Development Editor 作为目标。
   • 构建

插件

如果你想在现有项目中使用该插件：

1. 将插件复制到项目中

   • 将 MCPGameProject/Plugins/UnrealMCP 复制到项目的 Plugins 文件夹

2. 启用插件

   • 编辑 > 插件
   • 在 Editor 类别中找到“UnrealMCP”
   • 启用插件
   • 出现提示时重启编辑器

3. 构建插件

   • 右键单击你的 .uproject 文件
   • 生成 Visual Studio 项目文件
   • 打开解决方案（`.sln)
   • 使用你的目标平台和输出设置进行构建

Python 服务设置

请参阅 Python/README.md，了解详细的 Python 设置说明，包括：

• 设置 Python 环境
• 运行 MCP 服务
• 使用直接连接或基于服务端的连接

配置 MCP 客户端

根据你的 MCP 客户端，使用以下 JSON 进行 MCP 配置。

{
  "mcpServers": {
    "unrealMCP": {
      "command": "uv",
      "args": [
        "--directory",
        "<path/to/the/folder/PYTHON>",
        "run",
        "unreal_mcp_server.py"
      ]
    }
  }
}

示例见 mcp.json

MCP 配置位置

根据你使用的 MCP 客户端，配置文件的位置会有所不同：

MCP 客户端	配置文件位置	备注
Claude Desktop	~/.config/claude-desktop/mcp.json	Windows 系统：%USERPROFILE%\.config\claude-desktop\mcp.json
Cursor	.cursor/mcp.json	位于项目根目录
Windsurf	~/.config/windsurf/mcp.json	Windows 系统：%USERPROFILE%\.config\windsurf\mcp.json

每个客户端使用的 JSON 格式都与上述示例相同。
只需将配置放在 MCP 客户端对应的位置即可。

许可证

MIT

问题

如有疑问，可通过 X/Twitter 联系我： @chongdashu