Funplay MCP for Unity

The Most Advanced MCP Server for Unity Editor

中文 | English

💖 如果这个项目对你有帮助，欢迎顺手点一个 Star。它能帮助更多 Unity 开发者发现这个项目，也能支持后续持续维护。

Funplay MCP for Unity 是一个采用 MIT 协议的 Unity 编辑器 MCP 服务器，让 Claude Code、Cursor、Kimi Code、LM Studio、Windsurf、Codex、VS Code Copilot 等 AI 助手直接操作正在运行的 Unity 项目。

一句话描述你的游戏 — AI 助手通过 Funplay MCP for Unity 的内置工具自动创建场景、编写脚本、验证运行态、模拟输入、分析性能并完成编辑器自动化，把所有逻辑串联起来。

"做一个贪吃蛇游戏，10x10 网格，食物随机生成，计分 UI，游戏结束界面"

AI 助手通过 Funplay MCP for Unity 全程处理：创建场景、生成全部脚本、搭建 UI、配置游戏逻辑 — 只需一句话。

16 秒 demo — AI 生成 3D 模型并端到端集成进场景。观看高清 MP4。

快速开始

如果你只想尽快跑起来，先做这三步：

• 用 Git URL 安装 Unity 包
• 打开 Funplay > MCP Server
• 使用内置的一键客户端配置

1. 通过 UPM 安装 (Git URL)

在 Unity 中，打开 Window → Package Manager → + → Add package from git URL：

https://github.com/FunplayAI/funplay-unity-mcp.git

💡 在 clone 或安装之前，如果你愿意顺手点一个 ⭐，会非常感谢。

可选方案：通过 OpenUPM 安装

如果你希望 Unity Package Manager 显示 registry 提供的完整“版本历史记录”并能选择历史版本，可以改用 OpenUPM 安装。

使用 OpenUPM CLI：

openupm add com.gamebooom.unity.mcp

或者手动在 Packages/manifest.json 中添加 scoped registry：

{
  "scopedRegistries": [
    {
      "name": "OpenUPM",
      "url": "https://package.openupm.com",
      "scopes": [
        "com.gamebooom"
      ]
    }
  ],
  "dependencies": {
    "com.gamebooom.unity.mcp": "0.6.9"
  }
}

如果之前是用 Git URL 安装的，先移除 Git dependency，再从 OpenUPM 安装。Git 来源的包在 Unity 中只会显示当前解析到的 Git 版本，不会显示 registry 提供的完整 Version History。

2. 启动 MCP Server

菜单：Funplay → MCP Server 启动服务。

新工程使用按工程路径派生的独立端口，因此同时打开两个工程的编辑器不会互相抢端口。MCP Server 窗口会显示实际地址（http://127.0.0.1:<端口>/），一键配置会把该地址写进客户端配置。需要固定端口（CI / 防火墙规则）时在 Server Port 里填一个即可 pin 住，点 Use Per-Project Port 改为按工程派生。

从旧版本升级不会有任何变化：工程会保留原来在用的端口（记为 pin），已配置的客户端照旧可用。等到需要让该工程与另一个编辑器同时服务时，再点一次 Use Per-Project Port 即可。完整配置指南见 同时开多个 Unity 工程。

如果窗口显示当前使用回退端口，不要继续使用仍指向被占稳定端口的客户端条目；它可能连到占着该端口的另一个进程。一键配置会保持阻止，直到你点 Use Per-Project Port 或 Pin Current Port，并等服务器完成重启。

默认传输仍然是进程内 Direct HTTP。如果你需要在 Unity 脚本重编译或进入 Play Mode 触发域重载时尽量保持 MCP 客户端连接，可以在 MCP Server 窗口启用 Experimental Broker Mode。它会用 Unity 自带 Mono 启动一个很小的本地 broker，客户端仍然连接同一个 127.0.0.1 端口，不需要改 MCP 配置。

如果你想编辑 core 或 full 各自暴露哪些工具，可以打开 Funplay → Tool Exposure。

如果需要调整 execute_code 安全默认值或插件 debug 日志，可以打开 Funplay → MCP Settings。

