1. 为什么要在 Unity 里接 MCP：AI 改场景的真实痛点
如果你已经在用 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 Server，Server 直接在主线程上访问 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 接上 MCP
Funplay 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 Key，Base URL 就是http://127.0.0.1:8765/。但你的 AI 客户端本身需要配置模型访问，这部分如果你用的是 TaoToken 这类聚合服务，Base URL 填https://taotoken.net/api，Key 在控制台生成，Model ID 按你选的模型填。两者是独立的：MCP 配置负责让客户端“看见”Unity，模型配置负责让客户端“思考”。
如果你用 Cline 或带 MCP 的 VS Code 插件，配置结构类似，核心就是mcpServers下加一个funplay，URL 指向本地 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 注册了所有改动，按一下Ctrl+Z这 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_code，AI 直接把这段逻辑作为参数发过来，跑完场景里就是排好序的状态，没有任何脚本残留。实际开发里你会发现，很多看似需要“加一个工具”的需求，其实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_recompile），Unity 会丢弃这个请求。插件本身在这种情况下会返回一个明确的错误，所以 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/api，Key 在控制台生成后要完整粘贴，别带空格。如果 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/api，Key 在控制台生成。MCP 这边保持本地 8765 不变，两者互不干扰。想先验证模型连通性，可以去模型对话页面发一条测试消息；接入文档里有各客户端的详细配置示例；API Keys 页面管理你的 Key。
后面会陆续写一些更具体的使用模式——比如怎么用 AI 批量调整美术资源、怎么让 AI 帮你跑 PlayMode 回归、怎么写自己的[ToolProvider]扩展更多工具。如果你在用过程中遇到具体场景搞不定，欢迎在评论或 issue 里抛过来。
