/ 目录 / 演练场 / mcp-unity
● 社区 CoderGamester ⚡ 即开即用

mcp-unity

作者 CoderGamester · CoderGamester/mcp-unity

一个专注于场景编辑、测试和预制件工作的 Unity MCP —— 比其他大型方案表面更简洁。

CoderGamester/mcp-unity 是一个基于 Node 的 Unity 6+ MCP 插件,包含约 30 个功能清晰的工具:场景管理、GameObject 操作、组件、预制件、材质、测试、控制台。为 Cursor、Claude Code、Codex、Windsurf 而设计。

为什么要用

核心特性

实时演示

实际使用效果

unity-3.replay ▶ 就绪
0/0

安装

选择你的客户端

~/Library/Application Support/Claude/claude_desktop_config.json  · Windows: %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "unity-3": {
      "command": "TODO",
      "args": [
        "See README: https://github.com/CoderGamester/mcp-unity"
      ],
      "_inferred": true
    }
  }
}

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

~/.cursor/mcp.json · .cursor/mcp.json
{
  "mcpServers": {
    "unity-3": {
      "command": "TODO",
      "args": [
        "See README: https://github.com/CoderGamester/mcp-unity"
      ],
      "_inferred": true
    }
  }
}

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

VS Code → Cline → MCP Servers → Edit
{
  "mcpServers": {
    "unity-3": {
      "command": "TODO",
      "args": [
        "See README: https://github.com/CoderGamester/mcp-unity"
      ],
      "_inferred": true
    }
  }
}

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

~/.codeium/windsurf/mcp_config.json
{
  "mcpServers": {
    "unity-3": {
      "command": "TODO",
      "args": [
        "See README: https://github.com/CoderGamester/mcp-unity"
      ],
      "_inferred": true
    }
  }
}

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

~/.continue/config.json
{
  "mcpServers": [
    {
      "name": "unity-3",
      "command": "TODO",
      "args": [
        "See README: https://github.com/CoderGamester/mcp-unity"
      ]
    }
  ]
}

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

~/.config/zed/settings.json
{
  "context_servers": {
    "unity-3": {
      "command": {
        "path": "TODO",
        "args": [
          "See README: https://github.com/CoderGamester/mcp-unity"
        ]
      }
    }
  }
}

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

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

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

使用场景

实战用法: mcp-unity

如何通过聊天以最少的准备工作构建一个简单的场景

👤 独立 Unity 开发者 ⏱ ~15 min beginner

何时使用: 你希望获得一个 Unity MCP,不想被 100 多个工具搞得上下文混乱。

前置条件
  • Unity 6 或更高版本 — unity.com/download
  • Node 18+ — nodejs.org or nvm
  • 从 git URL 安装包 — Package Manager > + > Add from git URL: https://github.com/CoderGamester/mcp-unity.git
步骤
  1. 编写场景
    创建一个新场景 'Playground'。添加一个 Plane、一个 Directional Light 和 3 个立方体,位置分别为 (-2,0,0)、(0,0,0)、(2,0,0)。✓ 已复制
    → 场景出现,对象可见
  2. 连接交互
    为每个立方体添加 Rigidbody 和 BoxCollider。使原点处的立方体为运动学的。✓ 已复制
    → 检查时组件可见
  3. 运行测试
    run_tests mode=EditMode。显示失败。✓ 已复制
    → 测试输出

结果: 一个工作的场景 + 通过的测试,都在聊天中完成。

注意事项
  • batch_execute 的回滚行为因情况而异——不是真正的事务 — 假设出错时部分成功;在批量操作后验证
搭配使用: github

如何通过聊天创作和实例化预制件

👤 构建可复用资产的 Unity 开发者 ⏱ ~15 min intermediate

何时使用: 你希望代理维护一个预制件库。

步骤
  1. 创建预制件
    构建一个 GameObject 'Enemy',包含 Rigidbody + EnemyAI 组件,然后从它创建预制件,路径为 Assets/Prefabs/Enemy.prefab。✓ 已复制
    → 预制件文件已创建
  2. 实例化
    将 Assets/Prefabs/Enemy.prefab 添加到场景,放在原点周围 50 个单位内的 5 个随机位置。✓ 已复制
    → 5 个敌人已放置

结果: 一个可复用的 Enemy 预制件 + 5 个已放置的实例。

如何使用 run_tests 在紧凑的循环中迭代修复

👤 具有测试覆盖的 Unity 开发者 ⏱ ~15 min intermediate

何时使用: 存在 Bug 和测试;想要快速的红-绿-重构。

步骤
  1. 查看失败
    run_tests mode=EditMode filter='EnemyAI_ShouldPatrol'。显示堆栈。✓ 已复制
    → 带有行号的失败断言
  2. 编辑并重新测试
    应用最小修复,保存,然后重新运行测试。✓ 已复制
    → 绿色测试

结果: 绿色测试,对修复充满信心。

搭配使用: github

组合

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

unity-3 + github

运行测试,然后提交 + PR 修复

修复 EnemyAI 测试失败,在分支 fix/enemy-patrol 上提交,打开 PR。✓ 已复制

工具

此 MCP 暴露的能力

工具输入参数何时调用成本
create_scene name: str 开始一个新场景 free
load_scene path: str 打开现有场景 free
get_gameobject name_or_id: str 查找一个对象 free
update_gameobject id, props 重命名、重新指定父级、切换活跃状态 free
update_component target, component, values 调整组件字段 free
create_prefab source_id, path 将一个对象捕获为预制件 free
add_asset_to_scene path, position?, rotation? 实例化一个资产/预制件 free
run_tests mode: 'EditMode'|'PlayMode', filter? 单元测试 free
get_console_logs since_ms? 检查错误 free
batch_execute calls: Call[] 组合多个工具调用 free

成本与限制

运行它的成本

API 配额
无 —— 仅本地
每次调用 Token 数
较小;该 MCP 的工具列表紧凑
费用
免费(开源)
提示
通过 batch_execute 批量处理相关操作以减少往返。

安全

权限、密钥、影响范围

最小权限: 仅本地项目访问
凭据存储:
数据出站: 本地主机;LLM 看到你的工具返回的任何内容
切勿授予: 不要将 Node bridge 暴露给非本地回环

故障排查

常见错误与修复

Unity '包无法解析'

需要 Unity 6 或更高版本。检查版本;git URL 安装在较旧的编辑器上会失败。

Node bridge 在启动时崩溃

需要 Node 18 + npm 9。检查 'node -v' 并升级。

验证: node -v
测试不出现

测试程序集必须在引用 TestRunner 的 Assembly Definition 文件中定义。

替代方案

mcp-unity 对比其他方案

替代方案何时用它替代权衡
MCP for Unity (CoplayDev)你想要最大的 Unity 工具表面,具有物理/VFX 覆盖更多工具 = 更多上下文成本
Unity-MCP (IvanMurzak)你需要 Roslyn 支持的一次性 C# 执行更多功能,更多风险

更多

资源

📖 阅读 GitHub 上的官方 README

🐙 查看未解决的 issue

🔍 浏览全部 400+ MCP 服务器和 Skills