Unrealclaude MCP Bridge

UE5 MCP服务器

一个MCP（模型上下文协议）服务器，将AI助手连接到虚幻引擎5的编辑器，可以直接操纵关卡、演员、蓝图和动画蓝图。

为什么要使用独立存储库？

此MCP服务器最初是 不合理的赞美 插件，但已移至其自己的存储库，原因如下：

1. 扩大的范围MCP协议是一个开放标准，现在得到了许多人工智能提供商的支持
2. 更容易分叉：开发人员可以分叉并调整此桥以适应其他AI服务，而无需拉取整个虚幻插件
3. 社区贡献：独立仓库使接受新功能的PR、错误修复和对其他MCP客户端的支持变得更加容易

兼容的AI客户端

此服务器使用标准 模型上下文协议 并与 任何兼容MCP的AI客户端，包括：

• 克劳德代码 （CLI）
• Claude桌面应用程序
• OpenAI ChatGPT桌面 （MCP支持于2025年3月添加）
• 光标 （AI驱动的IDE）
• 回复 （AI编码平台）
• 源代码图科迪
• 帆板运动
• 以及任何其他符合MCP的工具

协议是 捐赠给Linux基金会 2025年12月，人工智能行业将继续广泛采用该技术。

______________________________________________________________________

重要提示：此工具是什么（不是什么）

这不是一个“文本到游戏”的工具。 它不会生成3D模型、纹理、动画，也不会取代艺术家、动画师和资产创建者的工作。

这是一个工作流加速器 虚幻引擎开发者。它有助于：

• 项目设置单调：快速构建蓝图、设置状态机、配置输入绑定
• 重复的编辑器任务：生成演员、设置属性、使用自然语言组织关卡
• 快速原型制作：通过描述你想要的东西而不是点击菜单来更快地测试想法
• 学习UE5：工作时查询内置API文档

我们的目标是加快游戏开发中乏味的部分，这样你就可以专注于真正重要的创造性工作。

______________________________________________________________________

需求

• Node.js 18.0.0或更高
• 实现预期REST API的HTTP端点（默认值： http://localhost:3000)

备注：此MCP服务器旨在与 不合理的克劳德插件，但是可以适用于实现相同API的其他HTTP后端。

快速开始

1.安装

git clone https://github.com/Natfii/unrealclaude-mcp-bridge.git
cd unrealclaude-mcp-bridge
npm install

2.配置您的MCP客户端

添加到MCP客户端的配置中：

克劳德代码 (~/.claude/settings.json):

{
  "mcpServers": {
    "unreal": {
      "command": "node",
      "args": ["/path/to/unrealclaude-mcp-bridge/index.js"],
      "env": {
        "UNREAL_MCP_URL": "http://localhost:3000"
      }
    }
  }
}

克劳德桌面版 (claude_desktop_config.json):

{
  "mcpServers": {
    "unreal": {
      "command": "node",
      "args": ["/path/to/unrealclaude-mcp-bridge/index.js"],
      "env": {
        "UNREAL_MCP_URL": "http://localhost:3000"
      }
    }
  }
}

其他MCP客户端：有关MCP服务器配置，请参阅客户的文档。服务器使用stdio传输。

3.使用它

连接后，您可以通过自然语言与虚幻编辑器进行交互：

"Spawn a point light at position 0, 0, 500"
"List all StaticMeshActors in the level"
"Create a new Actor Blueprint called BP_Enemy"
"Add a float variable called Health to BP_Player"
"Create a state machine called Locomotion in my Animation Blueprint"

______________________________________________________________________

可用工具

连接和上下文

关卡和演员工具

资产工具

脚本执行

视口

蓝图工具

动画蓝图工具

角色工具

材料工具

增强的输入工具

异步任务队列

______________________________________________________________________

动画蓝图操作

这 unreal_anim_blueprint_modify 该工具提供了对动画蓝图的全面控制：

状态机操作

过渡操作

过渡条件图

节点/引脚自检

动画作业

批量操作

______________________________________________________________________

UE 5.7上下文系统

服务器包含内置的UE 5.7 API文档，可以查询：

可选类别

用法

// Get specific category
{ "category": "animation" }

// Search by keywords
{ "query": "state machine transitions" }

// List all categories
{}

自动上下文注入

通过设置启用自动上下文注入：

{
  "env": {
    "INJECT_CONTEXT": "true"
  }
}

______________________________________________________________________

配置

______________________________________________________________________

故障排除

工具显示“未连接”

• 确保您的HTTP后端正在运行且可访问
• 验证 UNREAL_MCP_URL 环境变量指向正确的端点
• 检查端点是否响应 /mcp/status

stdin/stdout错误

• 确保Node.js 18+已安装并位于PATH中
• 跑 npm install 确保存在依赖关系
• 验证MCP客户端配置中的路径指向正确的 index.js

运行测试套件

此仓库包含一个Vitest测试套件（87个测试），可以在不运行虚幻编辑器的情况下验证网桥行为：

npm install
npm test              # run all tests
npm run test:watch    # watch mode
npm run test:coverage # with coverage report

测试模拟虚幻HTTP服务器，涵盖模式转换、HTTP客户端逻辑、上下文加载、工具列表和调用路由。

______________________________________________________________________

贡献

欢迎投稿！请随意：

• 添加对其他MCP客户端配置的支持
• 改进UE5上下文文档
• 修复错误或添加新功能
• 提交文件改进

______________________________________________________________________

许可证

麻省理工学院与归因-见 许可证 了解详情。

需要归因：如果您使用此项目，请注明：

• 项目：UE5 MCP服务器
• 作者：纳塔利·卡吉亚诺（Natfii）
• 链接：https://github.com/Natfii/unrealclaude-mcp-bridge

需要披露：如果您使用此代码构建另一个MCP服务器或AI集成，请在您的文档中披露其使用方法。

______________________________________________________________________

相关

• 不合理的克劳德插件 -为该MCP服务器提供HTTP后端的虚幻引擎插件
• 模型上下文协议 -协议规范
• -官方MCP存储库和SDK