🔍 Unreal MCP 开源项目全面测评

1. 模型概述

Unreal MCP Server 是一个中间件服务，它在 AI 助手（如 Claude、Cursor）与 Unreal Engine 编辑器之间建立了一座桥梁5。其核心是利用了 Unreal Engine 内置的 Python 远程执行功能，无需安装额外的插件即可实现对编辑器的控制。

1.1 模型能力与工作范围

Unreal MCP 的核心能力是让 AI 助手或外部工具能够通过协议与 Unreal Engine 交互，将自然语言指令转换为具体的编辑器操作。它主要能完成以下几类工作：

• 资产管理系统操作：包括列出、搜索、导出、验证项目中的各种资产，以及获取资产信息（如静态网格体和骨骼网格体资产的 LOD 级别）和引用关系。

• 场景编辑与对象管理：获取当前世界中所有 Actor 及其属性，创建、更新或删除世界中的对象/Actor。

• Python 脚本远程执行：直接在 Unreal Editor 中执行 Python 代码，无需编译或重启编辑器，支持文件执行、语句执行和表达式求值等多种模式。

• 编辑器控制与信息获取：运行控制台命令，获取当前项目和地图/关卡的详细信息，控制编辑器视口相机的位置和旋转以定位截图，以及截取编辑器截图。

• 信息查询：对于扩展功能，例如通过专门的 MCP 服务器进行虚幻引擎官方文档的智能搜索（结合关键词和语义搜索）或概念关系图谱查询。

1.2 主要技术特点

Unreal MCP 展现了以下几个显著的技术特点：

• 无需额外 UE 插件：其一大优势在于利用了 Unreal Engine 内置的 Python 远程执行协议，无需在 UE 中安装新的专用插件即可工作。

• 开发效率高：所有功能均通过 Python 实现，无需编写 C++ 代码，这使得添加新工具或功能的开发速度更快。

• 完整的 Unreal Python API 支持：能够支持完整的 Unreal Engine Python API，提供了强大的操控能力。

• 配置简单：只需在 UE 中启用内置 Python 插件并配置 AI 客户端，几分钟内即可开始使用5。

1.3 应用场景

Unreal MCP 适用于多种需要 AI 辅助或自动化 Unreal 项目开发的场景5：

• 快速原型制作：通过自然语言命令快速创建基础几何体、布置场景、应用材质，加速想法的验证5。

• 自动化测试：编写脚本自动化执行重复性测试任务，例如场景加载测试、资产完整性验证或性能分析。

• 批量处理任务：批量重命名资产、批量导出导入资产、批量修改资产属性或批量执行光照构建等5。

• AI 辅助内容生成：结合生成式 AI，根据文本描述生成或修改材质、蓝图脚本，甚至辅助设计场景布局。

• 项目分析与报告：自动获取项目中的资产列表、场景结构、引用关系等信息，生成项目报告或进行数据分析。

• 学习与探索：开发者或学习者可以通过自然语言询问引擎的功能、概念关系7或查询官方文档，快速了解 Unreal Engine。

2. 安装与部署方式

以下是 Unreal MCP 的详细安装与部署流程。

2.1 环境准备

在开始之前，请确保你的系统满足以下要求：

• Unreal Engine：5.4 或更高版本已验证支持。理论上 5.0+ 版本也可能工作，但推荐使用 5.4+ 以获得最佳兼容性5。

• Python：确保你的系统安装了 Python（通常 UE 内置的 Python 环境即可，但可能需要配置系统环境变量）。

• MCP 客户端：你需要一个支持 MCP 的客户端，如 Claude Desktop App 或 Cursor IDE。

2.2 在 Unreal Engine 中的配置

这一步在所有操作系统上都是通用的。

1. 启用 Python 插件：

   • 打开你的 Unreal Engine 项目。

   • 转到菜单栏的 编辑 (Edit) -> 插件 (Plugins)。

   • 在插件管理器的搜索框中搜索 “Python Editor Script Plugin“。

   • 找到后，勾选其旁边的复选框以启用它。

   • 如果系统提示，重启 Unreal Editor。