3. 配置 AI 客户端

优先使用 Funplay > MCP Server 窗口里的 一键 MCP 配置。

选择目标客户端后点击 Configure，插件会直接帮你写入推荐的 MCP 配置项。

对于 Claude Code、Cursor、Codex、OpenCode 和 DeepSeek Harness，也可以点击 Configure + Skills，同时安装两个内置项目 skills。

如果你希望为当前 Unity 项目配置项目级 AI 指引，可以打开 Funplay → Project Skills，为支持的平台安装内置的 unity-mcp-workflow 和 unity-ui-composition skills，其中 UI skill 用于竖屏、横屏响应式 uGUI 工作。

如果你更想手动编辑配置文件，再参考下面这些示例（把 <project> 换成本工程的条目名、<port> 换成本工程端口——MCP Server 窗口里两者都有显示）：

{
  "mcpServers": {
    "funplay-<project>": {
      "type": "http",
      "url": "http://127.0.0.1:<port>/"
    }
  }
}

{
  "mcpServers": {
    "funplay-<project>": {
      "url": "http://127.0.0.1:<port>/"
    }
  }
}

{
  "mcpServers": {
    "funplay-<project>": {
      "url": "http://127.0.0.1:<port>/"
    }
  }
}

{
  "servers": {
    "funplay-<project>": {
      "type": "http",
      "url": "http://127.0.0.1:<port>/"
    }
  }
}

{
  "mcpServers": {
    "funplay-<project>": {
      "url": "http://127.0.0.1:<port>/"
    }
  }
}

{
  "mcpServers": {
    "funplay-<project>": {
      "type": "http",
      "url": "http://127.0.0.1:<port>/"
    }
  }
}

{
  "mcpServers": {
    "funplay-<project>": {
      "url": "http://127.0.0.1:<port>/"
    }
  }
}

[mcp_servers.funplay-<project>]
url = "http://127.0.0.1:<port>/"

{
  "mcp": {
    "funplay-<project>": {
      "type": "remote",
      "url": "http://127.0.0.1:<port>/",
      "enabled": true
    }
  }
}

# >>> funplay-mcp:funplay-<project> begin (managed by Funplay MCP -- reconfigure from Unity > Funplay > MCP Server)
# Funplay Unity MCP endpoint served by this editor; tools appear as mcp__funplay-<project>__<tool>.
- insert:
    - id: mcp-funplay-<project>
      name: '@deepseek-ai/dsh-mcp-client'
      config:
        serverName: funplay-<project>
        transport: streamable-http
        url: http://127.0.0.1:<port>/
# <<< funplay-mcp:funplay-<project> end

{
  "mcpServers": {
    "funplay-<project>": {
      "serverUrl": "http://127.0.0.1:<port>/"
    }
  }
}

4. 验证连接

先在 AI 客户端里试几个安全请求：

“调用 get_scene_info，告诉我当前打开的是哪个场景。”

“读取 unity://project/context，总结当前编辑器状态。”

“调用 execute_code，返回当前激活场景名。”

如果这些都正常返回，说明 MCP server、resources 和主执行工具都已经连通。

5. 开始构建

打开你的 AI 客户端，试试："创建一个 3D 平台跳跃关卡，包含 5 个浮空平台"

开始前说明

