MCP Unreal

mcp不真实

  

MCP（模型上下文协议）服务器，为AI编码代理提供对虚幻引擎5.7项目的完全自主控制。Single Go二进制，零外部依赖。

构建、测试、操作编辑器、编辑蓝图、生成过程网格和查找UE API文档—所有这些都通过49个MCP工具实现，任何MCP-兼容代理都可以直接调用。

快速开始

# Install
go install github.com/remiphilippe/mcp-unreal/cmd/mcp-unreal@latest

# Build the documentation index
mcp-unreal --build-index

# Register with your AI coding tool (see Setup section below)

先决条件

• 转到1.25+ — 安装
• 虚幻引擎5.7 --用于构建/测试工具和编辑器交互
• 远程控制API插件 --在UE中启用（请参见 启用远程控制API 在......下面
• MCPUnreal编辑器插件 --有关高级编辑器工具（请参见 插件/README.md)

安装

来源

git clone https://github.com/remiphilippe/mcp-unreal.git
cd mcp-unreal
make build

预构建二进制文件

下载自 --适用于macOS、Linux和Windows的amd64和arm64。

启用远程控制API

远程控制API是一个内置的UE插件，它提供对端口30010上的参与者属性和函数调用的HTTP访问。mcp虚幻使用它 get_property, set_property, call_function，以及 move_actor 工具。

1. 在虚幻编辑器中打开您的项目
2. 首选 编辑>插件
3. 搜索 “远程控制API”
4. 检查 启用 复选框
5. 出现提示时重新启动编辑器

要验证它是否正在运行：

curl http://localhost:30010/remote/info

您应该得到一个带有API版本的JSON响应。如果连接被拒绝，则插件未启用或编辑器未运行。

安装UE插件

复制 plugin/ 目录到项目的 Plugins/ 文件夹：

cp -r plugin/ /path/to/YourProject/Plugins/MCPUnreal/

重建项目。当编辑器加载时，该插件在端口8090上启动HTTP服务器。看 插件/README.md 了解详情。

客户端设置

mcp-real可与任何兼容mcp的AI编码工具配合使用。下面是每个的设置说明。

备注：替换 /path/to/mcp-unreal 使用构建二进制文件的实际路径（例如 go install 或 make build).集 MCP_UNREAL_PROJECT 致你的 .uproject 文件路径或项目根目录。

克劳德代码

CLI注册：

claude mcp add mcp-unreal -- /path/to/mcp-unreal

