unreal-mcp

unreal-mcp

使用 Unreal Python Remote Execution 的 Unreal Engine MCP 服务

Twitter · Discord

⚡ 区别

此服务使用内置的 Python 远程执行协议，因此无需安装新的 UE 插件。

添加新工具/功能的开发速度更快，因为无需编写任何 C++ 代码。

它可以支持完整的 Unreal Engine Python API

⚠️ 注意

• 这不是官方的 Unreal Engine 项目。
• 你的 AI Agent 或工具将拥有对编辑器的完全访问权限。
• 请先检查客户端建议的所有更改，再予以批准。

📦 安装

📋 要求

• 🔧 Unreal Engine 5.4+（已验证，早期版本可能也能使用）
• 🟢 Node.js 和 npx
• 🤖 MCP 客户端（Claude、Cursor 等）

1. 设置编辑器：
   • 打开你的 Unreal Engine 项目
   • 前往 Edit -> Plugins
   • 搜索 "Python Editor Script Plugin" 并启用
   • 如有提示，请重启编辑器
   • 前往 Edit -> Project Settings
   • 搜索 "Python" 并启用 "Enable Remote Execution" 选项

2. 设置客户端：
   • 编辑你的 Claude（或 Cursor）配置

{
  "mcpServers": {
    "unreal": {
      "command": "npx",
      "args": [
        "-y",
        "@runreal/unreal-mcp"
      ]
    }
  }
}

🔧 故障排除

如果你遇到类似 MCP Unreal: Unexpected token 'C', Connection... 的错误，说明 mcp-server 无法连接到 Unreal Editor。

• 确保已启用 Python Editor Script Plugin，并且已在项目设置中勾选 Remote Execution 选项。
• 也可以尝试将绑定地址从 127.0.0.1 改为 0.0.0.0，但请注意，这将允许来自本地网络的连接。
• 完全重启 Unreal Editor。
• 完全关闭并重新打开客户端（Claude、Cursor 等），确保它重新连接到 MCP 服务。（在 Windows 上选择 File -> Exit。）
• 检查正在运行的进程，并结束所有僵尸 unreal-mcp Node.js 进程。

🛠️ 可用工具

工具	描述
set_unreal_engine_path	设置 Unreal Engine 路径
set_unreal_project_path	设置项目路径
get_unreal_engine_path	获取当前 Unreal Engine 路径
get_unreal_project_path	获取当前 Unreal 项目路径
editor_run_python	在 Unreal Editor 中执行任意 Python 代码
editor_list_assets	列出所有 Unreal 资源
editor_export_asset	将 Unreal 资源导出为文本
editor_get_asset_info	获取资源信息，包括 StaticMesh 和 SkeletalMesh 资源的 LOD 级别
editor_get_asset_references	获取资源的引用
editor_console_command	在 Unreal 中运行控制台命令
editor_project_info	获取当前项目的详细信息
editor_get_map_info	获取当前地图/关卡的详细信息
editor_search_assets	按名称或路径搜索资源，可选按类筛选
editor_get_world_outliner	获取当前世界中的所有 Actor 及其属性
editor_validate_assets	验证项目中的资源并检查错误
editor_create_object	在世界中创建新对象/Actor
editor_update_object	更新世界中现有的对象/Actor
editor_delete_object	删除世界中的对象/Actor
editor_take_screenshot	截取 Unreal Editor 的屏幕截图
editor_move_camera	将视口摄像机移动到指定位置和旋转角度，以便调整屏幕截图的取景位置

🤝 参与贡献

欢迎提交问题或拉取请求。欢迎贡献，尤其是新增工具/命令。

许可证 MIT