Funplay Unreal MCP

Funplay MCP for Unreal

最先进的 Unreal Editor MCP 服务。

中文 | 英文

💖 如果它为你节省了时间，请给仓库点个星标——这对我们帮助很大。

Funplay MCP for Unreal 可让 AI 助手——Claude Code、Cursor、Windsurf、Codex、 VS Code Copilot 以及任何其他 MCP 客户端——直接操作正在运行的 Unreal Editor。它是一个纯 Python 编辑器插件（无需编译 C++，适用于 Unreal Engine 5.3–5.8），通过本地 MCP 服务开放编辑器功能，并附带一个 用于连接 AI 客户端的小型 Node.js stdio 桥接程序。采用 MIT 许可证，可免费用于商业用途。

用自然语言描述你的需求——生成并摆放 Actor、构建关卡和 Blueprint、创建材质、导入资源、驱动 Play-In-Editor、截取屏幕截图，或运行任意 execute_python——然后让助手来完成。

“建一个小型竞技场：铺一块地板、建四面墙、放几盏点光源，并在中间放置玩家起始点。然后运行游戏并发给我一张截图。”

助手会检查关卡、生成并摆放 Actor、设置灯光、进入 Play-In-Editor，并返回屏幕截图——这一切都通过此 MCP 服务完成。

演示

Codex 提出建造城堡的需求，Funplay MCP 通过 MCP 驱动 Unreal Editor，最终场景直接呈现在编辑器中。

快速开始

分三步：(1) 将插件放入项目，(2) 启用插件并启动服务，(3) 将 AI 客户端连接到它。

1. 安装插件

💡 该插件完全由 Python 编写，无需编译。

• 将 FunplayMCP/ 文件夹复制到项目的 Plugins/ 目录中（<YourProject>/Plugins/FunplayMCP/），或者从最新的发布版本下载 Funplay.UnrealMcp.vX.Y.Z.zip 并解压到该目录。
• 它依赖引擎的 Python Editor Script Plugin，.uplugin 会自动启用该插件。

2. 启用并启动 MCP 服务

• 打开项目。在 Edit → Plugins 中确认已启用 Funplay MCP for Unreal，如果提示重启编辑器，请重启。
• 默认情况下，服务启动时会监听 http://127.0.0.1:8765/。如果该端口正被占用，服务会自动选择一个空闲的本地端口（同一项目的第二个编辑器实例会连接到现有服务）。
• 系统会为每个项目生成一个 auth token，并将其存储在 <YourProject>/Saved/FunplayMCP/funplay_mcp_settings.json 中。
• 随时可通过 **Tools → Funplay MCP → Log Endpoint
  • Token** 获取端点和令牌（信息会打印到 Output Log）。

3. 配置 AI 客户端

最快的方法是使用编辑器菜单：Tools → Funplay MCP → Configure Claude Code（或 Cursor / VS Code / Codex）。该菜单会写入正确的配置，并填入端点和令牌。

{
  "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>"
      }
    }
  }
}

4. 验证连接

请让助手：

• 调用 get_project_info，
• 读取资源 unreal://project/context，
• 运行 execute_python，其中包含 result = unreal.SystemLibrary.get_engine_version()。

开始之前

• 仅限编辑器。 服务在 Unreal 编辑器内运行；不会随打包后的游戏一起发布。
• 仅限环回地址。 服务绑定到 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 个内置工具（默认 core 配置中有 32 个），涵盖 20 个类别。
• MCP 资源（unreal://...），涵盖项目、关卡、选中项、日志和工具目录；另提供常见工作流的提示词模板。
• 结构化结果——每个工具都会返回助手可用于推理的 JSON；截图会以内嵌图片形式返回。
• 自动回退端口，并支持附加到同一项目的实例。
• 零依赖 Node 桥接程序，已发布到 npm，包名为 funplay-unreal-mcp。

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 的比较

内置工具

97 个内置工具（32 个 core）。调用 get_tool_catalog 获取实时列表。

仓库布局

FunplayMCP/                         # the Unreal editor plugin (pure Python)
  FunplayMCP.uplugin
  Content/Python/
    init_unreal.py                  # auto-run entry point
    funplay_mcp/                    # server, transport, registry, providers
      tools/                        # one module per tool category
stdio-wrapper/                      # zero-dependency Node.js stdio<->HTTP bridge
scripts/                           # validate_repo.py, package_release.py
tests/                             # Node + Python tests (run without the editor)
server.json                        # MCP registry manifest

架构

AI client (Claude Code / Cursor / ...)
        │  stdio (MCP JSON-RPC)
        ▼
funplay-unreal-mcp  (Node bridge, npx)
        │  HTTP + token  →  127.0.0.1:8765
        ▼
Unreal Editor plugin (Python)
        │  game-thread pump (register_slate_post_tick_callback)
        ▼
unreal API  →  Actors / Assets / Blueprints / Levels / PIE

贡献

请参阅 CONTRIBUTING.md。提交 PR 前，请运行 python3 scripts/validate_repo.py。

许可证

MIT — 请参阅 LICENSE。