配置文件 (.mcp.json 项目根，或 ~/.claude.json 全球）：

{
  "mcpServers": {
    "mcp-unreal": {
      "type": "stdio",
      "command": "/path/to/mcp-unreal",
      "env": {
        "MCP_UNREAL_PROJECT": "/path/to/MyProject/MyProject.uproject"
      }
    }
  }
}

光标

配置文件 (.cursor/mcp.json 项目根，或 ~/.cursor/mcp.json 全球）：

{
  "mcpServers": {
    "mcp-unreal": {
      "command": "/path/to/mcp-unreal",
      "env": {
        "MCP_UNREAL_PROJECT": "/path/to/MyProject/MyProject.uproject"
      }
    }
  }
}

保存后，通过启用 光标设置>MCP服务器.

OpenAI Codex命令行界面

CLI注册：

codex mcp add mcp-unreal -- /path/to/mcp-unreal

配置文件 (.codex/config.toml 项目根，或 ~/.codex/config.toml 全球）：

[mcp_servers.mcp-unreal]
command = "/path/to/mcp-unreal"
args = []
tool_timeout_sec = 120

[mcp_servers.mcp-unreal.env]
MCP_UNREAL_PROJECT = "/path/to/MyProject/MyProject.uproject"

增加 tool_timeout_sec 为了 build_project 和 run_tests 这可能需要60+秒。

VS代码与GitHub Copilot

需要启用GitHub Copilot代理模式的VS代码1.99+。

配置文件 (.vscode/mcp.json 项目根）：

{
  "servers": {
    "mcp-unreal": {
      "type": "stdio",
      "command": "/path/to/mcp-unreal",
      "env": {
        "MCP_UNREAL_PROJECT": "${workspaceFolder}"
      }
    }
  }
}

帆板运动

配置文件 (~/.codeium/windsurf/mcp_config.json):

{
  "mcpServers": {
    "mcp-unreal": {
      "command": "/path/to/mcp-unreal",
      "env": {
        "MCP_UNREAL_PROJECT": "/path/to/MyProject/MyProject.uproject"
      }
    }
  }
}

Cline（VS代码扩展）

打开临床面板>MCP服务器图标>配置选项卡> 高级MCP设置，然后添加：

{
  "mcpServers": {
    "mcp-unreal": {
      "command": "/path/to/mcp-unreal",
      "env": {
        "MCP_UNREAL_PROJECT": "/path/to/MyProject/MyProject.uproject"
      }
    }
  }
}

泽德

配置文件 (~/.config/zed/settings.json):

{
  "context_servers": {
    "mcp-unreal": {
      "command": "/path/to/mcp-unreal",
      "env": {
        "MCP_UNREAL_PROJECT": "/path/to/MyProject/MyProject.uproject"
      }
    }
  }
}

快速参考

推荐系统提示

为了获得最佳效果，请在项目的系统提示中添加以下内容（例如。 CLAUDE.md, .cursorrules, .codex/instructions.md或等效物）。这告诉人工智能代理如何有效地使用MCP工具。

## Unreal Engine MCP Tools

This project uses mcp-unreal for AI-driven Unreal Engine development. The following MCP tools are available:

### Workflow Guidelines

1. **Always check status first**: Call `status` to verify the editor and plugin connections before attempting editor operations.
2. **Look up docs before writing UE code**: Use `lookup_class` to get class references (inheritance, properties, functions) and `lookup_docs` for API patterns before writing C++ or Blueprint logic.
3. **Build-test cycle**: After editing C++ files, call `build_project` to compile, then `run_tests` to verify. Read build errors carefully — use `lookup_docs` to understand UE APIs.
4. **Actor workflow**: Use `get_level_actors` to discover existing actors, `spawn_actor` to create new ones, `move_actor` to position them, and `set_property`/`get_property` to read/write properties.
5. **Blueprint workflow**: Use `blueprint_query` with operation `list` to find Blueprints, then `list_variables`/`list_functions`/`list_nodes` to inspect them. Use `blueprint_modify` to make changes, and always `compile` after modifications.
6. **Material workflow**: Use `material_ops` with `create` to make new materials, `get_parameters` to inspect existing ones, and `set_parameter` or `set_texture` to modify them.
7. **Save your work**: The editor does not auto-save. After making changes, use `level_ops` with `save_level` or remind the user to save.
8. **PIE testing**: Use `pie_control` with operation `start` to begin a Play In Editor session, `status` to verify it started, and `stop` to end it. Use `capture_viewport` with `include_ui=true` during PIE to see the game view with HUD/menus. Use `player_control` to move the player pawn (`teleport`, `set_rotation`) or reposition the editor viewport camera (`get_camera`, `set_camera`).

### Tool Modes

- **Headless tools** (`build_project`, `run_tests`, `cook_project`, etc.) do NOT require the editor to be running. They invoke UnrealEditor-Cmd directly.
- **Editor tools** (actors, blueprints, materials, etc.) require the Unreal Editor to be open with the MCPUnreal plugin loaded.
- **Documentation tools** (`lookup_docs`, `lookup_class`) are always available — use them liberally.

### Object Paths

Many tools require UE object paths. The format is:
- Actor paths: `/Game/Maps/MapName.MapName:PersistentLevel.ActorName`
- Asset paths: `/Game/Folder/AssetName`
- Engine assets: `/Engine/BasicShapes/Cube`

Use `get_level_actors` to discover actor paths, and `search_assets` to find asset paths.

小贴士：对于Claude Code，请将其另存为 CLAUDE.md 在您的项目根目录中。对于光标，另存为 .cursorrules.对于Codex，除 .codex/instructions.md.

配置

平台默认值 UE_EDITOR_PATH:

• macOS: /Users/Shared/Epic Games/UE_5.7/Engine/Binaries/Mac/UnrealEditor-Cmd
• 视窗: C:\Program Files\Epic Games\UE_5.7\Engine\Binaries\Win64\UnrealEditor-Cmd.exe
• Linux: /opt/UnrealEngine/Engine/Binaries/Linux/UnrealEditor-Cmd

建筑

                                                    ┌───────────────────────┐
                                                    │   UE 5.7 Editor       │
                                                    │                       │
                                                    │  ┌─────────────────┐  │
                                                    │  │ Remote Control  │  │
                                              ┌────►│  │ API (port 30010)│  │
                                              │     │  │ (built-in)      │  │
                                              │     │  └─────────────────┘  │
┌──────────────┐    stdio     ┌──────────────┐│     │                       │
│  AI Coding   │   JSON-RPC   │              ││     │  ┌─────────────────┐  │
│    Agent     │◄────────────►│  mcp-unreal  │├────►│  │ MCPUnreal       │  │
│ (Claude Code │              │ (Go binary)  ││     │  │ Plugin (port    │  │
│  Cursor, etc)│              │              ││     │  │ 8090)           │  │
└──────────────┘              │ 49 tools     │┘     │  │ • Actors        │  │
                              │ doc index    │      │  │ • Blueprints    │  │
                              │              │      │  │ • Materials     │  │
                              │ ┌──────────┐ │      │  │ • PCG / GAS    │  │
                              │ │ Headless │ │      │  │ • Niagara       │  │
                              │ │ exec.Cmd │─┼──────│──│ • Mesh ops      │  │
                              │ └──────────┘ │      │  │ • Levels        │  │
                              │              │      │  └─────────────────┘  │
                              │ ┌──────────┐ │      │                       │
                              │ │ Bleve    │ │      └───────────────────────┘
                              │ │ Doc Index│ │
                              │ └──────────┘ │      ┌───────────────────────┐
                              │              │──────│ docs/                 │
                              └──────────────┘      │ ├── ue5.7/            │
                                                    │ ├── realtimemesh/     │
                                                    │ └── index.bleve       │
                                                    └───────────────────────┘

三条通信路径：

1. 无头 — exec.Command 调用 UnrealEditor-Cmd 用于构建、测试和烹饪。不需要编辑。
2. 远程控制API --HTTP PUT到 localhost:30010 用于属性访问和函数调用。内置于UE中。
3. MCPUnreal插件 --HTTP POST到 localhost:8090 用于蓝图编辑、资源查询、网格操作和其他深度编辑器内部。

看 实施.md 查看完整的架构文档。

可用工具（48）

构建和编译（无头）

项目与配置（无头）

测试自动化（无头）

演员和属性（编辑）

蓝图编辑（编辑器）

动画蓝图编辑（编辑器）

资源（编辑器）

材料（编辑）

字符和输入（编辑器）

程序内容生成（编辑器）

游戏能力系统（编辑）

尼亚加拉视觉特效（编辑）

网格生成（编辑器）

级别（编辑）

编辑器实用程序（编辑器）

组件和实例化（编辑器）

纹理（编辑器）

数据表（编辑器）

Fab Marketplace（编辑）

子系统和UI（编辑器）

网络调试（编辑器）

文档（始终可用）

文档索引

构建本地文档搜索索引：

mcp-unreal --build-index

这将为来自的markdown文件建立索引 docs/ue5.7/ 和 docs/realtimemesh/，加上你的项目 CLAUDE.md。索引存储在 ./docs/index.bleve （可通过以下方式配置 MCP_UNREAL_DOCS_INDEX).

要添加自定义文档，请将markdown文件放置在 docs/ 目录并重建索引。看 docs/README.md.

示例用法

注册后，您的AI代理可以自主地：

You: "Build the project, fix any errors, and run the tests"

Agent calls:
  1. status()                    → editor + plugin online
  2. build_project()             → finds 2 compile errors
  3. lookup_class("AActor")      → looks up the correct API
  4. (edits the C++ source)
  5. build_project()             → clean build
  6. run_tests(filter: "Game")   → 14/14 tests pass

You: "Add a Niagara fire effect to the torch actor"

Agent calls:
  1. get_level_actors(name_filter: "Torch")  → finds actor path
  2. lookup_class("UNiagaraComponent")       → checks API
  3. niagara_ops(operation: "spawn_system", system_path: "/Game/FX/NS_Fire", ...)
  4. niagara_ops(operation: "set_parameter", parameter_name: "SpawnRate", value: 50)

You: "Create a PCG scatter for placing rocks on the landscape"

Agent calls:
  1. lookup_docs("PCG scatter landscape")    → reads PCG docs
  2. pcg_ops(operation: "list_components")   → finds existing PCG actors
  3. spawn_actor(class: "Actor", name: "RockScatter")
  4. pcg_ops(operation: "add_node", node_type: "SurfaceSampler")
  5. pcg_ops(operation: "execute")           → generates rocks

发展

# Build
make build

# Run all tests with race detector
make test

# Go lint
make lint

# C++ format check (requires clang-format)
make cpp-fmt-check

# Run all checks (Go format, C++ format, vet, lint, tests)
make check

C++插件测试

MCPUnreal插件包括在UE编辑器内无头运行的自动化测试。这些要求在本地安装UE 5.7 不 作为CI的一部分，他们可以选择参与当地的发展。

# Build the test project (first run ~2-5 min, incremental after)
make test-cpp-build

# Build and run all MCPUnreal.* automation tests
make test-cpp

这在中使用了最小的UE项目 test-project/ 该符号链接插件源代码并运行所有 MCPUnreal.* 测试通过 UnrealEditor-Cmd -nullrhi.

贡献

看 贡献.md 关于开发设置、编码标准以及如何添加新工具。

许可证

Apache-2.0--参见 许可证.

虚幻引擎是Epic Games，股份有限公司的商标。本项目不隶属于Epic Game，也不由Epic Games。