2. 启用远程执行：

   • 在 Unreal Editor 中，转到 编辑 (Edit) -> 项目设置 (Project Settings)。

   • 在项目设置的搜索框中搜索 “Python“。

   • 找到 “Enable Remote Execution” 选项并勾选它。

   • 确保 “Enable Editor Python API” 也已启用（通常默认就是启用的）。

2.3 客户端配置（以 Claude Desktop 为例）

不同操作系统的配置方式主要在配置文件的路径和命令语法上略有差异。

Windows 系统

1. 定位配置文件：
   Claude Desktop 的配置文件通常位于：
   %APPDATA%\Claude\claude_desktop_config.json
   你可以在文件资源管理器的地址栏直接输入此路径，或使用文本编辑器打开。

2. 编辑配置文件：
   在 claude_desktop_config.json 文件中，添加或修改 mcp 部分以指向 Unreal MCP 服务器。请注意，根据搜索结果，存在两种略有不同的配置方式，对应不同的 Unreal MCP 实现或版本：

   • 方式一（推荐先尝试）：指向一个特定的批处理文件。

   json

   {
     "mcp": {
       "command": "C:\\YourProject\\Plugins\\UnrealMCP\\MCP\\run_unreal_mcp.bat"
     }
   }

   • 方式二：直接使用 Python 命令运行服务器脚本。

   json

   {
     "mcpServers": {
       "unreal-handshake": {
         "command": "python",
         "args": [
           "<your_project_directory_path>/Plugins/GenerativeAISupport/Content/Python/mcp_server.py"
         ],
         "env": {
           "UNREAL_HOST": "localhost",
           "UNREAL_PORT": "9877"
         }
       }
     }
   }

   你需要根据你所获取的 Unreal MCP 项目文件的实际路径和结构来选择并修改配置。请将 C:\\YourProject\\ 或 <your_project_directory_path> 替换为你自己的 Unreal 项目绝对路径。

3. 重启客户端：
   保存配置文件后，完全关闭并重新启动 Claude Desktop 应用（在 Windows 上为 文件 -> 退出）。

macOS 系统

1. 定位配置文件：
   macOS 上 Claude Desktop 的配置文件通常位于：
   ~/Library/Application Support/Claude/claude_desktop_config.json
   你可以使用 Terminal 或 Finder（前往文件夹功能）访问此路径。

2. 编辑配置文件：
   配置内容与 Windows 类似，但需要注意文件路径的写法（使用正斜杠 /）。

   json

   {
     "mcp": {
       "command": "/Users/YourUsername/YourUnrealProject/Plugins/UnrealMCP/MCP/run_unreal_mcp.sh"
     }
   }

   或者

   json

   {
     "mcpServers": {
       "unreal-handshake": {
         "command": "python3",
         "args": [
           "/Users/YourUsername/YourUnrealProject/Plugins/GenerativeAISupport/Content/Python/mcp_server.py"
         ],
         "env": {
           "UNREAL_HOST": "localhost",
           "UNREAL_PORT": "9877"
         }
       }
     }
   }

   确保你有可执行的 .sh 脚本文件，或者直接使用 python 命令。

3. 重启客户端：
   完全退出并重新打开 Claude Desktop。

Linux 系统

1. 定位配置文件：
   Linux 上 Claude Desktop 的配置文件通常位于：
   ~/.config/Claude/claude_desktop_config.json

2. 编辑配置文件：
   配置内容与 macOS 类似，确保路径正确。

   json

   {
     "mcp": {
       "command": "/home/YourUsername/YourUnrealProject/Plugins/UnrealMCP/MCP/run_unreal_mcp.sh"
     }
   }

3. 重启客户端：
   完全退出并重新打开 Claude Desktop。

2.4 安装中常见问题与修复方案

3. 配套客户端

Unreal MCP 需要与支持 MCP 协议的客户端配合使用才能发挥作用。

以下是其主要支持的客户端：

4. 案例讲解：批量重命名项目中的材质资产

假设你的项目中有一系列前缀为 Old_ 的材质（如 Old_Red_Brick, Old_Grass），你想使用 Unreal MCP 通过 Claude 将它们批量重命名为 M_ 前缀（如 M_Red_Brick, M_Grass）。

4.1 模拟操作流程

1. 对话发起：

   • 你（对 Claude）：”帮我把项目中所有以 ‘Old_’ 开头的材质资产重命名，去掉 ‘Old_’ 并加上 ‘M_’ 前缀。”