• 这是一个 仅限 Editor 的包，不会向最终构建产物添加运行时代码。
• MCP Server 端口对新工程按工程派生（20000-29999 区间）；从旧版本升级的工程会保留原端口并记为 pin，手填的端口同样是 pin。MCP Server 窗口会显示端口来源与当前实际地址。客户端配置里的条目名按工程目录名命名（例如 funplay-love-town，只保留 ASCII 字母数字），多个工程不再互相覆盖同一个 funplay 条目。两个工程产品名相同时会解析出同一个条目名，此时后配置的那个会自动追加工程哈希，既不会覆盖对方，也不需要用户去开任何开关。
• 本地 MCP Server 配置保存在 UserSettings/FunplayMcpSettings.json。
• v0.6.9 默认 core 精选 40 个工具，覆盖结构化检查与修改、UI 巡检和创建、可恢复的编译准备、统一任务查询、视觉证据、输入和日志。短任务可一次返回结果，get_task 支持有限等待、状态变化后返回和退避提示；execute_code 保留为项目特定逻辑的兜底。full 保留全部 180 个工具，包括原有状态、编译与 Play 接口，以及配置、预览管理和专项诊断。已有自定义暴露列表不会被覆盖，可用 get_tool_capabilities 区分“已实现”和“已暴露”。升级后请通过 Project Skills 更新已安装的内置技能。
• execute_code safety checks 和更严格的文件系统 guard 现在可在 Funplay > MCP Settings 设置默认值，默认开启；它会阻止明显破坏性片段、宽泛的 System.IO 写入、原始文件流、绝对路径、用户/系统目录路径和 ../ 穿越路径，但它不是完整沙箱。客户端仍可在单次调用中用可选 safety_checks 参数显式覆盖。
• 插件 debug 日志默认关闭，也可在 Funplay > MCP Settings 中开启；Warning 和 Error 始终会输出到 Unity Console。
• 所有已暴露的 MCP 工具都会直接执行，不再提供额外的 approval 开关。
• 菜单：Funplay > Check for Updates 可按安装来源自动更新：Git 安装会直接重新拉取，.unitypackage 导入会自动下载并导入最新版。

能力概览

• execute_code 主工具优先 — 核心体验围绕一个内存 C# 执行工具构建，适合复杂编辑器/运行态编排。详见下方 execute_code：内存 C# 执行。
• 默认安全检查 — execute_code 现在有持久化、默认开启的 safety toggle，并包含更严格的文件系统 guard，适合 LM Studio 这类不明显暴露单次参数的客户端
• Play Mode 自动化闭环 — 进入运行模式、模拟键鼠输入、截图、查看日志、验证行为都能在同一 MCP 会话里完成
• 内建项目上下文 — 直接提供项目状态、当前场景、选择对象、编译错误、控制台输出和 MCP 交互记录资源
• 默认聚焦，必要时全量 — 默认 core 工具集更利于 AI 选工具，需要时可切到 full 暴露开发版的全部 180 个工具
• 单 Unity 包落地 — 不需要额外 approval 开关，Unity 侧也不依赖单独 Python 守护进程
• 可扩展 — 支持 Attribute 发现自定义工具，也支持连接外部 MCP 服务

核心特性

• 180 个内置工具 — 覆盖场景编辑、脚本、资产、运行态控制、截图、性能分析、Prompts、Resources、结构化对象定位、SerializedObject 组件编辑、编辑器状态读写、菜单项兜底以及编辑器自动化，共 42 个模块
• 结构化返回 + instanceId 链式调用 — 工具返回 {success, message, data} JSON 并附带稳定的 instanceId，agent 后续直接 by_id 调用，不再受重名困扰
• execute_code 的 IFunplayCommand 模板 — 新模板自动 Undo（ctx.RegisterObjectCreation/Modification/DestroyObject）、结构化日志（ctx.Log/LogWarning/LogError），并把改动列表回传给 agent
• Resources 与 Prompts — 暴露实时项目上下文、场景/选择/错误资源、资源模板，以及常见 Unity 工作流的可复用 MCP Prompt
• 输入模拟 + 截图验证 — 在 Play Mode 中模拟键盘/鼠标，再用 Game View / Scene View 截图验证结果
• 内置更新 — 直接在 Unity 菜单中检查更新，并根据安装方式自动重新拉取 Git 包或导入最新 unitypackage
• 一键客户端配置 — 直接在 Unity 窗口里为 Claude Code、Cursor、Kimi、LM Studio、VS Code、Kiro、Trae、Codex、OpenCode、DeepSeek Harness、Antigravity 等客户端生成 MCP 配置
• 工具暴露控制 — 编辑 core 和 full 各自暴露的具体工具
• 项目 Skills 管理器 — 为支持的 AI 客户端配置项目级 skills，包含内置的 unity-mcp-workflow 与 unity-ui-composition 指引
• 插件设置 — 排查 MCP 连接或工具执行问题时，可开关详细 debug 日志
• 厂商无关 — 兼容任意支持 MCP 的 AI 客户端：Claude Code、Cursor、Kimi Code、LM Studio、Windsurf、Codex、VS Code Copilot 等

