使用说明

项目简介

Unreal MCP Server 是一个基于 Model Context Protocol (MCP) 的服务器实现，旨在让AI助手（如Cursor, Windsurf, Claude Desktop）能够通过自然语言指令控制和自动化Unreal Engine编辑器。该项目通过C++插件和Python服务器协同工作，为AI客户端提供资源管理、工具执行和Prompt模板渲染等核心MCP功能，从而实现更智能、更高效的Unreal Engine工作流程。

主要功能点

资源管理: 虽然文档中没有明确提及资源管理，但通过Actor和Blueprint的管理可以推断出具备基础的资源管理能力。
工具注册和执行: 通过C++插件和Python工具模块，实现了Actor、Editor和Blueprint等多种工具的注册和执行，允许AI助手调用Unreal Engine的各种功能。
Prompt模板渲染: 虽然仓库中没有显式的Prompt模板定义和渲染功能，但提供了 'unreal_best_practices' Prompt，可以作为一种硬编码的Prompt示例，暗示了未来支持Prompt模板的可能性。
会话管理: 服务器端负责监听和处理客户端请求，通过TCP协议保持连接并响应JSON-RPC格式的命令。
能力声明: 通过工具注册和'unreal_best_practices' Prompt，服务器向客户端声明了自身的功能和使用方法。
多种传输协议: 当前版本使用TCP Socket进行通信，为后续扩展到SSE或WebSocket等协议奠定了基础。
安全性: 框架设计上，MCP协议本身考虑了安全性，但具体实现中的安全性措施需要进一步评估。
可扩展性: 通过模块化的工具设计和Python/C++架构，服务器具备良好的功能扩展性。

安装步骤

环境准备:
- 确保已安装 Unreal Engine 5.5或更高版本。
- 确保已安装 Python 3.12或更高版本。
插件安装 (现有项目):
- 如果您已有Unreal Engine项目，请将仓库中的 'MCPGameProject/Plugins/UnrealMCP' 文件夹复制到您项目的 'Plugins' 目录下。
- 启动Unreal Editor，在 "编辑(Edit)" -> "插件(Plugins)" 菜单中找到 "Editor" 类别下的 "UnrealMCP" 插件，启用它并重启编辑器。
- 右键点击您的 '.uproject' 文件，选择 "Generate Visual Studio project files" 生成Visual Studio项目文件。
- 打开生成的 '.sln' 解决方案文件，选择 "Development Editor" 配置，编译项目以构建插件。
项目配置 (新项目或示例项目):
- 您可以直接使用仓库提供的示例项目 'MCPGameProject'。这是一个预配置了 'UnrealMCP' 插件的空白项目。
- 如果使用示例项目，同样需要生成Visual Studio项目文件并编译。
Python服务器设置:
- 导航到仓库的 'Python' 目录。
- 确保您的Python环境已安装所需依赖（虽然仓库中没有明确指出依赖，但通常需要FastMCP库，可以通过 'pip install fastmcp' 安装，如果需要）。
- 运行 'unreal_mcp_server.py' 脚本以启动Python MCP服务器。服务器默认监听 '127.0.0.1:55557' 端口。

服务器配置

MCP 服务器的配置信息用于MCP客户端连接到Unreal MCP Server。以下是一个典型的 'mcp.json' 配置文件示例，您需要根据您的MCP客户端放置到指定的配置路径下。

{
  "mcpServers": {
    "unrealMCP": {
      "command": "uv",
      "args": [
        "--directory",
        "<path/to/the/folder/PYTHON>", // 将此处替换为Python服务器脚本所在Python目录的绝对路径，例如 "D:/GitHub/unreal-mcp/Python" 或 "/home/user/unreal-mcp/Python"
        "run",
        "unreal_mcp_server.py" // Python服务器脚本名称
      ]
    }
  }
}

配置参数说明:

'mcpServers': 定义可用的MCP服务器列表。
'unrealMCP': 为该Unreal MCP Server 定义一个名称，客户端使用此名称来引用服务器。您可以自定义名称。
'command': 指定启动服务器的命令。这里 'uv' 假设您的环境中安装了 'uv' 这个Python虚拟环境和包管理器，您也可以直接使用 'python' 或 'python3'，取决于您的Python环境配置。
'args': 启动命令的参数列表。
- '--directory': 指定Python脚本所在的目录，MCP客户端会切换到这个目录再执行命令。请务必将 '<path/to/the/folder/PYTHON>' 替换为Python服务器脚本所在目录的绝对路径。
- 'run': 'uv' 或 'python' 命令的子命令，表示运行后面的脚本。
- 'unreal_mcp_server.py': 要运行的Python服务器脚本的名称。

MCP客户端配置路径示例:

| MCP 客户端 | 配置文件路径 | |-----------------|------------------------------------------------------| | Claude Desktop | '~/.config/claude-desktop/mcp.json' (macOS/Linux) 或 '%USERPROFILE%.config\claude-desktop\mcp.json' (Windows) | | Cursor | '.cursor/mcp.json' (项目根目录) | | Windsurf | '~/.config/windsurf/mcp.json' (macOS/Linux) 或 '%USERPROFILE%.config\windsurf\mcp.json' (Windows) |

基本使用方法

确保Unreal Editor已打开您的项目，并且UnrealMCP插件已启用。
启动Python MCP服务器 'unreal_mcp_server.py'。
配置您的MCP客户端（如Cursor, Claude Desktop, Windsurf），将上面提供的 'mcp.json' 配置添加到客户端指定的配置文件路径中。
在MCP客户端中，您应该能够连接到名为 'unrealMCP' 的服务器。
使用自然语言指令，通过AI助手控制Unreal Engine，例如创建Actor、修改Blueprint等。您可以参考 'Python/scripts' 目录下的测试脚本，了解可用的命令和参数。
您也可以参考 'Python/tools/actor_tools.py', 'Python/tools/blueprint_tools.py', 'Python/tools/editor_tools.py', 'Python/tools/node_tools.py' 等文件，了解服务器支持的具体工具和功能。

关键词