AI导哈

虚幻引擎AI控制插件

N1UnrealMCP是一款为虚幻引擎5.7设计的插件，允许AI代理（如Claude Code）控制虚幻编辑器，包括生成演员、编辑蓝图、创建材质和管理资产等功能。

  • by DandyDay
  • C++
  • 本地部署
  • 更新于
在 GitHub 查看 DandyDay/UnrealMCP

使用说明

N1UnrealMCP

韩语

专为 虚幻引擎5.7其他UE版本可能需要API调整。

MCP插件，允许AI代理（Claude Code等）控制虚幻编辑器——生成角色、编辑蓝图、创建材料、管理资产等。

快速开始

# 1. Clone into your project's Plugins folder
git clone https://github.com/DandyDay/UnrealMCP.git YourProject/Plugins/N1UnrealMCP

# 2. Install Python dependencies
cd YourProject/Plugins/N1UnrealMCP/Bridge
uv sync

# 3. Build the project (or open in UE Editor — it builds automatically)

然后添加到您的Claude Code配置中(~/.claude.json 或 .mcp.json):

{
  "mcpServers": {
    "n1-unreal-mcp": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/N1UnrealMCP/Bridge", "python", "-m", "src"]
    }
  }
}

打开UE编辑器→ 启动克劳德代码→ Done.尝试 ping 以验证。

建筑

Claude Code  ──── MCP (stdio) ────►  Python Bridge  ──── TCP :55558 ────►  UE Plugin
(MCP Client)                         (MCP Server)                          (EditorSubsystem)
  • UE插件 （C++）：TCP套接字服务器，命令注册表，11个处理程序类别
  • 巨蟒桥：MCP SDK(FastMCP)、TCP客户端、工具定义
  • 克劳德代码: mcpServers 自动启动配置

特性

11个类别的100多个命令（共104个）：

类别 命令 描述
编辑 19 演员生成/删除/转换、打开级别、视口、截图
蓝图 12 创建BP，添加组件/变量，编译
蓝图节点 15 事件/功能/分支节点，引脚连接
材料 11 创建材质、添加表达式、连接节点
环球音乐集团 7 小部件蓝图、添加/删除小部件、布局
项目 5 增强的输入映射、项目设置、插件
资产 8 查找/导入/重命名/移动/删除/复制资产
景观 8 创建景观、指定材质、图层
馅饼 5 播放/停止，控制台命令（带阻止列表）
数据 10 DataTable CRUD、曲线浮点/曲线线性颜色、数据资产
元 4 ping、list_command、describe_command、list_categories

关键设计

  • 基于TMap的命令注册表 --使用一个函数+一个注册行添加新命令
  • 请求ID关联 --通过UUID匹配的并发MCP工具调用
  • 握手协议 --版本检查+连接时的功能交换
  • 取消/重做 --所有可变命令都封装在 FScopedTransaction
  • 性能集成 --自动结账， MarkPackageDirty，可选保存
  • 参数验证 --必填字段的JSON模式子集+类型检查
  • 分页 — limit/offset 对于大型结果集
  • 控制台命令安全 --PIE中危险命令的阻止列表

需求

  • 虚幻引擎5.7+
  • Python 3.11+
  • 紫外线 （Python包管理器）
  • Claude Code（或任何兼容MCP的客户端）

设置

1.安装插件

复制 N1UnrealMCP/ 进入你的项目 Plugins/ 目录。重建。

2.安装Python依赖项

cd N1UnrealMCP/Bridge
uv sync

3.配置克劳德代码

添加 ~/.claude.json （根据您的项目 mcpServers):

{
  "n1-unreal-mcp": {
    "command": "uv",
    "args": [
      "run",
      "--directory",
      "/path/to/N1UnrealMCP/Bridge",
      "python",
      "-m",
      "src"
    ]
  }
}

4.发射

  1. 打开UE编辑器（插件自动启动端口55558上的TCP服务器）
  2. 启动Claude代码（通过MCP自动启动Python桥）
  3. 使用 ping 验证连接

用法示例

# Spawn a point light
spawn_actor(class_path="PointLight", location=[0, 0, 500])

# Create a blueprint with components
create_blueprint(name="BP_MyActor", parent_class="Actor")
add_component(blueprint_path="/Game/Blueprints/BP_MyActor.BP_MyActor", component_class="StaticMeshComponent")
compile_blueprint(blueprint_path="/Game/Blueprints/BP_MyActor.BP_MyActor")

# Search assets
find_assets(name_pattern="Sky", limit=10)

# Read and clone a curve
get_curve_keys(curve_path="/Game/Data/Sky/MC_SunIntensity.MC_SunIntensity")
create_curve(name="MC_SunIntensity_New", curve_type="CurveFloat", path="/Game/Data/Sky")
set_curve_keys(curve_path="/Game/Data/Sky/MC_SunIntensity_New.MC_SunIntensity_New", keys=[...])

延伸

向现有处理程序添加新命令

// In your handler's RegisterCommands():
RegisterCommand("my_command", "Description for AI",
    nullptr, // ParameterSchema (optional)
    true,    // bMutatesEditorState
    false,   // bRequiresPIE
    false,   // bLongRunning
    10000,   // DefaultTimeoutMs
    [this](const TSharedPtr<FJsonObject>& P) { return HandleMyCommand(P); });

添加新的处理程序类别

  1. 创建 N1MCPMyHandler.h/cpp 继承 FN1MCPHandlerBase
  2. 注册于 N1MCPBridge.cpps RegisterAllHandlers()
  3. 创建 Bridge/src/tools/my_handler.py 和 @mcp.tool() 函数
  4. 添加导入 Bridge/src/server.py

协议

TCP消息是换行符分隔的JSON：

// Request
{"type":"request", "id":"<uuid>", "command":"ping", "params":{}, "timeout_ms":10000}

// Response
{"type":"response", "id":"<uuid>", "status":"success", "result":{"pong":"N1UnrealMCP"}}

// Handshake
{"type":"hello", "protocol_version":"1.0", "client":"n1-unreal-mcp-bridge"}
{"type":"hello_ack", "protocol_version":"1.0", "server":"N1UnrealMCP", "capabilities":["pagination","meta_commands"]}

许可证

麻省理工学院

相关 MCP