execute_code：内存 C# 执行

execute_code 是 Funplay MCP for Unity 的核心工具。AI 写一段 C#，通过 Roslyn 优先的内存编译流程完成编译，并在编辑器线程直接执行——agent 拿到 Unity Editor 与 Runtime 的全套 API，但完全不需要往项目里写文件。

• 零项目落盘编译 —— 优先使用 Unity 自带 Roslyn csc 编译，同时保留内存编译/内存执行流程。Assets/ 下不会多出 .cs 文件，不会触发 domain reload，除非 snippet 自己显式改，否则项目状态不动。
• 运行前自动就绪 —— 每次调用都会先刷新 AssetDatabase 并等待 pending compilation 完成，外部文件编辑会被自动拾取，不需要额外 request_recompile。
• 自动 Undo + 结构化日志（推荐模板） —— 实现 IFunplayCommand，用注入的 ExecutionContext：所有新建/修改/销毁的对象都自动进 editor Undo，改动列表也会回传给 agent。

using UnityEngine;
using UnityEditor;
using Funplay.Editor.Tools.Helpers;
using Funplay.Editor.Tools.Scripting;

public class CommandScript : IFunplayCommand
{
    public void Execute(ExecutionContext ctx)
    {
        var go = GameObject.CreatePrimitive(PrimitiveType.Cube);
        ctx.RegisterObjectCreation(go);          // 自动 Undo + 追踪
        ctx.Log("Created {0}", go.name);
        ctx.ReturnValue = GameObjectSerializer.Describe(go, includeComponents: false);
    }
}

返回里带 { logs, created, modified, destroyed, returnValue }，agent 不用再回查场景就能确认改动。

旧模板（public static string Run()）仍然兼容，适合一次性 inspection snippet——不需要结构化追踪的场景。

什么时候用 execute_code vs 专门工具 —— execute_code 适合多步编排、新颖查询、或者会被拆成 5-10 个细粒度调用的场景，一段 snippet 比一连串小工具更省。要是单字段组件修改、简单选中切换，或者已有专门工具能搞定的，优先用专门工具——对 LLM 调用成本更低、验证更直接。

与 Coplay 的对比

下表基于 Coplay 官方公开 GitHub README 所描述的能力与安装方式进行对比。

Coplay 信息来源：CoplayDev/unity-mcp

与 Unity AI Assistant 的对比

下表对比本仓库与 Unity Technologies 官方包 com.unity.ai.assistant（2026-05 时点 v2.7.0-pre.2）。

长文对比见 Funplay Unity MCP 与 Unity AI Assistant 详细对比。

MCP 能力结构

当前开源包有四层高价值能力：

