unity-mcp MCP — 使用场景, 安装 & 实时演示

为什么要用

核心特性

40+ 精细化的 Unity 编辑器工具（场景、资源、脚本、测试、物理、UI、VFX）
安全的 C# 脚本 apply_text_edits，写入前验证
读取 Unity 控制台（错误/警告）并触发域重载
运行 EditMode 和 PlayMode 测试并读取结果
支持多个 Unity 实例，使用逐实例路由

实时演示

实际使用效果

unity.replay ▶ 就绪

0/0

安装

选择你的客户端

~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "unity": {
      "command": "TODO",
      "args": [
        "See README: https://github.com/CoplayDev/unity-mcp"
      ],
      "_inferred": true
    }
  }
}

打开 Claude Desktop → Settings → Developer → Edit Config。保存后重启应用。

~/.cursor/mcp.json · .cursor/mcp.json

{
  "mcpServers": {
    "unity": {
      "command": "TODO",
      "args": [
        "See README: https://github.com/CoplayDev/unity-mcp"
      ],
      "_inferred": true
    }
  }
}

Cursor 使用与 Claude Desktop 相同的 mcpServers 格式。项目级配置优先于全局。

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "unity": {
      "command": "TODO",
      "args": [
        "See README: https://github.com/CoplayDev/unity-mcp"
      ],
      "_inferred": true
    }
  }
}

点击 Cline 侧栏中的 MCP Servers 图标，然后选 "Edit Configuration"。

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "unity": {
      "command": "TODO",
      "args": [
        "See README: https://github.com/CoplayDev/unity-mcp"
      ],
      "_inferred": true
    }
  }
}

格式与 Claude Desktop 相同。重启 Windsurf 生效。

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "unity",
      "command": "TODO",
      "args": [
        "See README: https://github.com/CoplayDev/unity-mcp"
      ]
    }
  ]
}

Continue 使用服务器对象数组，而非映射。

~/.config/zed/settings.json

{
  "context_servers": {
    "unity": {
      "command": {
        "path": "TODO",
        "args": [
          "See README: https://github.com/CoplayDev/unity-mcp"
        ]
      }
    }
  }
}

加入 context_servers。Zed 保存后热重载。

claude mcp add unity -- TODO 'See README: https://github.com/CoplayDev/unity-mcp'

一行命令搞定。用 claude mcp list 验证，claude mcp remove 卸载。

使用场景

实战用法： unity-mcp

如何从文本描述原型化 Unity 场景

👤 游戏设计师、独立开发者、黑客马拉松团队 ⏱ ~20 min intermediate

何时使用： 你想从「低多边形森林，带一个玩家和 5 个巡逻敌人」快速到可运行的场景，无需手工连接每个 GameObject。

前置条件

Unity 2021.3 LTS 或更新版本、Python 3.10+、uv — 通过 brew install uv 安装 uv；从 unity.com/download 安装 Unity
安装 Unity 包 — Window > Package Manager > + > Add from git URL: https://github.com/CoplayDev/unity-mcp.git?path=/MCPForUnity#main

步骤

描述你想要的场景

创建一个名为 'ForestDemo' 的新场景。添加一个 200x200 的低多边形地形、一个原点处带刚体的玩家胶囊体，以及 5 个立方体敌人随机放置在 (-50,-50) 至 (50,50) 之间。✓ 已复制

→ 场景已创建，GameObject 出现在层级中，Unity 实时反映变化
请求行为脚本

创建一个 C# 脚本 EnemyPatrol.cs，在两个随机路点之间移动，并将其附加到每个 Enemy* GameObject。✓ 已复制

→ 新脚本编译无误，已附加到敌人
进入播放模式并迭代

进入播放模式 5 秒，然后读取控制台并告诉我是否有任何内容抛出异常。✓ 已复制

→ 运行时日志已返回，Claude 为任何 NullReferenceException 提出具体修复

结果： 可运行的原型场景，带脚本敌人 — 少于 15 分钟聊天。

注意事项

脚本编辑因编译错误级联而被拒绝 — 要求 Claude 在 apply_text_edits 前运行 manage_script validate
域重载在会话中途清除运行时状态 — 在脚本编辑前显式保存场景；之后使用 refresh_unity

搭配使用： filesystem · github

如何从聊天中诊断和修复 Unity 编译/运行时错误

👤 卡在红色控制台的 Unity 开发者 ⏱ ~15 min intermediate

何时使用： 控制台充满来自大型重构或包更新的错误，你想要另一双眼睛。

步骤

获取控制台

读取 Unity 控制台。按根本原因分组错误。✓ 已复制

→ 错误已按根本原因分组，可能的文件已识别
读取有问题的脚本

打开提到的顶部脚本，找到该行，并解释为什么它会破坏。✓ 已复制

→ 参考行号的具体修复提议
应用最小补丁

应用最小的变化使其编译，然后刷新 Unity 并重新读取控制台。✓ 已复制

→ 错误数量下降，未引入新错误

结果： 绿色控制台和可在提交前审查的 diff。

注意事项

Claude 提出破坏其他脚本 API 契约的修复 — 在编辑前要求它查找引用（find_in_file）

搭配使用： github

