chongdashu/unreal-mcp

GitHub: chongdashu/unreal-mcp

通过 Model Context Protocol 让 Claude、Cursor 等 AI 助手用自然语言控制 Unreal Engine，实现场景搭建、Blueprint 创建等编辑器操作的自动化。

Stars: 1468 | Forks: 221

# Unreal Engine 的 Model Context Protocol unreal-mcp [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT) [![Unreal Engine](https://img.shields.io/badge/Unreal%20Engine-5.5%2B-orange)](https://www.unrealengine.com) [![Python](https://img.shields.io/badge/Python-3.12%2B-yellow)](https://www.python.org) [![Status](https://img.shields.io/badge/Status-Experimental-red)](https://github.com/chongdashu/unreal-mcp)

本项目使得 Cursor、Windsurf 和 Claude Desktop 等 AI 助手客户端能够通过 Model Context Protocol (MCP) 使用自然语言控制 Unreal Engine。 ## ⚠️ 实验性状态本项目目前处于**实验性**状态。API、功能和实现细节可能会发生重大变化。虽然我们鼓励测试和反馈，但请注意： - 可能会发生破坏性变更，恕不另行通知 - 功能可能不完整或不稳定 - 文档可能过时或缺失 - 目前不建议用于生产环境 ## 🌟 概述 Unreal MCP 集成提供了通过自然语言控制 Unreal Engine 的全面工具： | 类别 | 功能 | |----------|-------------| | **Actor 管理** | • 创建和删除 Actor（立方体、球体、灯光、相机等）
• 设置 Actor 变换（位置、旋转、缩放）
• 查询 Actor 属性并按名称查找 Actor
• 列出当前关卡中的所有 Actor | | **Blueprint 开发** | • 创建带有自定义组件的新 Blueprint 类
• 添加和配置组件（网格、相机、灯光等）
• 设置组件属性和物理设置
• 编译 Blueprint 并生成 Blueprint Actor
• 为玩家控制创建输入映射 | | **Blueprint 节点图** | • 添加事件节点（BeginPlay、Tick 等）
• 创建函数调用节点并连接它们
• 添加具有自定义类型和默认值的变量
• 创建组件和自身引用
• 在图中查找和管理节点 | | **编辑器控制** | • 聚焦视口于特定 Actor 或位置
• 控制视口相机方向和距离 | 所有这些功能都可以通过 AI 助手使用自然语言命令访问，从而轻松实现 Unreal Engine 工作流程的自动化和控制。 ## 🧩 组件 ### 示例项目 `MCPGameProject` - 基于空白项目，但添加了 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、编辑器和 Blueprint 操作的工具模块 - **scripts/** - 示例脚本和演示 - **Docs/** - 综合文档 - 有关文档索引，请参阅 [Docs/README.md](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 设置说明，请参阅 [Python/README.md](Python/README.md)，包括： - 设置您的 Python 环境 - 运行 MCP 服务器 - 使用直接或基于服务器的连接 ### 配置您的 MCP 客户端根据您的 MCP 客户端，使用以下 JSON 进行 MCP 配置。 ``` { "mcpServers": { "unrealMCP": { "command": "uv", "args": [ "--directory", "", "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](https://www.x.com/chongdashu)

标签：3D建模, AIGC, AI编程, Blueprint, Claude Desktop, Cursor, MCP, Python, SOC Prime, UE5, Unreal Engine, Windsurf, 元宇宙, 开发工具, 数字孪生, 无后门, 模型上下文协议, 游戏开发, 编辑器扩展, 网络调试, 自动化, 自然语言控制, 蓝图, 虚拟引擎, 逆向工具