1. 为什么要在 Unity Editor 里接 AI 客户端如果你做 Unity 开发大概率经历过这种循环在编辑器里点半天创建一个测试场景手动改十几个 GameObject 的组件属性切到 PlayMode 看一眼效果截图退出再改。这些操作本身不难但极其消耗注意力。把 Claude Code、Cursor、Codex 这类支持 MCP 的 AI 客户端接到 Unity Editor 上意味着你可以用自然语言描述意图让 AI 直接驱动编辑器完成这些重复动作。Funplay Unity MCP 是一个运行在 Unity Editor 进程内部的 HTTP MCP server它把编辑器和 PlayMode 的状态暴露成 MCP 协议下的工具与资源。外部 AI 客户端通过标准 JSON-RPC 调用就能驱动编辑器不需要额外的桥接进程也不需要写一行 Editor 扩展代码。它适合三类人一是想用 AI 加速场景搭建和批量改属性的 Unity 开发者二是已经在用 Claude Code 或 Cursor 写代码、希望把能力延伸到编辑器内的团队三是想研究 MCP 协议在游戏引擎侧落地方式的工程师。这篇文章聚焦配置流程本身给出 Claude Code、Cursor、Codex 三种客户端的可复制配置骨架以及逐项验证连接是否生效的操作步骤。整个过程围绕一个核心事实展开所有客户端共用同一个 HTTP endpoint差异只在配置文件位置和字段命名。2. 前置准备Unity 侧安装与启动在配置任何 AI 客户端之前Unity 这一侧必须先跑起来。Funplay Unity MCP 是 Editor-only 的包includePlatforms限定为[Editor]不会向最终构建产物注入任何运行时代码这一点对发布流程没有影响。环境要求不复杂Unity 2022.3 或更高版本macOS / Windows / Linux 编辑器都可以网络只监听本地127.0.0.1:8765不暴露到外网。AI 客户端侧只要是支持 MCP 的即可Claude Code、Cursor、VS Code、Codex、Trae、Kiro、Windsurf 都在支持范围内。安装走 UPM Git URL 最直接。打开 Unity 编辑器菜单Window → Package Manager → → Add package from git URL填入仓库地址https://github.com/FunplayAI/funplay-unity-mcp.gitPackage Manager 拉取完成后菜单栏会出现 Funplay 顶级菜单。如果你偏好离线安装仓库 Releases 页面也提供对应版本的.unitypackage文件导入效果一致。安装完成后打开Funplay → MCP Server窗口点击 Start。服务启动后会在http://127.0.0.1:8765/上监听窗口下方会显示当前会话的 Recent Activity 记录。这里有两个可调项值得注意端口设置在Funplay → MCP Server窗口里改工具集在Funplay → Tool Exposure里编辑。默认的 core profile 暴露 29 个高频工具包括execute_code、运行模式控制、输入模拟、截图、性能检查、日志、编译检查、结构化对象定位与组件编辑、编辑器状态读写以及execute_menu_item兜底入口。需要完整 91 个工具时切到 full。注意server 运行在 Editor 内部所有调用直接拥有完整的 Unity API 权限包括 SceneView、PrefabStage、AssetDatabase、PlayMode 状态。这也是它不需要额外桥接进程的原因。3. 三种客户端的可复制配置推荐路径是直接在Funplay → MCP Server窗口里点击一键 MCP 配置选择目标客户端后插件会自动写入对应的配置文件。但理解手动配置的骨架仍然有价值尤其是当你要在多台机器上复现或者需要排查自动写入失败的情况。下面给出三种主流客户端的最小可行示例。3.1 Claude Code 配置Claude Code 的 MCP 配置位于用户级~/.claude.json也可以放在项目级.mcp.json。JSON 结构如下{ mcpServers: { funplay: { type: http, url: http://127.0.0.1:8765/ } } }写完保存Claude Code 下一次启动会话时自动连接。你可以在 Claude Code 中执行/mcp查看连接状态。这里type字段显式声明为http是因为 Claude Code 同时支持 stdio 和 http 两种传输方式不写清楚容易走错分支。3.2 Cursor 配置Cursor 的 MCP 配置位于~/.cursor/mcp.json结构比 Claude Code 更简洁不需要type字段{ mcpServers: { funplay: { url: http://127.0.0.1:8765/ } } }保存后打开Cursor Settings → MCP应该能看到 funplay 处于已连接状态。如果显示未连接先确认 Unity 侧的 MCP Server 窗口是 Start 状态再检查端口是否被占用。3.3 Codex 配置Codex 使用 TOML 格式配置位于~/.codex/config.toml。注意这里的段名是mcp_servers和 JSON 客户端的mcpServers拼写不同[mcp_servers.funplay] url http://127.0.0.1:8765/保存后重启 Codex CLI 即可生效。TOML 对缩进不敏感但段名必须准确写错会导致整个配置被忽略。3.4 配置格式速查三种客户端的差异集中在文件位置和字段命名上endpoint 完全一致。下表可以当作速查卡客户端配置文件格式关键字段Claude Code~/.claude.jsonJSONmcpServers.funplay.typehttp, urlCursor~/.cursor/mcp.jsonJSONmcpServers.funplay.urlCodex~/.codex/config.tomlTOML[mcp_servers.funplay]段下urlVS Codesettings / mcp configJSONservers.funplay.typehttp, urlTrae / Kiro / Windsurf各自 MCP 配置JSONmcpServers.funplay.url所有客户端共用同一个 HTTP endpoint迁移或并存不需要改动 Unity 项目本身。这一点在团队协作里很实用有人用 Cursor有人用 Claude Code只要各自配好本地文件指向同一个127.0.0.1:8765即可。4. 验证连接是否生效配置写完不代表连通。下面三类调用覆盖 server 的核心能力面建议逐项跑一遍任何一项失败都能定位到具体环节。4.1 工具调用验证在客户端里发起调用 get_scene_info告诉我当前打开的是哪个场景。正常情况下会返回{success: true, data: { name, path, isLoaded, ... }}。这一步验证的是tools/list和tools/call链路是否通。如果返回工具不存在说明客户端没有成功拉取工具清单回到第 3 节检查配置。4.2 资源读取验证接着发起读取 MCP resource unity://project/context总结当前编辑器状态。unity://project/context是 Funplay Unity MCP 暴露的实时项目上下文资源包含项目名、当前场景、选中对象、最近编译错误等信息。这一步验证的是 resources 通道和工具调用走的是不同的协议分支所以需要单独测。4.3 内存代码执行验证最后测中心工具execute_code调用 execute_code返回当前激活场景名。这个工具允许客户端提交任意 C# 代码片段在 Editor 内存中编译执行无需写文件、无需触发 domain reload。它的执行链路是客户端发送 C# 片段MCP server 用 CodeDom 在内存编译反射调用IFunplayCommand最后返回结构化 JSON。复杂的多步操作通常用一次execute_code调用就能完成。如果三类调用都正常返回说明 server、resources 与主执行工具均已连通。此时你可以尝试更贴近实际工作的指令比如「创建 5 个浮空平台」或「把所有 Enemy_ 开头的 GameObject 改成 trigger」观察编辑器里的实时变化。5. 本篇常见错误排查配置过程中最容易卡住的几个点基本都集中在端口、domain reload 和工具注册三处。端口 8765 被占用是最常见的。表现是 Unity 侧 Start 失败或者客户端连接超时。解决办法是在Funplay → MCP Server窗口改端口改完记得把客户端配置里的 URL 同步更新三处配置都要改漏一处就连不上。Domain reload 中断调用也经常遇到。Unity 在脚本编译时会重启脚本域正在执行的 MCP 请求会被打断。Funplay Unity MCP 的DomainReloadHandler会在 reload 后保留中断状态客户端可以调用get_reload_recovery_status拉取摘要。日常工作流中不需要手动处理但如果你的指令执行到一半突然没响应先查这个状态再重试。外部脚本编辑后工具行为没变通常是因为工具注册还没刷新。如果你在 IDE 中编辑了Editor/下的 C# 脚本需要让 Unity 重新编译并刷新工具注册。调用request_recompile工具可以触发 import compile reload 全流程并等待完成比手动切窗口点刷新可靠。工具列表里看不到新工具是工具方法增删后的注册问题。ToolRegistry在 domain reload 时会自动重新扫描如果列表确实没刷新可以在 Unity 内重启 server或调用客户端的刷新 MCP 服务功能。另外 core 和 full profile 的工具数量不同如果你在找某个专用工具却找不到先确认当前是不是 core profile切到 full 再试。提示core profile 暴露 29 个工具目的是降低 AI 客户端在工具选择阶段的噪音。大多数 LLM 面对 90 工具时容易选错或选漏29 个高频工具配合execute_code兜底已经能覆盖绝大多数场景。只有当工作流强依赖某个具体工具比如 SerializedProperty 的细粒度读写才需要切到 full。6. 把 AI 客户端接到编辑器之后配置这件事本身不复杂真正改变工作方式的是接入之后。以前要写 Editor 扩展才能做的编辑器自动化现在降级成用自然语言描述意图。Funplay Unity MCP 在协议侧选择标准 HTTP MCP配置成本停留在写一段 JSON 或 TOML客户端的迁移与并存不需要改动 Unity 项目本身。如果你在配置 Claude Code、Cursor 或 Codex 的过程中需要确认模型侧的调用行为可以先用模型对话快速验证指令语义是否符合预期再落到编辑器里执行。长期做编码和 Agent 工作流的团队可以考虑 Coding Plan 把调用额度固定下来避免频繁切换配置。接入过程中遇到鉴权或 endpoint 相关问题API Keys 页面和接入文档里有完整的字段说明对照检查比反复重启客户端更快。仓库地址是 FunplayAI/funplay-unity-mcpMIT 协议。完整接入流程可以压缩成一条链路UPM 安装Funplay → MCP Server启动:8765选择客户端写入配置用/mcp或设置面板验证最后跑工具调用、资源读取和execute_code三类测试。跑通之后剩下的就是你想让编辑器做什么了。
Claude Code / Cursor / Codex 接 Unity Editor：Funplay Unity MCP 配置实战
1. 为什么要在 Unity Editor 里接 AI 客户端如果你做 Unity 开发大概率经历过这种循环在编辑器里点半天创建一个测试场景手动改十几个 GameObject 的组件属性切到 PlayMode 看一眼效果截图退出再改。这些操作本身不难但极其消耗注意力。把 Claude Code、Cursor、Codex 这类支持 MCP 的 AI 客户端接到 Unity Editor 上意味着你可以用自然语言描述意图让 AI 直接驱动编辑器完成这些重复动作。Funplay Unity MCP 是一个运行在 Unity Editor 进程内部的 HTTP MCP server它把编辑器和 PlayMode 的状态暴露成 MCP 协议下的工具与资源。外部 AI 客户端通过标准 JSON-RPC 调用就能驱动编辑器不需要额外的桥接进程也不需要写一行 Editor 扩展代码。它适合三类人一是想用 AI 加速场景搭建和批量改属性的 Unity 开发者二是已经在用 Claude Code 或 Cursor 写代码、希望把能力延伸到编辑器内的团队三是想研究 MCP 协议在游戏引擎侧落地方式的工程师。这篇文章聚焦配置流程本身给出 Claude Code、Cursor、Codex 三种客户端的可复制配置骨架以及逐项验证连接是否生效的操作步骤。整个过程围绕一个核心事实展开所有客户端共用同一个 HTTP endpoint差异只在配置文件位置和字段命名。2. 前置准备Unity 侧安装与启动在配置任何 AI 客户端之前Unity 这一侧必须先跑起来。Funplay Unity MCP 是 Editor-only 的包includePlatforms限定为[Editor]不会向最终构建产物注入任何运行时代码这一点对发布流程没有影响。环境要求不复杂Unity 2022.3 或更高版本macOS / Windows / Linux 编辑器都可以网络只监听本地127.0.0.1:8765不暴露到外网。AI 客户端侧只要是支持 MCP 的即可Claude Code、Cursor、VS Code、Codex、Trae、Kiro、Windsurf 都在支持范围内。安装走 UPM Git URL 最直接。打开 Unity 编辑器菜单Window → Package Manager → → Add package from git URL填入仓库地址https://github.com/FunplayAI/funplay-unity-mcp.gitPackage Manager 拉取完成后菜单栏会出现 Funplay 顶级菜单。如果你偏好离线安装仓库 Releases 页面也提供对应版本的.unitypackage文件导入效果一致。安装完成后打开Funplay → MCP Server窗口点击 Start。服务启动后会在http://127.0.0.1:8765/上监听窗口下方会显示当前会话的 Recent Activity 记录。这里有两个可调项值得注意端口设置在Funplay → MCP Server窗口里改工具集在Funplay → Tool Exposure里编辑。默认的 core profile 暴露 29 个高频工具包括execute_code、运行模式控制、输入模拟、截图、性能检查、日志、编译检查、结构化对象定位与组件编辑、编辑器状态读写以及execute_menu_item兜底入口。需要完整 91 个工具时切到 full。注意server 运行在 Editor 内部所有调用直接拥有完整的 Unity API 权限包括 SceneView、PrefabStage、AssetDatabase、PlayMode 状态。这也是它不需要额外桥接进程的原因。3. 三种客户端的可复制配置推荐路径是直接在Funplay → MCP Server窗口里点击一键 MCP 配置选择目标客户端后插件会自动写入对应的配置文件。但理解手动配置的骨架仍然有价值尤其是当你要在多台机器上复现或者需要排查自动写入失败的情况。下面给出三种主流客户端的最小可行示例。3.1 Claude Code 配置Claude Code 的 MCP 配置位于用户级~/.claude.json也可以放在项目级.mcp.json。JSON 结构如下{ mcpServers: { funplay: { type: http, url: http://127.0.0.1:8765/ } } }写完保存Claude Code 下一次启动会话时自动连接。你可以在 Claude Code 中执行/mcp查看连接状态。这里type字段显式声明为http是因为 Claude Code 同时支持 stdio 和 http 两种传输方式不写清楚容易走错分支。3.2 Cursor 配置Cursor 的 MCP 配置位于~/.cursor/mcp.json结构比 Claude Code 更简洁不需要type字段{ mcpServers: { funplay: { url: http://127.0.0.1:8765/ } } }保存后打开Cursor Settings → MCP应该能看到 funplay 处于已连接状态。如果显示未连接先确认 Unity 侧的 MCP Server 窗口是 Start 状态再检查端口是否被占用。3.3 Codex 配置Codex 使用 TOML 格式配置位于~/.codex/config.toml。注意这里的段名是mcp_servers和 JSON 客户端的mcpServers拼写不同[mcp_servers.funplay] url http://127.0.0.1:8765/保存后重启 Codex CLI 即可生效。TOML 对缩进不敏感但段名必须准确写错会导致整个配置被忽略。3.4 配置格式速查三种客户端的差异集中在文件位置和字段命名上endpoint 完全一致。下表可以当作速查卡客户端配置文件格式关键字段Claude Code~/.claude.jsonJSONmcpServers.funplay.typehttp, urlCursor~/.cursor/mcp.jsonJSONmcpServers.funplay.urlCodex~/.codex/config.tomlTOML[mcp_servers.funplay]段下urlVS Codesettings / mcp configJSONservers.funplay.typehttp, urlTrae / Kiro / Windsurf各自 MCP 配置JSONmcpServers.funplay.url所有客户端共用同一个 HTTP endpoint迁移或并存不需要改动 Unity 项目本身。这一点在团队协作里很实用有人用 Cursor有人用 Claude Code只要各自配好本地文件指向同一个127.0.0.1:8765即可。4. 验证连接是否生效配置写完不代表连通。下面三类调用覆盖 server 的核心能力面建议逐项跑一遍任何一项失败都能定位到具体环节。4.1 工具调用验证在客户端里发起调用 get_scene_info告诉我当前打开的是哪个场景。正常情况下会返回{success: true, data: { name, path, isLoaded, ... }}。这一步验证的是tools/list和tools/call链路是否通。如果返回工具不存在说明客户端没有成功拉取工具清单回到第 3 节检查配置。4.2 资源读取验证接着发起读取 MCP resource unity://project/context总结当前编辑器状态。unity://project/context是 Funplay Unity MCP 暴露的实时项目上下文资源包含项目名、当前场景、选中对象、最近编译错误等信息。这一步验证的是 resources 通道和工具调用走的是不同的协议分支所以需要单独测。4.3 内存代码执行验证最后测中心工具execute_code调用 execute_code返回当前激活场景名。这个工具允许客户端提交任意 C# 代码片段在 Editor 内存中编译执行无需写文件、无需触发 domain reload。它的执行链路是客户端发送 C# 片段MCP server 用 CodeDom 在内存编译反射调用IFunplayCommand最后返回结构化 JSON。复杂的多步操作通常用一次execute_code调用就能完成。如果三类调用都正常返回说明 server、resources 与主执行工具均已连通。此时你可以尝试更贴近实际工作的指令比如「创建 5 个浮空平台」或「把所有 Enemy_ 开头的 GameObject 改成 trigger」观察编辑器里的实时变化。5. 本篇常见错误排查配置过程中最容易卡住的几个点基本都集中在端口、domain reload 和工具注册三处。端口 8765 被占用是最常见的。表现是 Unity 侧 Start 失败或者客户端连接超时。解决办法是在Funplay → MCP Server窗口改端口改完记得把客户端配置里的 URL 同步更新三处配置都要改漏一处就连不上。Domain reload 中断调用也经常遇到。Unity 在脚本编译时会重启脚本域正在执行的 MCP 请求会被打断。Funplay Unity MCP 的DomainReloadHandler会在 reload 后保留中断状态客户端可以调用get_reload_recovery_status拉取摘要。日常工作流中不需要手动处理但如果你的指令执行到一半突然没响应先查这个状态再重试。外部脚本编辑后工具行为没变通常是因为工具注册还没刷新。如果你在 IDE 中编辑了Editor/下的 C# 脚本需要让 Unity 重新编译并刷新工具注册。调用request_recompile工具可以触发 import compile reload 全流程并等待完成比手动切窗口点刷新可靠。工具列表里看不到新工具是工具方法增删后的注册问题。ToolRegistry在 domain reload 时会自动重新扫描如果列表确实没刷新可以在 Unity 内重启 server或调用客户端的刷新 MCP 服务功能。另外 core 和 full profile 的工具数量不同如果你在找某个专用工具却找不到先确认当前是不是 core profile切到 full 再试。提示core profile 暴露 29 个工具目的是降低 AI 客户端在工具选择阶段的噪音。大多数 LLM 面对 90 工具时容易选错或选漏29 个高频工具配合execute_code兜底已经能覆盖绝大多数场景。只有当工作流强依赖某个具体工具比如 SerializedProperty 的细粒度读写才需要切到 full。6. 把 AI 客户端接到编辑器之后配置这件事本身不复杂真正改变工作方式的是接入之后。以前要写 Editor 扩展才能做的编辑器自动化现在降级成用自然语言描述意图。Funplay Unity MCP 在协议侧选择标准 HTTP MCP配置成本停留在写一段 JSON 或 TOML客户端的迁移与并存不需要改动 Unity 项目本身。如果你在配置 Claude Code、Cursor 或 Codex 的过程中需要确认模型侧的调用行为可以先用模型对话快速验证指令语义是否符合预期再落到编辑器里执行。长期做编码和 Agent 工作流的团队可以考虑 Coding Plan 把调用额度固定下来避免频繁切换配置。接入过程中遇到鉴权或 endpoint 相关问题API Keys 页面和接入文档里有完整的字段说明对照检查比反复重启客户端更快。仓库地址是 FunplayAI/funplay-unity-mcpMIT 协议。完整接入流程可以压缩成一条链路UPM 安装Funplay → MCP Server启动:8765选择客户端写入配置用/mcp或设置面板验证最后跑工具调用、资源读取和execute_code三类测试。跑通之后剩下的就是你想让编辑器做什么了。
