MCP 服务器

Model Context Protocol for Unreal Engine

使像 Cursor、Windsurf 和 Claude Desktop 这样的 AI 助手客户端能够使用模型上下文协议 (MCP) 通过自然语言控制 Unreal Engine。

chongdashu

开发者工具

访问服务器

README

Unreal Engine 的模型上下文协议

<span style="color: #555555">unreal-mcp</span>

</div>

该项目使 AI 助手客户端（如 Cursor、Windsurf 和 Claude Desktop）能够使用模型上下文协议 (MCP) 通过自然语言控制 Unreal Engine。

⚠️ 实验状态

该项目目前处于实验性状态。API、功能和实现细节可能会发生重大变化。虽然我们鼓励测试和反馈，但请注意：

可能会在没有通知的情况下发生重大更改
功能可能不完整或不稳定
文档可能已过时或缺失
目前不建议用于生产环境

🌟 概述

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

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

所有这些功能都可以通过 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 库来实现模型上下文协议

📂 目录结构

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。

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

插件

否则，如果您想在现有项目中使用该插件：

将插件复制到您的项目
- 将 MCPGameProject/Plugins/UnrealMCP 复制到您项目的 Plugins 文件夹
启用插件
- 编辑 > 插件
- 在 Editor 类别中找到 "UnrealMCP"
- 启用插件
- 出现提示时重新启动编辑器
构建插件
- 右键单击您的 .uproject 文件
- 生成 Visual Studio 项目文件
- 打开解决方案 (.sln)
- 使用您的目标平台和输出设置进行构建

Python 服务器设置

有关详细的 Python 设置说明，请参见 Python/README.md，包括：

设置您的 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`