Unity MCP Server

用于 Unity 编辑器的 MCP 服务器。让 AI 代理（如 Claude Code）能够检查、操作、测试和截取你的项目。

亮点

• 73 个工具：场景、GameObject、组件、预制体、变换、测试、反射 + 反编译、C# 求值、UI 捕获

• 零配置客户端：每台机器一键（或一条命令）完成，之后每个项目和编辑器都会自动连接。无需端口、无需令牌、无需逐项目配置

• 多编辑器安全：每个打开的项目运行自己的服务器，会话自动路由到正确的项目

• MCP 资源：控制台日志、场景层级、测试结果、项目文件

• Unity 2022.3+（推荐 Unity 6）、Node.js 18+

Related MCP server: Unity MCP Server

安装

Package Manager > + > 通过 Git URL 添加包：

https://github.com/Singtaa/UnityMCP.git

或者克隆 / 子模块到 Packages/com.singtaa.unity-mcp。

设置（每台机器一次）

1. 在 Unity 中打开项目。服务器自动启动，启动器部署到 ~/.unity-mcp/stdio.js

2. 点击 Window > Unity MCP Server > Set up Claude Code

完成。终端等价命令：

# macOS / Linux
claude mcp add --scope user --transport stdio unity -- node ~/.unity-mcp/stdio.js

# Windows
claude mcp add --scope user --transport stdio unity -- node "%USERPROFILE%\.unity-mcp\stdio.js"

任何 Unity 项目中的每个 Claude Code 会话现在都能到达该项目自己的编辑器。多个编辑器并排：每个会话都会找到自己的。编辑器关闭或重新加载中：工具返回清晰的错误并自行恢复。在会话中途打开编辑器也可以：在编辑器关闭时启动的会话会立即注册工具列表（由每个项目的缓存提供），并在编辑器启动时实时重新同步，无需重启客户端。

底层原理：编辑器写入每个会话的信标（Temp/UnityMcp_Endpoint.json，退出时删除，永不过期）。启动器解析会话的项目（CLAUDE_PROJECT_DIR，否则向上遍历 cwd，UNITY_MCP_PROJECT 优先于两者）并将 MCP 代理到该项目的实时端点，每个请求都重新读取信标。它声明 tools.listChanged 并监视信标：当编辑器出现（或另一个编辑器接管项目）时，它发出 list_changed 通知，客户端在会话中重新获取工具和资源列表。启动器部署到 ~/.unity-mcp/stdio.js 仅由 LAUNCHER_VERSION 升级，因此不同包版本的编辑器永远不会冲突。

其他 MCP 客户端：相同的启动器，或纯 HTTP（端点 + 令牌显示在窗口中）。

工具

值得注意的：

• unity_eval：在编辑器中编译并运行 C# 代码片段，无需域重载。表达式形式返回其值，语句形式使用 return。自动导入常用 using，前置 using 行会提升。内置 Roslyn（最高 C# 9）。首次调用预热几秒，之后每次编译几十毫秒

• unity_capture_panel：将 UI Toolkit PanelSettings 渲染为离屏 PNG，无场景装饰，编辑模式和播放模式均可。自动检测活动的 UIDocument

• unity_assets_find：项目窗口查询语法（t:Material、t:Prefab ui、l:MyLabel），可选的文件夹范围，结果带总数上限

• unity_reflection_decompile：任何已加载类型或方法的完整 C# 源代码

• 注意：域重载后等待约 1 秒再使用测试工具；unity_capture_game_view 在 Unity 6.3+ 上仅限播放模式

资源

unity://console/logs · unity://hierarchy · unity://hierarchy/{scene} · unity://tests/results · unity://project/files

配置

ProjectSettings/McpSettings.json（建议提交到版本控制）：HTTP 端口 5173、IPC 端口 52100、自动启动、认证令牌。

端口被另一个项目的服务器占用？会自动分配一个空闲对并存储在每台机器的 UserSettings/McpPortOverride.json（已 gitignore）中，因此端口变动永远不会影响到团队。每次桥接连接都会验证项目身份：编辑器永远不能采用另一个项目的服务器，即使端口配置错误。

手动启动服务器：node src/server.js，同时设置 MCP_PROJECT_ROOT 为项目路径。

与 Unity CLI 配合

互补而非竞争：

• Unity CLI 掌控编辑器生命周期：安装、unity open、构建、CI

• UnityMCP 掌控实时编辑器会话：UI 捕获、反编译、求值、测试循环、零配置路由

• 典型代理循环：通过 CLI 执行 unity open <project>，编辑器启动，服务器 + 信标出现，启动器连接。两侧均无需配置

• CLI 启动的编辑器在后台 / 未聚焦状态下运行。UnityMCP 正是为此而构建和测试的（后台安全启动、域重载期间重试）

• 无端口或工具名称冲突。同时注册两者

架构

┌─────────────────────────────────────────────────────────────┐
│                      AI Assistant                           │
├──────────────────────────────┬──────────────────────────────┤
│  stdio launcher              │  (or direct HTTP clients)    │
│  ~/.unity-mcp/stdio.js       │                              │
│  resolves the session's      │                              │
│  project, reads its beacon   │                              │
│  Temp/UnityMcp_Endpoint.json │                              │
├──────────────────────────────┴──────────────────────────────┤
│           HTTP JSON-RPC (Port 5173, per project)            │
├─────────────────────────────────────────────────────────────┤
│              Node.js MCP Server (Server~/)                  │
├─────────────────────────────────────────────────────────────┤
│                TCP NDJSON (Port 52100)                      │
├─────────────────────────────────────────────────────────────┤
│                Unity Editor C# Bridge                       │
│  (McpBridge → ToolRegistry → MainThreadDispatcher)          │
├─────────────────────────────────────────────────────────────┤
│                     Unity APIs                              │
└─────────────────────────────────────────────────────────────┘

每个打开的项目运行自己的 Node 服务器。启动器是共享的前门，将每个会话路由到正确的项目。

开发

• Unity 测试：Window > General > Test Runner（EditMode + PlayMode）

• 启动器测试：在 Server~/ 中运行 npm test

• 更新日志：CHANGELOG.md

许可证

MIT。参见 LICENSE。