如何运行 Unity EditMode/PlayMode 测试并读取失败

👤 有真实测试套件的 Unity 开发者 ⏱ ~15 min intermediate

何时使用： 在打开 PR 之前或 CI 宕机时，你想要快速本地通过。

步骤

启动测试运行

运行 Tests.EditMode 程序集中的所有 EditMode 测试。✓ 已复制

→ 返回测试 job id，状态流式传输
总结失败

对于每个失败的测试，显示断言消息和它触发的行。✓ 已复制

→ 逐测试诊断
先修复最小的失败

选择最可能由我最后一次更改引起的失败，并提出补丁。✓ 已复制

→ 具体的编辑建议

结果： 绿色测试运行，编辑可追踪。

注意事项

PlayMode 测试需要不同的程序集 — 显式指定 EditMode 与 PlayMode

搭配使用： github

组合

与其他 MCP 搭配，撬动十倍杠杆

unity + github

脚手架场景和脚本，提交变化，打开 PR 供审查

在 Unity 中构建 EnemyPatrol 功能，提交新脚本和场景变化到分支 'feature/enemy-patrol'，并打开 PR 附带变化总结。✓ 已复制

unity + filesystem

从本地文件夹导入一批 3D 资源并将其连接到预制体

读取 /Downloads/kenney-nature-pack，将每个 .fbx 导入到 Assets/Models/，然后为每棵树创建一个带碰撞体的预制体。✓ 已复制

unity + unity-2 + unity-3

选择最适合你工作流的 Unity MCP — 一次只运行一个

比较 MCP for Unity 与 CoderGamester mcp-unity 在我的 2D tilemap 项目中的表现，然后保持效果更好的启用。✓ 已复制

工具

此 MCP 暴露的能力

工具	输入参数	何时调用	成本
manage_scene	action: 'create'\|'open'\|'save'\|'load', name?: str, path?: str	任何场景生命周期变化	free
find_gameobjects	query: str, scene?: str	按名称、标签或组件定位对象	free
manage_components	target: str, action: 'add'\|'remove'\|'modify', component: str, values?: obj	附加或调整组件	free
manage_script	action: 'create'\|'read'\|'delete', path: str, body?: str	完整文件脚本写入 — 部分编辑用 apply_text_edits	free
apply_text_edits	path: str, edits: Edit[]	精细补丁；比完全重写更安全	free
read_console	since_ms?: int	任何变化后检查错误/警告	free
run_tests	mode: 'EditMode'\|'PlayMode', filter?: str	启动测试运行；用 get_test_job 轮询	free
refresh_unity		创建/修改脚本或资源后	free
manage_asset	action, path, ...	导入/移动/删除资源	free
unity_docs	query: str	内联查找 Unity API 文档	free

成本与限制

运行它的成本

API 配额: 无远程 API — 完全在你的机器上运行
每次调用 Token 数: 读取场景层级：500–3000 tokens。脚本读取：取决于文件大小
费用: 免费（开源，MIT）
提示: 通过工具允许列表禁用你不会使用的工具（例如 manage_vfx、manage_probuilder）以缩小提示足迹。

安全

权限、密钥、影响范围

最小权限： 你的 Unity 项目的本地文件系统写入

凭据存储： 无需凭据 — 仅本地主机 HTTP

数据出站： 仅本地主机（http://localhost:8080/mcp）。默认无遥测。

切勿授予： 访问活跃项目外的 Unity 项目

AI 驱动的脚本编辑可能破坏你的项目 — 长会话前提交。
PlayMode 中的 run_tests 执行游戏代码；像「播放」一样对待它，带完整副作用。

故障排查

常见错误与修复

Claude 无法连接：ECONNREFUSED localhost:8080

Unity 编辑器必须打开且加载 MCP 包。检查 Window > MCP for Unity > Status。

验证： curl http://localhost:8080/mcp/ping

apply_text_edits 报告「磁盘上的文件已更改」

另一个工具修改了文件。在再次编辑前用 manage_script 重新读取。

refresh_unity 永久挂起

通常是编译错误锁定域重载。打开 Unity，修复红色脚本，然后重试。

验证： Check Unity console manually

Package Manager「无法解析 git URL」

在代理后面或 PATH 中没有 git。安装 git 并重试，或使用 OpenUPM 安装。

验证： git --version

替代方案

unity-mcp 对比其他方案

替代方案	何时用它替代	权衡
Unity-MCP (IvanMurzak)	你想要 CLI 驱动的设置和基于 Roslyn 的 C# 执行	社区比 Coplay 的小，工具表面不同
mcp-unity (CoderGamester)	你想要更简单的工具集，专注于场景操纵和测试	工具更少，对材质/VFX 的覆盖较少

unity-mcp

为什么要用

核心特性

实时演示

实际使用效果

安装

选择你的客户端

使用场景

实战用法： unity-mcp

前置条件

步骤

注意事项

步骤

注意事项

步骤

注意事项

组合

与其他 MCP 搭配，撬动十倍杠杆

工具

此 MCP 暴露的能力

成本与限制

运行它的成本

安全

权限、密钥、影响范围

故障排查

常见错误与修复

替代方案

unity-mcp 对比其他方案

更多

资源