JinDaGe - unrealengine5-mcp MCP Details

article

README

🚀 Unreal Engine MCP

MCP 工具可实现对 Unreal Engine 5.6+ 的自然语言控制。专为大型项目设计，支持专业的蓝图工作流程。可通过 MCP 客户端构建节点图、创建游戏玩法能力并自动化编辑器任务。还包含由检索增强生成（RAG）驱动的 Python 脚本编写功能，可查阅 Unreal Python API 文档。

🚀 快速开始

要求

| 组件 | 版本 | |-----------|---------| | Unreal Engine | 5.6+ | | Python | 3.11 | | Claude Desktop 或 Cursor | 最新版本 |

⚠️ 重要提示

建议使用 uv 包管理器，若未安装，系统将自动安装。

1. 克隆仓库

git clone https://github.com/gimmeDG/UnrealEngine5-mcp.git
cd UnrealEngine5-mcp

2. 设置 Unreal Engine 插件

将 Plugins/UnrealEngineMCP 文件夹复制到你的 Unreal 项目的 Plugins/ 目录下。
在 Unreal 编辑器中打开你的项目。
启用插件：编辑 → 插件 → 搜索 "UnrealEngineMCP" → 启用。
重启 Unreal 编辑器。

3. 配置 MCP 客户端

Claude Desktop

Windows - 编辑 %APPDATA%\Claude\claude_desktop_config.json：

{
  "mcpServers": {
    "UnrealEngineMCP": {
      "command": "uv",
      "args": [
        "--directory",
        "C:\\path\\to\\unreal-engine-mcp",
        "run",
        "main.py"
      ]
    }
  }
}

macOS - 编辑 ~/Library/Application Support/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "UnrealEngineMCP": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/unreal-engine-mcp",
        "run",
        "main.py"
      ]
    }
  }
}

Cursor

设置 → MCP → 添加服务器，使用相同的配置：

{
  "UnrealEngineMCP": {
    "command": "uv",
    "args": [
      "--directory",
      "/path/to/unreal-engine-mcp",
      "run",
      "main.py"
    ]
  }
}

4. （可选）环境设置

cp .env.example .env
# 若需要更改默认设置，请编辑 .env

默认配置可直接使用。服务器将：

自动创建虚拟环境。
安装所有依赖项。
在首次运行时生成 BM25 索引。

✨ 主要特性

| 类别 | 描述 | |----------|-------------| | 蓝图工具 | 创建蓝图、添加组件、构建节点图、管理变量、连接引脚 | | GAS（游戏玩法能力系统） | 创建游戏玩法能力、游戏玩法效果、能力任务，并进行完整的图形构建 | | 编辑器工具 | 生成演员、创建材质、操作变换、搜索资产 | | RAG 搜索 | 使用 BM25 搜索 Unreal Python API 文档 | | Python 执行 | 在 Unreal 中执行由 RAG 驱动的 Python 代码，并进行文档查找 | | PCG 工具 | 创建 PCG 图、添加节点、连接边（早期阶段 - 开发中） |

🎬 演示

Homing Cluster Grenade

寻的集束手榴弹 - Lyra 手榴弹 + MCP 生成的蓝图（GA，技能系统）

📚 详细文档

可用工具

编辑器工具（21 个工具）

| 类别 | 工具 | |----------|-------| | 演员 | spawn_actor、spawn_blueprint_actor、delete_actor、list_level_actors、set_actor_transform、get_actor_properties、set_actor_property | | 材质 | create_material、apply_material_to_actor、get_actor_material_info | | 搜索 | search_actors、search_assets、list_folder_assets、list_gameplay_tags | | 世界分区 | get_world_partition_info、search_actors_in_region、load_actor_by_guid、set_region_loaded、list_level_instances、get_level_instance_actors | | 实用工具 | get_connection_status |

蓝图工具（47 个工具）

| 类别 | 工具 | |----------|-------| | 核心 | create_blueprint、compile_blueprint、analyze_blueprint、create_child_blueprint、list_graphs | | 组件 | add_component_to_blueprint、set_component_property、set_physics_properties、delete_component_from_blueprint、apply_material_to_blueprint、get_blueprint_material_info、set_mesh_material_color | | 变量 | add_blueprint_variable、add_blueprint_variable_node、get_blueprint_variables、delete_blueprint_variable | | 节点图 | add_blueprint_event_node、add_custom_event_node、add_blueprint_function_node、add_blueprint_flow_control_node、add_function_override、add_blueprint_input_action_node、add_component_getter_node、add_property_get_set_node、add_blueprint_self_reference、add_blueprint_generic_node、list_blueprint_nodes、connect_blueprint_nodes、connect_nodes、set_pin_default_value、get_pin_value、set_node_property、disconnect_blueprint_nodes、delete_blueprint_node、add_pin、delete_pin、add_comment_box | | GAS | create_gameplay_effect、create_gameplay_ability、add_ability_task_node、explore_gas_context、list_attribute_sets、get_attribute_set_info、build_ability_graph | | 反射 | search_functions、get_class_functions、get_class_properties |

RAG 工具（2 个工具）

| 工具 | 描述 | |------|-------------| | search_unreal_api | 使用 BM25 搜索 Unreal Python API 文档 | | execute_unreal_python | 在 Unreal Engine 中执行 Python 代码，并进行安全验证 |

PCG 工具（13 个工具） - 早期阶段

⚠️ 重要提示

PCG 工具已具备功能，但仍在优化中。

| 类别 | 工具 | |----------|-------| | 图 | create_pcg_graph、analyze_pcg_graph、set_pcg_graph_to_component | | 节点 | add_pcg_sampler_node、add_pcg_filter_node、add_pcg_transform_node、add_pcg_spawner_node、add_pcg_attribute_node、add_pcg_flow_control_node、add_pcg_generic_node、list_pcg_nodes、connect_pcg_nodes、disconnect_pcg_nodes、delete_pcg_node |

🔧 技术细节

┌─────────────────────────────────────────────────────────────┐
│              Claude Desktop / Cursor (Client)                │
│            LLM reasoning & tool invocation                   │
└──────────────────────────┬──────────────────────────────────┘
                           │ MCP Protocol (stdio)
┌──────────────────────────┴──────────────────────────────────┐
│                    Python MCP Server                         │
│  ┌────────────────────────────────────────────────────────┐ │
│  │ Tools                                                  │ │
│  │  • editor_tool    - Actor/asset manipulation           │ │
│  │  • blueprint_tool - Blueprint/GAS node graphs          │ │
│  │  • pcg_tool       - PCG graph construction             │ │
│  │  • rag_tool       - API search & Python execution      │ │
│  └────────────────────────────────────────────────────────┘ │
└──────────────────────────┬──────────────────────────────────┘
                           │ TCP
┌──────────────────────────┴──────────────────────────────────┐
│                 Unreal Engine C++ Plugin                     │
│  ┌────────────────────────────────────────────────────────┐ │
│  │ Command Handlers                                       │ │
│  │  • EditorCommands    - Level actor operations          │ │
│  │  • BlueprintCommands - BP asset & node graph editing   │ │
│  │  • PCGCommands       - PCG graph manipulation          │ │
│  │  • PythonExecutor    - Python script execution         │ │
│  └────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘

RAG System (BM25):
  • Provides Unreal Python API documentation search
  • Used by execute_unreal_python on failure for error recovery
  • No external API keys required

📄 许可证

本项目采用 MIT 许可证。

💬 反馈

发现了 bug 或有建议？提交一个问题。

unrealengine5-mcp