UnityMCP VRC

UnityMCP-VRC

通过 Claude（或任何 MCP 客户端）驱动 Unity Editor。Unity Editor 插件会在 Editor 中运行一个小型 HTTP 服务，而小型 MCP 服务（Node/TypeScript）会针对每次工具调用向它发送一个请求，并将工具提供给 Claude——在 Editor 中运行 C#、读取 Editor/场景状态，以及获取 Unity 控制台日志。

本项目从 Arodoid/UnityMCP 分支而来，并经过大幅重构，重点是使用 Claude 构建 VRChat / UdonSharp 和 Basis 世界——不过大多数功能也适用于普通 Unity 开发。它支持 Unity 2022.3 到 Unity 6（命令沙箱会为每个项目选择编译后端，详见下文）。take_screenshot 和 get_object_details 工具移植自 setohima/UnityMCP-VRC，并针对本项目的连接模型进行了适配。

调试窗口——插件的 HTTP 服务正在 Editor 中监听（每个实例使用独立端口）。

亮点

• 多个 Editor，多个 Claude 会话。 每个 Editor 的插件都会运行自己的 HTTP 服务，使用动态端口并将自身发布到共享注册表，因此你可以同时运行多个项目并按名称指定目标——同时任意数量的 Claude 会话都能驱动同一个 Editor。没有固定端口争用，也没有“显示已连接但实际失效”的僵尸服务。
• 本地且经过身份验证。 Editor 端点仅绑定到 127.0.0.1，每条命令都必须携带一个通过本地实例注册表读取的、针对每个 Editor 会话单独生成的加密随机令牌。
• 运行真实 C#。 execute_editor_command 可运行由大模型编写的 C#（包含其自己的 using、类和函数），并自动从所有已加载内容中发现程序集引用——包括 UnityEngine、包、VRChat/UdonSharp、Basis 和项目脚本，无需手动维护列表。
• Unity 2022.3 → Unity 6。 对于 .NET Framework 项目（Unity 2022 / VRChat 的常见配置），命令沙箱会使用 Mono 的进程内编译器进行编译；对于 .NET Standard 项目（Unity 6 的默认配置），Mono 路径不可用时则会自动回退到 Editor 自带的 Roslyn csc。回退方式只检测一次并缓存；无需配置。详情：docs/005。
• 有界状态。 get_editor_state 会按需返回场景/项目状态，并设有上限，防止大型项目撑爆上下文窗口。
• 直观查看运行情况。 take_screenshot 会将 Scene 或游戏摄像机画面渲染为图像并返回给 Claude；get_object_details 会输出 GameObject 的组件/边界信息——因此，视觉迭代和检查不必每次都手写 C#。
• 重新编译后仍可用。 域重载只会暂时关闭 HTTP 监听器——无需拆除持久连接，因此在此期间发送的请求只需重试，直到 Editor 恢复即可。
• 实时调试窗口。 显示服务是否正在监听、上一次请求以及主线程队列的情况，让连接中断一目了然。
• VRChat 辅助工具 + MCP 资源，帮助 Claude 提高 UdonSharp 的成功率。

工具

工具	功能说明
list_unity_instances	列出当前正在运行的 Unity 编辑器（名称、项目、instanceId），供你选择。
select_unity_instance	选择后续调用默认针对的编辑器（每个会话）；调用时也可以通过 instance= 覆盖。
execute_editor_command	在编辑器中编译并运行由大模型编写的 C#；返回结果和日志。可选 timeoutMs（默认 60s，最长 300s），适用于大型导入等耗时操作。
get_editor_state	按需返回 Unity／场景／项目状态（有大小限制）。
get_object_details	检查一个 GameObject：变换、组件和大小信息（Renderer 边界、网格顶点数、共享网格／材质名称）。
get_logs	返回近期的 Unity 控制台日志。
clear_logs	清除编辑器缓存的控制台日志（例如，清除失败代码片段留下的过时错误），避免后续读取 get_logs 时产生歧义。
take_screenshot	将 Scene 视图或游戏摄像机渲染为 JPEG／PNG 图像，让 Claude 查看编辑结果。
get_command_page	获取任何已分页的超大工具结果的后续页面 — execute_editor_command、get_object_details、get_editor_state（自动使用）。

开始使用

1. 构建 MCP 服务

cd unity-mcp-server
npm install
npm run build      # compiles to build/index.js and copies text resources

2. 将插件添加到 Unity

• 将整个 UnityMCPPlugin/ 文件夹拖入项目的 Assets/。Unity 会在导入时重新生成 .meta 文件 — 仓库不会跟踪这些文件。
• 此时会出现 UnityMCP 菜单。打开 Debug Window 并将其停靠；Unity 运行时， Server 行应显示为绿色／Listening。

3. 将 Claude 指向它 — 将 stdio MCP 服务添加到客户端。Claude Desktop （启用开发者模式，然后选择 File > Settings）：

