内容
<p align="center">
<h1 align="center">Funplay MCP for Unreal</h1>
<p align="center"><strong>最先进的MCP服务器，适用于虚幻编辑器。</strong></p>
<p align="center">
<img src="https://img.shields.io/badge/Unreal%20Engine-5.3%E2%80%935.8-blue" alt="Unreal Engine 5.3-5.8" />
<img src="https://img.shields.io/badge/license-MIT-green" alt="MIT" />
<img src="https://img.shields.io/badge/MCP-compatible-purple" alt="MCP compatible" />
<img src="https://img.shields.io/badge/editor-only-lightgrey" alt="Editor only" />
</p>
<p align="center"><a href="./README_CN.md">中文</a> | English</p>
</p>
> 💖 如果这节省了您的时间，请给仓库点赞 — 它帮助很大。
---
Funplay MCP for Unreal 让 AI 助手（如 **Claude Code, Cursor, Windsurf, Codex, VS Code Copilot** 等）可以直接在运行的虚幻编辑器中操作。它是一个 **纯 Python 编辑器插件**（无需 C++ 编译，可跨 Unreal Engine 5.3–5.8 版本），通过本地 MCP 服务器暴露编辑器，并附带一个小型 Node.js stdio 桥接器，连接您的 AI 客户端。采用 MIT 许可，免费商用。
用自然语言描述您想要的 — *生成和排列 Actor，构建关卡和蓝图，创建材质，导入资产，驱动 Play-In-Editor，捕获截图，或运行任意 `execute_python`* — 让助手为您完成。
> "构建一个小型竞技场：一个地板，四面墙，一些点光源，和一个位于中间的玩家起点。然后播放并发送我一张截图。"
>
> 助手检查关卡，生成和定位 Actor，设置照明，进入 Play-In-Editor，并返回一张截图 — 所有这些都通过这个 MCP 服务器。
## 演示
<p align="center">
<img src="./docs/assets/codex-to-unreal-castle-demo.gif" alt="Codex uses Funplay MCP to build a castle in Unreal Editor" width="900" />
</p>
Codex 请求一个城堡，Funplay MCP 通过 MCP 驱动虚幻编辑器，最终的场景直接出现在编辑器中。
## 快速开始
三步走：**（1）将插件放入您的项目中，（2）启用并启动服务器，（3）将您的 AI 客户端指向它。**
### 1. 安装插件
> 💡 插件是纯 Python — 无需编译。
- 将 `FunplayMCP/` 文件夹复制到您的项目的 `Plugins/` 目录（`<YourProject>/Plugins/FunplayMCP/`），**或** 从最新的 [Release](https://github.com/FunplayAI/funplay-unreal-mcp/releases) 下载 `Funplay.UnrealMcp.vX.Y.Z.zip` 并解压到那里。
- 它依赖于引擎的 **Python 编辑器脚本插件**，`.uplugin` 自动启用。
### 2. 启用并启动 MCP 服务器
- 打开您的项目。在 **编辑 → 插件** 中，确认 **Funplay MCP for Unreal** 已启用，然后如果需要重启编辑器。
- 启动时，服务器默认监听 `http://127.0.0.1:8765/`。如果端口被占用，它会自动选择一个空闲的本地端口（同一项目的第二个编辑器附加到现有的服务器）。
- 为每个项目生成并存储一个 **身份验证令牌**，位于 `<YourProject>/Saved/FunplayMCP/funplay_mcp_settings.json`。
- 随时可以从 **工具 → Funplay MCP → 日志端点 + 令牌** 获取端点和令牌（打印到输出日志）。
### 3. 配置您的 AI 客户端
最快捷的方式是编辑器菜单：**工具 → Funplay MCP → 配置 Claude Code**（或其他客户端，如 Cursor / VS Code / Codex）。它会写入正确的配置，其中包含填写好的端点和令牌。
<details>
<summary>手动配置</summary>
**Claude Code** (`~/.claude.json`)，**Cursor** (`~/.cursor/mcp.json`) :
```json
{
"mcpServers": {
"funplay-unreal": {
"command": "npx",
"args": ["-y", "funplay-unreal-mcp"],
"env": {
"FUNPLAY_UNREAL_MCP_URL": "http://127.0.0.1:8765/",
"FUNPLAY_UNREAL_MCP_TOKEN": "<token from the Funplay MCP menu>"
}
}
}
}
```
**VS Code** (`mcp.json`) 使用 `servers` 键；**Codex** (`~/.codex/config.toml`) 使用 `[mcp_servers."funplay-unreal"]` 表。两者都可以通过单击菜单写入。
</details>
### 4. 验证连接
要求您的助手：
- 调用 `get_project_info`，
- 读取资源 `unreal://project/context`，
- 运行 `execute_python` 并执行 `result = unreal.SystemLibrary.get_engine_version()`。
## 开始前
- **仅限编辑器。** 服务器在虚幻编辑器中运行；它不包含在打包的游戏中。
- **仅限环回。** 它绑定 `127.0.0.1` 并拒绝非环回源；POST 请求需要每个项目的身份验证令牌。
- **默认 `core` 配置文件。** 默认情况下暴露一个聚焦的 32 工具集；当您想要所有工具时，可以在设置文件中切换到 `full`（97 个工具）。
- **`execute_python` 安全检查** 默认开启（文件系统/进程拒绝列表）；通过传递 `safety_checks=false` 来覆盖每个调用。
- 所有 `unreal` API 工作都转移到游戏线程，因此编辑器不会因线程外部访问而崩溃。
## 为什么有这个项目
- **`execute_python` 优先。** 一个一流的工具，可以在编辑器中运行任意 Python — 96 个专用工具无法涵盖的所有操作，您仍然可以执行。
- **内置 API 发现。** `search_api` / `describe_class` / `inspect_object` 读取嵌入的 `unreal` 模块的文档，因此助手使用真实的 API 而不是幻觉。
- **纯 Python，无需构建。** 无需 C++ 模块，无需编译步骤，可跨 UE 5.3–5.8 版本移植。
- **安全构造。** 游戏线程调度、环回绑定、身份验证令牌和 DNS 重新绑定保护开箱即用。
- **一键客户端配置 + 项目技能。** 从编辑器菜单配置 Claude Code / Cursor / VS Code / Codex 并生成 `AGENTS.md` 桥接器。
- **相同的家族，相同的约定** ，适用于 Funplay MCP for Unity / Godot / Cocos。
## 亮点
- **97 个内置工具** （32 个在默认 `core` 配置文件中），跨 20 个类别。
- **MCP 资源** （`unreal://...`）用于项目、关卡、选择、日志和工具目录，以及 **提示模板** 用于常见工作流程。
- **结构化结果** — 每个工具都返回 JSON，助手可以推理；截图以内联图像返回。
- **自动端口回退** 和 **同一项目实例附件**。
- **零依赖 Node 桥接器** 以 `funplay-unreal-mcp` 发布到 npm。
## MCP 功能
- **工具：** 97（32 核心 / 97 完整）。
- **主要执行：** `execute_python` — 在编辑器中运行任意 Python 片段。
- **提示：** `level_review`, `feature_plan`, `debug_runtime`, `blueprint_actor`.
- **资源：** `unreal://project/context`, `unreal://project/info`, `unreal://level/current`, `unreal://actors/list`, `unreal://selection/current`, `unreal://tools/catalog`, `unreal://logs/recent`, `unreal://interaction/history`, 以及模板 `unreal://actor/{ref}` 和 `unreal://asset/{path}`.
## 与 Funplay MCP for Unity 比较
| | Funplay MCP for Unreal | Funplay MCP for Unity |
|---|---|---|
| 编辑器端 | 纯 Python 插件（无需构建） | C# 包 |
| 主要执行 | `execute_python`（嵌入式 `unreal`） | `execute_code`（内存 C#） |
| 传输 | 本地 HTTP + stdio 桥接器 | 本地 HTTP + stdio 桥接器 |
| 默认暴露 | `core` 配置文件（32/97） | `core` 配置文件 |
| 引擎版本 | UE 5.3–5.8 | Unity 2022.3+ |
| 客户端配置 | 一键（Claude/Cursor/VS Code/Codex） | 一键 |
## 内置工具
**97 个内置工具** （32 `core`）。调用 `get_tool_catalog` 获取实时列表。
| 类别 | 工具 |
|---|---|
| 执行 | `execute_python`, `run_console_command` |
| 反射 | `search_api`, `describe_class`, `list_enum_values`, `inspect_object` |
| Actor | `spawn_actor`, `spawn_actor_from_asset`, `destroy_actor`, `duplicate_actor`, `set_actor_transform`, `set_actor_label`, `set_actor_property`, `attach_actor`, `get_actor_info`, `list_actors`, `find_actors`, `batch_spawn_actors` |
| 组件 | `add_component`, `list_components`, `get_component_properties`, `set_component_property`, `set_static_mesh`, `set_material`, `set_physics_properties`, `add_ism_instances` |
| 资产 | `list_assets`, `find_assets`, `get_asset_info`, `duplicate_asset`, `rename_asset`, `delete_asset`, `save_asset`, `import_asset`, `create_folder`, `asset_exists`, `get_asset_references` |
| 蓝图 | `create_blueprint`, `add_blueprint_component`, `compile_blueprint`, `get_blueprint_info`, `spawn_blueprint` |
| 材质 | `create_material`, `create_material_instance`, `set_material_instance_parameter`, `get_material_info`, `add_material_expression`, `connect_material_expressions`, `connect_material_property`, `recompile_material` |
| 关卡 | `new_level`, `load_level`, `save_current_level`, `save_all_dirty`, `get_level_info`, `list_levels` |
| Play-In-Editor | `play_in_editor`, `stop_play_in_editor`, `simulate_in_editor`, `get_play_state` |
| 视口 | `set_viewport_camera`, `get_viewport_camera`, `focus_viewport` |
| 截图 | `take_screenshot` |
| 选择 | `get_selection`, `set_selection`, `select_none`, `get_selected_assets` |
| 编辑器状态 | `get_editor_state`, `get_project_info`, `get_output_log`, `sync_content_browser`, `health_status`, `undo`, `redo` |
| 文件 | `read_file`, `write_file`, `list_directory`, `file_exists` |
| 程序化 | `build_wall`, `build_floor`, `build_stairs`, `scatter_actors` |
| 组织 | `set_actor_folder`, `create_layer`, `add_actors_to_layer`, `list_layers` |
| 数据 | `create_data_table`, `get_data_table`, `set_data_table_rows`, `export_data_table_csv` |
| UMG | `create_widget_blueprint`, `add_widget`, `set_widget_property` |
| 效果 | `spawn_niagara_system`, `set_niagara_parameter` |
| 发现 | `get_tool_catalog` |
## 仓库布局
```
FunplayMCP/ # 虚幻编辑器插件（纯 Python）
FunplayMCP.uplugin
Content/Python/
init_unreal.py # 自动运行入口点
funplay_mcp/ # 服务器、传输、注册表、提供程序
tools/ # 每个工具类别一个模块
stdio-wrapper/ # 零依赖 Node.js stdio <-> HTTP 桥接器
scripts/ # validate_repo.py, package_release.py
tests/ # Node + Python 测试（无需编辑器运行）
server.json # MCP 注册表清单
```
## 架构
```
AI 客户端（Claude Code / Cursor / ...）
│ stdio (MCP JSON-RPC)
▼
funplay-unreal-mcp (Node 桥接器，npx)
│ HTTP + 令牌 → 127.0.0.1:8765
▼
虚幻编辑器插件（Python）
│ 游戏线程泵（register_slate_post_tick_callback）
▼
unreal API → Actor / 资产 / 蓝图 / 关卡 / PIE
```
## 贡献
参见 [CONTRIBUTING.md](./CONTRIBUTING.md)。在打开 PR 之前运行 `python3 scripts/validate_repo.py`。
## 许可证
MIT — 参见 [LICENSE](./LICENSE)。
