<div align="center">

Unreal Engine 的模型上下文协议

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

</div>

该项目使像Cursor、Windsurf和Claude Desktop这样的AI助手客户端能够通过自然语言使用模型上下文协议（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中的启动项目。这是一个已配置好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