• Tools — 开发版 full 下共 180 个工具，core 下 40 个高频工具
• Primary execution — execute_code 用于复杂编辑器/运行态编排
• Prompts — 参数化工作流 Prompt：edit_prefab_safely、verify_compilation、enter_play_and_recover、wire_serialized_references、create_playable_prototype。项目可通过根目录下的 mcp-prompts/*.md 注册专属 Prompt。
• Resources — 项目上下文、场景摘要、选择状态、编译错误、控制台错误、MCP 交互记录，以及按对象/组件/资源路径展开的模板资源

项目 Prompt

项目 Prompt 文件使用轻量、无额外依赖的 front-matter 格式，后面跟随工作流正文：

---
name: validate_activity
description: Open and validate a project activity.
arguments: activity_key(required), theme_id
---
Open activity {activity_key} with theme {theme_id}, then validate its runtime state.

Prompt 名称和参数名必须匹配 [a-z][a-z0-9_-]{0,63}。prompts/get 会拒绝缺失的必填参数、未知参数和非字符串参数；未提供的可选参数占位符会替换为空字符串。定义会在 MCP Server 启动时缓存，因此修改 Prompt 文件后需重启 Server 或触发一次 Unity 域重载。

内置工具

v0.6.9 提供 180 个工具函数，覆盖 42 个模块，默认暴露其中 40 个高频工具。

新增 UI 工作流包括：prepare_editor 持久任务、audit_ui 只读巡检、组件属性查询和 Sprite 关联检查、统一截图/输入坐标、项目级 TMP/字体材质/预制体/输入模块默认值、录屏动作标记与关键帧提取，以及可恢复的预览会话。详见 完整工作流指南 和 实现与验证清单。两项内置 skills 也已同步这些规则，仍为 built-in；已有安装可通过 Project Skills 更新。

📊 完整的 Profiler 工具参考、实现细节、已知限制和测试报告见 PROFILER_TOOLS_CN.md。

录制 Game View 视频

默认 core 工具集中的 record_game_view 可将 UI 动画、转场和连续操作录成一段无音轨 MP4，用于视觉检查。使用 Unity 自带的 MediaEncoder，不需要安装 Recorder 包或外部编码器。

1. 进入 Play Mode，等待域重载恢复，并打开 Game 标签页使其正常渲染。
2. 调用 record_game_view，参数为 {"action":"start","duration_seconds":10,"fps":15,"max_dimension":1280}，保留返回的 recording_id。
3. 开始调用立即返回，可在录制期间继续模拟输入和操作；达到时长上限后自动停止。
4. 使用 {"action":"status","recording_id":"<id>"} 查询状态。若要提前结束，调用 action:"stop"，然后继续查询直至文件完成封装。
5. 只有 ready:true 时才读取返回的本地 path。MCP 响应不会内嵌视频数据；远程客户端需要另行获得 Unity 所在机器的文件访问能力。

视频采用唯一文件名，保存在 <UnityProject>/Library/FunplayMcp/Recordings/，不会自动删除。开始录制可设置 1–120 秒、1–60 目标 FPS，以及 128–1920 像素的最长边；保持宽高比、不放大原画面，并对齐到编码所需的偶数尺寸。状态还包含实际帧数、经过时间、结束原因、文件大小和错误信息。查询或停止时携带录制 ID，可避免误操作新一段录制。

目前支持具有图形设备的 macOS / Windows Unity Editor，且必须处于 Play Mode；暂不录音。画面来自已经渲染的 Game View，包含 Overlay UI，不额外重绘场景相机。录制时保持 Game 标签页渲染，不要改变其分辨率：隐藏、关闭标签页或改变渲染分辨率会结束录制并报错，避免录入旧画面或拉伸画面。退出 Play Mode 会封装视频；脚本重编译或域重载会提前封装，并在编辑器会话中保留 interrupted 状态。无论结束原因如何，都以 ready:true 为可读取条件。慢帧会保留真实时间戳，但录制本身有开销，不能用于帧精确的性能测量。

添加自定义工具

通过简单的 Attribute 标注即可创建自定义工具：

using System.ComponentModel;

[ToolProvider("MyTools")]
public static class MyCustomTools
{
    [Description("Spawns enemies at random positions in the scene")]
    public static string SpawnEnemies(
        [ToolParam("Number of enemies to spawn", Required = true)] int count,
        [ToolParam("Prefab path in Assets")] string prefabPath)
    {
        // Your implementation here
        return $"Spawned {count} enemies";
    }
}

方法会被自动发现，名称转换为 snake_case（spawn_enemies），并通过 MCP 自动生成 JSON Schema 定义暴露给 AI。

架构

MCP Server (HTTP JSON-RPC 2.0)
    └─ MCPRequestHandler (协议处理)
        └─ MCPExecutionBridge
            └─ FunctionInvokerController (反射式调用)
                └─ Tool Functions (180 个内置工具，42 个模块)

外部 AI 客户端 → HTTP 请求 → MCPRequestHandler → MCPExecutionBridge → FunctionInvokerController → 工具方法

环境要求

• Unity 2022.3 或更高版本
• .NET / Mono + Newtonsoft.Json

参与贡献

欢迎贡献！提交 PR 前请阅读 贡献指南。

许可证

MIT — 可自由使用、修改、分发，也可集成到商业或开源项目中。