Unity Mcp

Unity MCP ✨

使用大模型创建 Unity 应用！

Unity MCP 是一套端到端工具链，可让 AI 助手（例如 Claude、Cursor、Windsurf、VS Code）通过 Model Context Protocol (MCP) 与 Unity Editor 交互。为你的大模型提供工具，使其能够直接在 Unity Editor 中管理资源、控制场景、编辑脚本并自动化工作流。

---

💬 这个仓库包含什么？

此仓库包含：

• 一个 Unity Editor 包，可在 Editor 中运行本地 HTTP 桥接服务
• 一个基于 TypeScript 的 MCP 服务，可通过 MCP 工具（stdio）提供 Unity 操作
• 一个用于快速冒烟测试的 TypeScript 示例 MCP 客户端

[LLM / MCP Client] ⇄ [MCP Server (Node/TypeScript)] ⇄ [Unity Bridge (Unity Editor)]

---

主要功能 🚀

• 🗣️ 自然语言控制 — 让你的大模型执行 Unity 任务
• 🛠️ 强大工具 — 资源、场景、游戏对象、组件、Editor 实用工具、包、播放模式等
• 🤖 自动化 — 编写脚本来自动执行重复或多步骤的 Editor 任务
• 🎨 可视化脚本集成 — 使用预构建模板，通过 MCP 操作创建 Unity Visual Scripting 图
• 🔍 自动控制台验证 — 每次工具操作都会自动检查 Unity 控制台中的错误和警告
• ✅ 增强的错误处理 — 操作失败时立即提供包含控制台上下文的反馈
• 🎮 智能播放模式控制 — 存在编译错误时禁止进入播放模式
• 🧩 可扩展 — 随着工作流的发展，添加新的 Unity 端点和 MCP 工具

可用工具

工具仅以带下划线的名称提供。部分示例：

• unity_console — 读取或清空 Unity 控制台
• unity_play — 启动/停止/暂停/恢复 Play Mode
• unity_packages — UPM 列表/安装/移除
• unity_assets — AssetDatabase 列表/查找/刷新
• unity_selection — 获取/设置选择项
• unity_gameObject — 创建/获取/设置/删除层级项
• unity_component — 添加/更新/获取/销毁组件
• unity_editor — 状态、信息、通知、buildTarget、偏好设置、调用
• unity_scene — open/save/saveAs/getLoaded/create/createClean/unload/clear
• unity_prefab — 应用/还原预制件实例
• unity_bake — 开始烘焙光照
• unity_profiler — 内存快照
• unity_import — 常用纹理导入器设置
• unity_menu — 执行 Editor 菜单项
• unity_asset — 将资源实例化到场景中
• unity_tests — 运行 EditMode/PlayMode 测试
• unity_rendering — 创建光源/相机/材质，设置属性
• unity_gameplay — Rigidbody/Collider 辅助工具、标签/图层
• unity_code — 写入文件、创建脚本、附加脚本、编译
• unity_visualscripting — 创建可视化脚本、添加节点、连接工作流
• unity_visualscripting_templates — 浏览、搜索并应用工作流模板
• unity_import - 导入 .unitypackages 或将外部文件复制到 Unity 项目中。

---

工作原理 🤔

• Unity Bridge — 仅限 Editor 使用的包，提供本地 HTTP API 和 SSE 日志（127.0.0.1:58888）
• MCP 服务 — Node/TypeScript 进程，将 MCP 工具调用转换为 Unity Bridge 端点请求
• MCP 客户端 — 使用 stdio 与 MCP 通信的 LLM IDE 或 Agent

---

安装 ⚙️

注意：需要 Unity 2022.3+ 和 Node.js 18+。

1) 安装 Unity Bridge 包

• 在 Unity 中打开 Package Manager → + → Add package from disk...
• 选择 PathToFile/UnityBridge/Packages/com.example.mcp.unitybridge/package.json
• 等待 Unity 加载，然后进入一次 Play Mode（或等待脚本完成编译）

桥接服务运行后，你应当会在 Console 中看到：

UnityMcpBridge running at http://127.0.0.1:58888/

2）安装 MCP 服务依赖

cd MCP/server
npm install

可选（示例客户端）：

cd MCP/client
npm install

3）构建 MCP 服务

cd MCP/server
npm run build

也可以直接使用 TypeScript 在开发模式下运行：

cd MCP/server
npm run dev

---

配置 MCP 客户端（Cursor、VS Code、Claude Code 等）

在 MCP 客户端配置中添加服务条目，指向构建后的服务。仅使用下划线工具名称。

配置示例（JSON）：

