Unreal Engine MCP Python Bridge Plugin

Unreal Engine MCP Python Bridge Plugin

这是一个适用于 Unreal Engine（UE）的插件，用于创建 Model Context Protocol（MCP） 服务端实现。 这使 MCP 客户端（例如 Anthropic 的 Claude）能够访问完整的 UE Python API。

使用场景

• 使用 Python 与 Claude 这样的 Agent 开发工具和工作流。
• 对这类工作流进行智能、动态的自动化。
• 与 Agent 进行一般性的协作开发。

前提条件

• 系统 PATH 中有 Python 3.10 或更高版本，并已安装官方的 MCP Python SDK：

  pip install mcp
  

  这是唯一的 Python 依赖项。客户端脚本 unreal_mcp_client.py 使用 from mcp.server.fastmcp import FastMCP 向 Agent 提供桥接工具。为方便起见，项目提供了 MCPClient/requirements.txt 文件（pip install -r MCPClient/requirements.txt）。注意：这里使用的是你的系统 Python——该脚本作为 Agent 的子进程运行，而不是在编辑器附带的 Python 中运行。

• 一个 AI Agent。下文假设使用 Claude，但任何实现了 MCP 的 AI Agent 都可以。

• 已启用 Python Editor Script Plugin 的 Unreal Engine 5。

• Visual Studio 2019 或更高版本（仅在从源代码构建插件时需要——通过 Fab 安装则不需要）。

• 请留意 Unreal Engine Python API。

从 Fab 安装

安装 MCP Python Bridge 插件最简单的方式是通过 Fab 商店页面。购买插件后，它会显示在 Epic Games Launcher 的“Library”中。点击“Install to Engine”，然后选择相应版本的 Unreal Engine。

从 GitHub 安装

1. 创建一个新的 Unreal Engine C++ 项目。
2. 在项目根目录下找到 Plugins 文件夹。
3. 将此仓库克隆到 Plugins 文件夹中，使其下方新增一个包含所有项目内容的文件夹。
4. 右键点击 UE 项目文件（扩展名为 .uproject），然后选择“Generate Visual Studio project files”。如果没有立即看到该选项，请先选择“Show more options”，此时应该会显示该选项。
5. 打开新生成的 Visual Studio 项目并进行构建。
6. 将 unreal_mcp_client.py 从“MCPClient”文件夹复制到任意位置。
7. 找到 claude_desktop_config.json 配置文件。 Mac 路径：~/Library/Application\ Support/Claude/claude_desktop_config.json Windows 路径：[path_to_your_user_account]\AppData\Roaming\Claude\claude_desktop_config.json
8. 将 unreal-engine 服务端部分添加到配置文件中，并按下方所示更新路径位置（不包含方括号）。 Mac 路径格式：/[path_from_step_4]/unreal_mcp_client.py Windows 路径格式：C:\\[path_from_step_4]\\unreal_mcp_client.py

{
  "mcpServers": {
    "unreal-engine": {
      "command": "python",
      "args": [
        "[mac_or_windows_format_path_to_unreal_mcp_client.py]"
      ]
    } 
  }
}

9. 启动 Unreal Engine 并加载新项目。
10. 启用新的 UnrealMCPBridge 插件，然后重启。
11. 将鼠标悬停时，工具栏上应会出现一个标有“Start MCP Bridge”的新按钮。
12. 点击 MCP Bridge 按钮。弹出窗口会显示“MCP Python bridge running.”。输出日志会提示新的套接字服务端正在监听 127.0.0.1:9000。
13. 以管理员身份启动 Claude。
14. 点击插头图标“Attach from MCP”。在“Choose an integration”下方有两个测试提示词：create_castle 和 create_town。你可以在插件 Content 文件夹下的 unreal_server_init.py 中编辑它们的实现。每次修改后请务必重启 Unreal Engine。
15. 你也可以让 Claude 使用 UE Python API 在项目中构建内容。
16. 点击插头图标左侧的锤子图标，即可查看当前已实现的工具列表。

开发新工具和提示词

查看 unreal_mcp_client.py，你会看到 MCP 如何使用函数上方的 Python 装饰器定义工具和提示词。示例如下：

@mcp.tool()
def get_project_dir() -> str:
    """Get the top level project directory"""
    result = send_command("get_project_dir")
    if result.get("status") == "success":
        response = result.get("result")
        return response
    else:
        return json.dumps(result)

此命令会将 get_project_dir 命令发送到 Unreal Engine 执行，并返回当前项目的项目目录。在插件的 Content 文件夹下，你可以找到此工具命令的服务端实现：

@staticmethod
def get_project_dir():
    """Get the top level project directory"""
    try:
        project_dir = unreal.Paths.project_dir()
        return json.dumps({
            "status": "success",
            "result" : f"{project_dir}"
        })
    except Exception as e:
        return json.dumps({ "status": "error", "message": str(e) })

按照此模式创建新工具，这些工具会显示在 Claude 桌面界面的锤子图标下。

添加新提示词只需将其添加到 unreal_mcp_client.py 中。以下是 unreal_mcp_client.py 中的 create_castle 提示词示例：

@mcp.prompt()
def create_castle() -> str:
    """Create a castle"""
    return f"""
Please create a castle in the current Unreal Engine project.
0. Refer to the Unreal Engine Python API when creating new python code: https://dev.epicgames.com/documentation/en-us/unreal-engine/python-api/?application_version=5.5
1. Clear all the StaticMeshActors in the scene.
2. Get the project directory and the content directory.
3. Find basic shapes to use for building structures.
4. Create a castle using these basic shapes.
"""

请确保保留三重引号，以便返回完整提示词。创建提示词时，一个不错的迭代方式是让 Claude 逐步执行每个步骤，直到结果令人满意。然后，如示例所示，将所有步骤组合成编号的分步提示词。

必须重启 Claude，unreal_mcp_client.py 中的更改才会生效。请注意，在 Windows 上，你可能需要在任务管理器中结束 Claude 进程，才能彻底重启 Claude。