本项目使像 Cursor、Windsurf 和 Claude Desktop 这样的 AI 助手客户端能够通过自然语言，利用模型上下文协议（MCP）来控制虚幻引擎。

⚠️ 实验性状态

该项目目前处于 实验性 状态。API、功能及实现细节可能会发生重大变化。尽管我们鼓励大家进行测试并提供反馈，但请注意以下几点：

• 可能会在未事先通知的情况下出现破坏性变更。
• 某些功能可能尚未完善或不稳定。
• 文档可能过时或缺失。
• 目前不建议用于生产环境。

🌟 概述

虚幻 MCP 集成提供了通过自然语言控制虚幻引擎的全面工具：

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

所有这些功能都可以通过 AI 助手的自然语言命令来访问，从而轻松实现虚幻引擎工作流程的自动化与控制。

🧩 组件

示例项目（MCPGameProject）MCPGameProject

• 基于空白项目，但添加了 UnrealMCP 插件。

插件（UnrealMCP）MCPGameProject/Plugins/UnrealMCP

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

Python MCP 服务器 Python/unreal_mcp_server.py

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

📂 目录结构

• MCPGameProject/ - 虚幻引擎示例项目。

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

• Python/ - Python 服务器及工具。

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

• Docs/ - 全面的文档。

  • 请参阅 Docs/README.md 获取文档索引。

🚀 快速入门指南

先决条件

• 虚幻引擎 5.5+
• Python 3.12+
• MCP 客户端（例如：Claude Desktop、Cursor、Windsurf）

示例项目

为了快速上手，您可以使用 MCPGameProject 中的启动项目。这是一个已配置好 UnrealMCP.uplugin 的 UE 5.5 空白启动项目。

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

插件

如果您希望在现有项目中使用该插件：

1. 将插件复制到您的项目

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

2. 启用插件

   • 打开 编辑 > 插件。
   • 在“编辑器”类别中找到 “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

unreal-mcp 快速上手指南

unreal-mcp 是一个基于 Model Context Protocol (MCP) 的开源项目，允许 AI 助手（如 Cursor、Windsurf、Claude Desktop）通过自然语言直接控制 Unreal Engine 编辑器。你可以用它来创建 Actor、编写蓝图逻辑或调整场景属性。

⚠️ 注意：本项目目前处于 实验性 (Experimental) 阶段。API 和功能可能会发生重大变更，不建议用于生产环境。

1. 环境准备

在开始之前，请确保你的开发环境满足以下要求：

• Unreal Engine: 版本 5.5 或更高 (必须)。
• Python: 版本 3.12 或更高。
• MCP 客户端: 已安装并配置好任意一款支持的 AI 编辑器，例如：
  • Cursor
  • Windsurf
  • Claude Desktop
• 构建工具: Visual Studio (Windows) 或 Xcode (Mac)，用于编译 C++ 插件。

2. 安装步骤

第一步：部署 Unreal 插件

你可以选择使用示例项目或直接集成到现有项目中。

选项 A：使用示例项目 (推荐新手) 项目自带了一个配置好的空白项目 MCPGameProject。

1. 克隆或下载本仓库。
2. 右键点击 MCPGameProject/MCPGameProject.uproject。
3. 选择 Generate Visual Studio project files。
4. 打开生成的 .sln 文件，将配置设置为 Development Editor，然后执行 Build 以编译插件。

选项 B：集成到现有项目

1. 将仓库中的 MCPGameProject/Plugins/UnrealMCP 文件夹复制到你的项目根目录下的 Plugins 文件夹中。
2. 启动 Unreal Editor，进入 Edit > Plugins。
3. 在 "Editor" 分类下找到 UnrealMCP 并勾选启用。
4. 根据提示重启编辑器。
5. 右键点击你的 .uproject 文件，生成工程文件并重新编译项目。

第二步：设置 Python 服务端

Python 服务端负责在 MCP 客户端和 Unreal 引擎之间建立 TCP 连接。

1. 进入 Python 目录。
2. 建议创建虚拟环境并安装依赖（具体依赖请参考 Python/requirements.txt 或使用 uv 管理）：

   cd Python
   # 如果使用 uv (推荐)
   uv venv
   uv pip install -r requirements.txt
   

   (注：如果国内下载慢，可临时指定清华源：uv pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple)

第三步：配置 MCP 客户端

你需要告诉 AI 编辑器如何启动 unreal-mcp 服务。根据你的客户端类型，编辑对应的配置文件。

通用配置内容 (mcp.json)： 请将 <path/to/the/folder/PYTHON> 替换为你实际的 Python 文件夹绝对路径。

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

配置文件位置：

客户端	配置文件路径
Cursor	项目根目录下的 .cursor/mcp.json
Claude Desktop	macOS: ~/.config/claude-desktop/mcp.json Windows: %USERPROFILE%\.config\claude-desktop\mcp.json
Windsurf	macOS: ~/.config/windsurf/mcp.json Windows: %USERPROFILE%\.config\windsurf\mcp.json

配置完成后，重启你的 AI 编辑器。

3. 基本使用

完成上述步骤后，确保同时满足以下条件即可开始使用：

1. Unreal Editor 已打开并加载了包含 UnrealMCP 插件的项目。
2. AI 编辑器 (如 Cursor) 已重新启动以加载 MCP 配置。

使用示例：

在 AI 聊天窗口中，直接使用自然语言下达指令。AI 将自动调用工具操作引擎。

• 创建物体：

  "在场景原点创建一个红色的立方体。" (Create a red cube at the origin.)

• 调整属性：

  "把刚才创建的立方体移动到 (100, 0, 100)，并将旋转角度设为 45 度。" (Move the cube to 100, 0, 100 and rotate it by 45 degrees.)

• 蓝图操作：

  "创建一个新的 Blueprint 类，添加一个 StaticMesh 组件，并在 BeginPlay 事件中打印 'Hello World'。" (Create a new Blueprint class with a StaticMesh component and print 'Hello World' on BeginPlay.)

• 场景查询：

  "列出当前关卡中所有的灯光 Actor。" (List all light actors in the current level.)

现在，你可以通过对话高效地自动化 Unreal Engine 的开发流程了。