{
  "unity-mcp": {
    "command": "node",
    "args": [
      "PathToFile/MCP/server/dist/index.js"
    ],
    "env": {
      "UNITY_BRIDGE_URL": "http://127.0.0.1:58888"
    }
  }
}

控制台验证配置

该服务包含自动控制台验证功能。使用环境变量进行配置：

{
  "unity-mcp": {
    "command": "node",
    "args": ["PathToFile/server/dist/index.js"],
    "env": {
      "UNITY_BRIDGE_URL": "http://127.0.0.1:58888",
      "UNITY_CONSOLE_VERIFICATION": "true",
      "UNITY_CONSOLE_CHECK_DELAY_MS": "500"
    }
  }
}

环境变量：

• UNITY_BRIDGE_TOKEN — 安全令牌（在 Unity 和服务中设置相同的值）
• UNITY_CONSOLE_VERIFICATION — 启用自动控制台检查（默认值：true）
• UNITY_CONSOLE_CHECK_DELAY_MS — 检查控制台前的延迟时间（默认值：500ms）
• UNITY_COMPILE_TIMEOUT_MS — 脚本编译超时时间（默认值：120000ms）

说明：

• 服务通过 stdio 通信；客户端应以 stdio 工具的形式启动它
• 控制台验证可即时反馈操作成功或失败
• 每次工具操作都会自动检查 Unity 控制台中的错误和警告

---

使用 ▶️

1. 打开已安装桥接包的 Unity 项目
2. 启动 MCP 客户端；它应通过 stdio 启动 Node 服务
3. 按名称使用工具（例如，使用操作 create 调用 unity_gameObject）

冒烟测试示例（可选）：

cd MCP/client
# Use tsx for both client and server
set MCP_USE_TSX=1   # Windows (PowerShell: $env:MCP_USE_TSX="1")
npm run dev

你应该会看到：

• 工具发现
• 编辑器状态/信息/通知
• 控制台读取/清除
• 创建/更新/删除 GameObject，以及组件操作
• 播放/暂停/恢复/停止
• 场景保存/另存为
• 包列表

---

可视化脚本集成 🎨

Unity MCP Bridge 现已包含强大的可视化脚本集成功能，支持通过 MCP 操作和自然语言命令创建 Unity 可视化脚本图。

主要功能

• 模板系统：为常见游戏开发模式提供预构建工作流模板
• MCP 到可视化脚本的转换：将 MCP 操作转换为可视化脚本节点
• 基于节点的工作流：使用可视化节点设计复杂工作流
• 自动连接：智能管理节点连接和流程

快速示例

// Apply a player setup template
await client.callTool("unity_visualscripting_templates", {
  action: "apply",
  templateName: "create_player_setup",
  gameObjectPath: "Player"
});

// Generate visual script from MCP operations
await client.callTool("unity_visualscripting", {
  action: "generateFromMcp",
  gameObjectPath: "GameManager",
  operations: [
    { tool: "unity_console", action: "clear", description: "Clear console", order: 1 },
    { tool: "unity_scene", action: "save", description: "Save scene", order: 2 }
  ],
  autoConnect: true
});

可用模板

• 玩家管理：包含组件的完整玩家设置
• 场景管理：场景转换和优化
• 资源管理：资源优化和验证工作流
• 测试与 QA：自动化测试流水线
• 构建与部署：完整的构建和部署流程

详细文档请参阅可视化脚本集成指南。

---

安全 🔐

• 桥接服务绑定到 127.0.0.1，并支持可选的 X-Unity-Bridge-Token
• 在 Unity 和 MCP 服务环境中设置 UNITY_BRIDGE_TOKEN 以进行身份验证

---

故障排除 ❓

• ECONNREFUSED/超时 — 确保 Unity Editor 已打开、已安装包，并且控制台显示桥接服务正在运行
• 401 Unauthorized — 在服务端和 Unity 中设置 UNITY_BRIDGE_TOKEN（也支持 EditorPrefs 键 MCP_UnityBridge_Token）
• 端口被占用 — 另一个服务正在使用 58888；请关闭该服务或调整环境
• 场景/资源路径 — 使用相对于项目的 Assets/... 路径
• 编译时域重载 — 桥接服务会在重载时重启监听器；编译完成后重试

---

开发者指南 🛠️

• 服务端：使用 @modelcontextprotocol/sdk、axios 和 eventsource 的 TypeScript（ESM）
• 客户端：用于调用大多数工具并打印 Unity 控制台差异的 TypeScript 示例
• Unity Bridge：仅供 Editor 使用的 C# 包（HttpListener + SSE + 主线程队列）

构建/测试命令：

# Server
cd MCP/server
npm run dev      # tsx
npm run build    # tsc
node dist/index.js

# Client (optional)
cd MCP/client
npm run dev      # tsx

---