{
  "mcpServers": {
    "unity": {
      "command": "node",
      "args": ["C:\\git\\UnityMCP\\unity-mcp-server\\build\\index.js"]
    }
  }
}

或者使用 Claude Code：claude mcp add unity -- node C:\git\UnityMCP\unity-mcp-server\build\index.js

4. 验证 — 在 Debug Window 中，确认 Server: Listening，并在 Claude 启动后看到 MCP Client 行（连接多个会话时，每个会话都会显示出来）。 向 Claude 提示；如果脚本报错，请在 UnityMCP > Script Tester 中诊断。

使用多个编辑器

可按需打开任意数量的项目 — 每个项目都会以其项目文件夹名称进行注册。在 Claude 会话中：

1. list_unity_instances — 查看正在运行的实例（名称 · 项目 · instanceId）。
2. select_unity_instance <name> — 为会话的其余时间指定目标实例；单次调用也可以 通过 instance=<name> 覆盖。

在选择实例之前，工具不会运行，因此调用绝不会落到错误的项目中。若要在会话开始时将其固定到某个项目，可在 MCP 服务的 env 中设置 UNITYMCP_INSTANCE=<name>（这样 Agent 就不必选择实例）。实例发现记录位于 %LOCALAPPDATA%\UnityMCP\instances\（可通过 UNITYMCP_REGISTRY_DIR 覆盖）；其中还包含本地 MCP 服务使用的私有会话令牌，因此不要复制或发布这些记录。每个编辑器都会在 Debug Window 中显示其名称和 instanceId。

插件会限制注册表目录和令牌文件的访问权限，仅允许当前操作系统用户访问。自定义的 UNITYMCP_REGISTRY_DIR 必须是该用户拥有的专用目录；其权限也会受到限制。编辑器和 MCP 服务必须使用同一目录。

从未进行身份验证的传输方式升级时，请更新每个 Unity 项目中的插件，重新构建 MCP 服务，并重启 MCP 客户端。没有会话令牌的旧插件不会被更新后的服务发现。

故障排除

• Claude 中显示“已连接”，但 Unity 中没有任何反应？ MCP 徽标只反映 Claude↔服务端的握手状态，并不表示与 Unity 的连接正常。请以调试窗口为准：Server: Listening 和 MCP Client 行才是真正的信号。
• 服务无法绑定／显示“NOT listening”？ 每个 Editor 都会使用操作系统分配的端口，因此端口冲突不太可能发生；如果 Server 行显示红色，Last Error 框会显示绑定失败原因。点击 Restart Server 以选择一个新端口。
• 调用卡住或超时？ Editor 在失去焦点时会进行限流——请查看 Editor 行的队列深度。重新聚焦 Unity，或在后台使用时选择 Preferences > General > Interaction Mode > No Throttling。
• 域重新加载需要 10–20 秒以上（Unity 卡在“Reloading Domain…”）？ 在 Windows 上，这通常是防病毒软件正在扫描刚编译的程序集——Editor 日志中会出现一条很长的 Loaded All Assemblies, in N seconds，且只会在重新编译后出现。请在每个正在运行的扫描程序中，为项目的 Library/ 文件夹、Unity Editor 安装目录以及 Unity.exe/bee_backend.exe 进程添加实时扫描排除项（同一台机器可能运行多个扫描程序，例如 Windows Defender 和 HP Wolf Pro Security 等厂商的 Agent）。重新加载时间通常会从约 20 秒降至约 3 秒；由于会触发重新加载，写入 .cs 文件的 execute_editor_command 也会因此更快，从而加速 MCP 工作循环。详情： docs/004 — 重新加载缓慢时的处理。

更多详情请参阅 docs/001 — 架构。

文档

• 001 — 架构 — 当前的工作方式：连接模型、线路协议、线程处理、生命周期、工具、文件映射和限制。从这里开始。
• 002 — 设计决策 — 架构背后的原因：反向无状态连接、服务端分页，以及关于我们已替换的 WebSocket 传输方式的说明。
• 003 — 与原始分支的差异 — 本仓库与上游 Arodoid/UnityMCP 的差异：反向拓扑、VRChat/UdonSharp 支持、分页和重新授权。
• 004 — Unity Editor 状态 — 插件需要应对的 Editor 生命周期：编译、域重新加载、播放模式、焦点／限流——各状态何时发生，以及对正在执行的命令意味着什么。
• 005 — 执行 LLM C# 代码 — 命令沙箱：LLM 编写的 C# 如何编译（自动发现引用，包括 BCL 外观程序集）并运行、结果和日志捕获、输出限制，以及信任模型。
• 006 — 从代码附加 UdonSharp 组件 — 向 GameObject 添加可正常工作的 Udon 脚本的可靠方法（程序资源 + 底层 UdonBehaviour + 代理 + CopyProxyToUdon）、每个步骤的必要性，以及 UdonSharpHelper 如何将其封装为一次调用。

许可证

依据 Creative Commons Attribution-NonCommercial 4.0 International （CC BY-NC 4.0）授权。