2. Claude 与 MCP 交互：

   • Claude 通过 MCP 协议向 Unreal MCP Server 发送指令。

   • MCP Server 接收指令，将其转换为一系列 Unreal Python API 调用。

3. 执行过程：

   • 列出资产：首先，MCP Server 会执行一个 Python 脚本来搜索所有以 “Old_” 开头的材质资产。

   • 分析并生成新名称：对找到的每个资产，计算其新名称（例如，Old_Red_Brick -> M_Red_Brick）。

   • 执行重命名：调用 Unreal Engine 的资产重命名 API 来应用更改。

4.2 可执行的 Python 代码示例

Unreal MCP Server 在背后执行的 Python 代码逻辑类似于下面这样（这是一个简化的示例，展示了核心逻辑）：

# 假设这段代码是由 MCP Server 生成并在 Unreal Engine Python 环境中执行的

import unreal

def rename_old_materials():
    # 获取资产注册中心
    asset_registry = unreal.AssetRegistryHelpers.get_asset_registry()
    
    # 创建一个过滤器来查找所有材质资产
    material_filter = unreal.ARFilter(
        class_names=["Material"], # 指定材质类
        package_names=["/Game"]   # 指定搜索范围，例如 /Game 目录
    )
    
    # 应用过滤器并获取所有材质资产
    all_materials = asset_registry.get_assets(material_filter)
    
    # 遍历所有材质
    for asset_data in all_materials:
        asset_name = asset_data.asset_name
        current_path = asset_data.package_name
        
        # 检查资产名是否以 "Old_" 开头
        if asset_name.startswith("Old_"):
            # 计算新名称：去掉 "Old_", 加上 "M_"
            new_name = "M_" + asset_name[4:] # 去掉前4个字符 ("Old_")
            
            # 获取当前的包路径（不含资产名）
            package_path = str(current_path).rpartition('.')[0]
            
            # 构建新的完整包路径
            new_package_path = package_path + "/" + new_name
            
            # 打印信息（可选，便于调试）
            print(f"Renaming {asset_name} to {new_name}")
            
            # 执行重命名操作
            # 注意：重命名操作需要加载资产
            try:
                # 加载资产
                asset = unreal.load_asset(str(current_path))
                # 执行重命名
                unreal.EditorAssetLibrary.rename_asset(
                    str(current_path), 
                    new_package_path
                )
                print(f"Successfully renamed {asset_name} to {new_name}")
            except Exception as e:
                print(f"Failed to rename {asset_name}: {str(e)}")
    
    print("Batch rename operation completed.")

# 调用函数
rename_old_materials()

重要提示：

• 这段代码是一个概念示例，实际 MCP Server 生成的代码可能会更复杂，包含更多错误处理和日志记录。

• 在执行任何批量操作（尤其是重命名、删除）之前，务必确保你的项目已经提交到版本控制系统（如 Git、SVN、Perforce）或者有完整的备份。错误的脚本可能导致资产引用丢失。

• 你可以尝试在 Unreal Editor 的 Python 控制台中手动运行类似逻辑的简单测试代码，以确保其按预期工作。

5. 使用成本与商业价值

5.1 使用成本评估

5.2 商业价值与使用收益

5.3 综合评估

Unreal MCP 项目是一个具有显著潜力的工具，特别适合那些希望利用 AI 和自动化技术来提升 Unreal Engine 开发效率和体验的个人开发者、独立工作室乃至大型团队。

它的主要优势在于其无需额外插件的特性、与 Unreal Python API 的深度集成以及相对简单的配置过程。其商业价值主要体现在解放开发者生产力、加速开发流程和降低某些任务的技能门槛上。

然而，采用它也需要清醒地认识到其潜在风险，最主要的就是对项目资产的安全性威胁。因此，绝不能在没有版本控制系统备份的情况下在生产项目中盲目使用。它更适合在受控的环境中进行尝试，逐步集成到工作流中。

建议：对于追求效率和新技术的 Unreal Engine 开发者来说，Unreal MCP 绝对值得一试。从小任务开始，逐步验证其稳定性和有效性，并始终将安全放在第一位，这样才能最大化其收益 while minimizing the risks.

关注 “悠AI” 更多干货技巧行业动态