1. 为什么要在 Unity 里接 MCPAI 改场景的真实痛点如果你已经在用 Claude Code、Cursor、Codex 这类 AI 客户端写代码会发现一个很割裂的地方AI 能帮你写.cs脚本、能改配置文件、能跑命令行但每次切回 Unity 编辑器调场景、改组件、点 Play 验证还是得手动来。AI 看不到你当前打开的是哪个场景不知道 Hierarchy 里选中了谁更不知道 Inspector 里那个Rigidbody.mass现在是多少。这就是 funplay-unity-mcp 要解决的问题。它是一个开源的 Unity Editor 插件MIT 许可运行起来后会在 Unity 进程内监听一个本地 HTTP 端口把场景、Prefab、Asset、PlayMode 状态以 MCP 协议暴露给外部 AI 客户端。客户端可以列出工具、调用工具、读资源——也就是说“在场景里创建 6 个浮空平台并随机摆放”“把所有 Enemy_ 开头的对象改成 trigger”“进入 PlayMode 截一张图给我”这类操作可以直接用自然语言交给 AI。它适合谁适合已经在用 AI 写代码、但被 Unity 编辑器手动操作卡住节奏的独立开发者和小团队。你不需要懂 MCP 协议细节也不需要写编辑器扩展装完插件、起服务、连客户端就能让 AI 真正“动手”改你的场景。整体调用链是这样的AI 客户端通过 HTTP / JSON-RPC 连到跑在 Unity 进程内的 Funplay MCP ServerServer 直接在主线程上访问 Scene、Prefab、Asset、PlayMode。因为 server 就在 Unity 进程内部它拥有完整的 Unity Editor API——SceneView、PrefabStage、AssetDatabase、PlayMode 状态都是同进程访问没有跨进程 IPC也不需要额外的守护进程。这一点很关键同进程意味着延迟低、状态一致不会出现“AI 以为改了但编辑器没刷新”的错位。环境要求也不复杂Unity 2022.3 或更高版本已在 6000.x 上验证macOS / Windows / Linux 编辑器都可以任意一款支持 MCP 的 AI 客户端都行比如 Claude Code、Cursor、VS Code、Codex、Trae、Kiro、Windsurf 等。网络层面它仅监听127.0.0.1:8765不会暴露到外网。整个包是 Editor-only 的asmdef 里includePlatforms限定为 Editor构建出去的游戏不会带进任何运行时代码这点可以放心。我试过在一个 2022.3 的 2D 项目里接这套流程从装插件到 AI 真的在 Hierarchy 里生成对象大概十几分钟。下面把完整路径拆开写你可以照着复现。2. 前置准备装好 funplay-unity-mcp 并启动 MCP Server先说安装。推荐用 UPM Git URL 安装最简单。打开 Unity 编辑器菜单Window → Package Manager左上角→Add package from git URL填入https://github.com/FunplayAI/funplay-unity-mcp.git回车等 Package Manager 拉完。完成后菜单栏会多出一个Funplay顶级菜单。如果不想走 Git可以去仓库 Releases 页下载对应版本的.unitypackage文件离线导入效果一致。装完之后要启动 MCP Server。菜单点开Funplay → MCP Server会出来一个面板点Start。服务起来后下方Recent Activity区域会开始记录最近发生的工具调用。这个面板就是你和 AI 之间发生过什么事的“控制台”排错时非常有用。默认端口8765如果被占用可以在面板里改。改完之后插件会自动按新端口重启 transport不需要你操心。这里有个细节端口改了之后后面客户端配置里的 URL 也要同步改否则会连不上。校验服务是否真的起来了开一个终端curl -X POST http://127.0.0.1:8765/ \ -H Content-Type: application/json \ -d {jsonrpc:2.0,id:1,method:tools/list,params:{}}应该看到一个很长的 JSON里面包含一堆工具定义。这就是 MCP 客户端马上要看到的工具清单。如果返回的是连接拒绝说明 Server 没起来或者端口不对如果返回空或者报错检查一下 Unity Console 有没有异常。这一步是整个流程的地基。很多人卡在“客户端连不上”其实八成是 Server 没起或者端口对不上。建议每次开 Unity 项目后先确认Funplay → MCP Server面板里状态是 Running再去做客户端配置。另外提一句如果你用的是 Claude Code菜单里还有一项Funplay → Project Skills。点开把unity-mcp-workflow装到当前项目Claude Code 之后会自动按这套工作流来用 Funplay 工具——比如优先用结构化的工具读编辑器状态而不是瞎写代码、改完之后回读校验、合理使用instanceId等等。这是把“怎么有效地用这套工具”的经验沉淀进去了第一次用强烈推荐装上。3. 可复制配置把 Claude Code / Cursor / Codex 接上 MCPFunplay MCP Server 面板里有一个“一键 MCP 配置”按钮选你用的客户端插件会自动把配置写进对应文件。这是最省事的路径。但如果你想手动写或者想搞清楚配置到底长什么样下面是几种主流客户端的最小可行配置。Claude Code配置位置用户级~/.claude.json或项目级.mcp.json。{ mcpServers: { funplay: { type: http, url: http://127.0.0.1:8765/ } } }写完重启 Claude Code新对话里输入/mcp能看到funplay在列表里就成了。Cursor打开Cursor Settings → MCP添加一项{ mcpServers: { funplay: { url: http://127.0.0.1:8765/ } } }Codex (CLI)Codex CLI 配置在~/.config/codex/config.toml[mcp_servers.funplay] url http://127.0.0.1:8765/这里要强调三件套Base URL、Key、Model ID。funplay-unity-mcp 本身是本地 HTTP 服务不需要 API KeyBase URL 就是http://127.0.0.1:8765/。但你的 AI 客户端本身需要配置模型访问这部分如果你用的是 TaoToken 这类聚合服务Base URL 填https://taotoken.net/apiKey 在控制台生成Model ID 按你选的模型填。两者是独立的MCP 配置负责让客户端“看见”Unity模型配置负责让客户端“思考”。如果你用 Cline 或带 MCP 的 VS Code 插件配置结构类似核心就是mcpServers下加一个funplayURL 指向本地 8765。CC Switch 这类工具切换配置时注意别把 MCP 段覆盖掉。接好之后客户端这边在新对话里就能直接看到 Funplay 提供的工具。你可以先让 AI 列一下工具清单确认它真的读到了。如果客户端里看不到 funplay先检查 JSON/TOML 语法有没有写错再检查 Server 是否 Running最后检查端口是否一致。4. 验证请求第一次让 AI 真正改场景这一步是分水岭之前所有配置都是为了让 AI “看见” Unity现在让它“动手”。打开任意 Unity 项目新建或打开一个空场景。然后在 AI 客户端里输入在当前场景里以 (0,0,0) 为中心、半径 3 的圆周上等距创建 6 个 Cube命名为 Ring_0 到 Ring_5每个染上不同的颜色。AI 客户端会调用 funplay 暴露的工具——多半是execute_code——把这段意图翻译成一段 C# 编辑器代码立即在你的 Unity 编辑器里执行。整个过程你不需要切回 Unity但切回去之后 Hierarchy 里就会真的躺着 6 个 Cube。而且因为插件用 Undo API 注册了所有改动按一下CtrlZ这 6 个 Cube 一次性消失完全符合 Unity 的撤销直觉。这一点很重要AI 改场景不是“不可逆的魔法”你随时可以撤。如果你要的是更精细的工作流例子比如“把当前选中的 GameObject 的 Rigidbody.mass 改成 2.5”“把 Assets/Prefabs/Enemy.prefab 打开给它加一个 BoxCollider 设成 trigger保存”“把当前场景里所有 Light 的强度乘以 0.5”“进入 PlayMode 跑 3 秒截一张 Game 视图的图给我”这些都不需要你手动写一行编辑器脚本AI 客户端会按需要调用合适的工具组合完成。核心工具是execute_code。如果你看过工具清单会发现里面有 80 多个工具但其中最值钱的就一个execute_code。它接受一段 C# 片段在 Unity 进程内通过 CodeDom 反射就地编译执行——不写.cs文件不触发 domain reload。这意味着 AI 可以为你当前这一个任务“临时写一个编辑器工具”跑完即弃。举个例子“把场景里所有 tag 为 Enemy 的对象按 X 坐标排序后重新命名为 Enemy_01…”这种需求传统做法是写一段 EditorWindow 脚本放进Assets/Editor/跑完再删用execute_codeAI 直接把这段逻辑作为参数发过来跑完场景里就是排好序的状态没有任何脚本残留。实际开发里你会发现很多看似需要“加一个工具”的需求其实execute_code已经覆盖了。Play Mode 闭环也值得单独说。游戏开发跟普通后端开发最大的区别是很多事情只有进入 Play Mode 才能验证。funplay 把这个闭环也连上了。AI 可以调用enter_play_mode/exit_play_mode控制运行状态模拟键盘鼠标输入基于 InputSystem截 Game / Scene 视图的图直接以图片形式返回给客户端读取 Console 错误和 Profiler 性能数据。这意味着 AI 不仅能改场景还能“自己跑一遍验证”。比如调一个跳跃手感AI 可以改 Rigidbody 参数 → 进入 PlayMode → 模拟按空格 → 截图返回 → 根据观察的轨迹再调参数。这就是闭环。一个注意点在 Play Mode 运行期间不要请求重编request_recompileUnity 会丢弃这个请求。插件本身在这种情况下会返回一个明确的错误所以 AI 通常会先退出 Play Mode 再做需要重编的事。5. 常见报错排查401、local proxy failed、reading choices、OAuth排错这块我踩过的坑不少下面按真实报错对照着写。401 Unauthorized如果你在客户端里看到 401先分清是 MCP 层还是模型层。funplay-unity-mcp 本地服务不需要 Key所以 401 基本来自模型访问。检查你的 Base URL 和 Key 是否匹配比如用 TaoToken 的话 Base URL 是https://taotoken.net/apiKey 在控制台生成后要完整粘贴别带空格。如果 Key 过期或额度用完也会 401。local proxy failed / connection refused这个通常是 MCP Server 没起来或者端口对不上。先去Funplay → MCP Server面板确认状态是 Running再用 curl 测一下127.0.0.1:8765。如果 curl 通但客户端不通检查客户端配置里的 URL 是不是写成了localhost而系统解析到了 IPv6改成127.0.0.1通常能解决。另外有些客户端对type: http字段敏感Claude Code 需要Cursor 可以省略按上面给的配置来。reading choices / 解析响应失败这类报错多半是客户端拿到了非 JSON 响应。可能是端口被别的服务占了返回了 HTML 或空内容。换个端口同步改客户端配置再重启 Server。也有可能是 Unity 正在编译Server 短暂不可用等编译完再试。OAuth / 认证流程卡住有些客户端默认走 OAuth 流程但本地 MCP 是直连 HTTP不需要 OAuth。检查配置里有没有多余的 auth 字段删掉。如果是 Codex CLI确认config.toml里只写了url没有加 token 相关字段。工具调用成功但场景没变先看Recent Activity面板有没有记录。如果有记录但场景没变可能是 AI 调用了只读工具而不是execute_code。在提示词里明确说“用 execute_code 执行”或者让 AI 先列出可用工具再操作。另外确认你当前打开的场景就是 AI 操作的那个场景多场景编辑时容易搞混。PlayMode 期间重编失败前面提过Play Mode 运行期间request_recompile会被 Unity 丢弃。让 AI 先exit_play_mode再重编。如果 AI 没意识到你可以在提示词里加一句“先退出 PlayMode 再改代码”。排错的核心思路是分层先确认 Server 活着再确认客户端连上了再确认工具被调用了最后确认 Unity 侧真的执行了。每一层都有对应的检查点别一上来就怀疑插件本身。6. 把 AI 改场景变成日常下一步怎么走到这一步你已经完成了插件装上、服务跑起来、AI 客户端连上、第一次让 AI 改了场景、知道execute_code是核心、Play Mode 闭环可用。接下来可以做的几件事。一是把常用操作沉淀成提示词模板比如“批量重命名”“批量改组件”“跑回归截图”每次直接调用不用重新描述。二是如果你用 Claude Code把unity-mcp-workflowskill 装上它会自动按最佳实践调用工具减少你反复纠正的成本。三是关注execute_code的边界它虽然强但涉及复杂资产依赖时还是用结构化工具更稳比如打开 Prefab 用专门的工具而不是硬写代码。如果你在模型访问上需要统一管理可以用 TaoToken 的 Coding Plan 把编码类请求集中起来Base URL 填https://taotoken.net/apiKey 在控制台生成。MCP 这边保持本地 8765 不变两者互不干扰。想先验证模型连通性可以去模型对话页面发一条测试消息接入文档里有各客户端的详细配置示例API Keys 页面管理你的 Key。后面会陆续写一些更具体的使用模式——比如怎么用 AI 批量调整美术资源、怎么让 AI 帮你跑 PlayMode 回归、怎么写自己的[ToolProvider]扩展更多工具。如果你在用过程中遇到具体场景搞不定欢迎在评论或 issue 里抛过来。