Unity编辑器AI控制服务

Unity MCP服务器

直接从AI助手控制Unity编辑器。

该项目实现了 模型上下文协议（MCP） 在Unity编辑器内运行的服务器。它允许AI驱动的IDE，如 光标 通过自然语言操纵场景、编写脚本和控制游戏模式，在游戏开发中直接使用GenAI。

📖 目录

• 用户：快速入门
• 开发者：贡献
  • 支持的Unity版本和工作树
• 特性
• 可用工具、资源和提示
• 建筑
• 文档
• 许可证

🚀 用户：快速入门

想使用这个MCP服务器用AI构建Unity游戏吗？请按照以下步骤操作：

先决条件

• Unity 6.2、6.3 LTS或6.5 （参见 支持的版本 在......下面
• Node.js 18+
• 反重力, 光标IDE, VS代码与克劳德代码，或另一个兼容MCP的IDE

步骤1：安装Unity软件包

选项A：来自GitHub（推荐）

1. 打开Unity项目
2. 首选 窗口>包管理器
3. 点击 + → 从git URL添加包。。。
4. 输入：
   复制

   https://github.com/mitchchristow/unity-mcp.git?path=/Packages/org.christowm.unity.mcp
   

选项B：克隆用于本地开发

git clone https://github.com/mitchchristow/unity-mcp.git
cd unity-mcp

然后在Unity Hub中打开文件夹。

步骤2：安装网关依赖项

cd gateway
npm install

步骤3：连接IDE

光标(✅ 完全支持）

Cursor是推荐的具有完全MCP支持的IDE。

1. 打开Unity并等待 [MCP] HTTP Server started 在控制台中
2. 在Cursor中打开项目文件夹
3. MCP服务器通过以下方式自动启动 .cursor/mcp.json
4. 开始聊天！尝试： 在（0,1,0）位置创建一个红色立方体

手动设置 （如果自动检测失败）：

创建 .cursor/mcp.json:

{
  "mcpServers": {
    "unity": {
      "command": "node",
      "args": ["./gateway/index.js"],
      "cwd": "${workspaceFolder}"
    }
  }
}

反重力(⚠️ 仅全局配置）

备注：根据 反重力MCP文件，反重力 仅支持全局MCP配置。每个项目的配置不可用。

设置：

1. 开放反重力→ Click "..." → “管理MCP服务器” → “查看原始配置”
2. 添加此配置（更新安装路径）：

{
  "mcpServers": {
    "unity": {
      "command": "node",
      "args": ["/absolute/path/to/unity-mcp/gateway/index.js"],
      "cwd": "/absolute/path/to/unity-mcp"
    }
  }
}

看 反重力集成指南 详细说明。

VS代码(✅ 通过Kilo、Copilot和Claude Code支持）

VS Code通过以下方式支持MCP服务器 千, GitHub Copilot，以及 克劳德代码 扩展（和其他）。

自动设置： 此存储库包括 .vscode/mcp.json 文件。如果您在安装了GitHub Copilot或Kilo扩展的VS Code中打开此文件夹，则应自动检测到Unity MCP服务器。

手动设置（Kilo/GitHub Copilot）： 如果要将Unity MCP服务器添加到其他工作区：

1. 创建一个 .vscode/mcp.json 项目根目录中的文件。
2. 添加配置：
   复制

   {
     "servers": {
       "unity": {
         "command": "node",
         "args": ["/path/to/unity-mcp/gateway/index.js"],
         "type": "stdio"
       }
     }
   }
   

Claude代码设置： 此存储库包括 .mcp.json Claude代码支持文件。如果你有 克劳德代码 如果扩展安装在VS Code中，则打开此项目时将自动检测到Unity MCP服务器。

对于在其他工作区中的手动设置，请创建 .mcp.json 项目根目录中的文件：

{
  "mcpServers": {
    "unity": {
      "command": "node",
      "args": ["./gateway/index.js"],
      "cwd": "${workspaceFolder}"
    }
  }
}

看 VS代码集成指南 了解更多详情。

第四步：开始建设！

连接后，您可以使用自然语言控制Unity：

• “使用WASD动作创建2D玩家角色”
• “将Rigidbody2D添加到所选对象”
• “建立回合制战斗系统”
• “我的场景中有什么物体？”

🛠 开发者：贡献

想要扩展MCP服务器、修复错误或添加新功能吗？这部分是给你的。

开发设置

1. 克隆存储库:

   复制

   git clone https://github.com/mitchchristow/unity-mcp.git
   cd unity-mcp
   

2. 在Unity中打开：打开repo根（或 版本工作台)在Unity Hub。

3. 安装网关依赖项:

   复制

   cd gateway
   npm install
   

4. 项目结构:

   复制

   unity-mcp/
   ├── Packages/org.christowm.unity.mcp/   # Unity Editor package
   │   └── Editor/
   │       ├── MCP/                        # MCP server implementation
   │       │   ├── Rpc/Controllers/        # RPC method handlers
   │       │   ├── McpObjectReference.cs   # Unity 6.2–6.5 object ID bridge
   │       │   ├── Events/                 # WebSocket event system
   │       │   └── Progress/               # Progress tracking
   │       ├── Networking/                 # HTTP & WebSocket servers
   │       └── IPC/                        # Named Pipe server
   ├── gateway/                            # Node.js MCP gateway
   │   └── index.js                        # Tool/Resource/Prompt definitions
   ├── Docs/                               # Documentation (Docusaurus)
   ├── .cursor/                            # Cursor IDE MCP config
   ├── ide-integrations/                   # IDE config templates
   │   ├── antigravity/                    # Global config template
   │   └── vscode/                         # VS Code extension (WIP)
   └── TODO.md                             # Future improvements roadmap
   

支持的Unity版本和工作树

该项目在三个Unity 6编辑器行上进行了测试。 为每个版本使用单独的项目文件夹 所以 ProjectSettings/ 和 Library/ 在切换编辑器时不会被覆盖。

回购根(unity-mcp/)继续 main 用于git工作和一般开发。版本工作树是 仅限本地 (/worktrees/ 在...里 .gitignore).

创建工作树 （从repo根目录开始，克隆后）：

git worktree add -B worktree/unity-620      worktrees/unity-620      main
git worktree add -B worktree/unity-630-lts  worktrees/unity-630-lts  main
git worktree add -B worktree/unity-6500     worktrees/unity-6500     main

使用匹配的编辑器打开Unity Hub中的每个文件夹。预计Unity将升级该副本 ProjectVersion.txt 在首次启动时，这是正常的，并且保持在该工作台的本地。

对象ID: Unity 6.5返回大 ulong 导线上的实体ID；6.2/6.3使用 int 实例ID。包裹代码路由通过 McpObjectReference (#if UNITY_6000_5_OR_NEWER).

添加新功能

添加新工具

1. 创建/更新控制器 在 Packages/.../Rpc/Controllers/:

   复制

   public static class MyController
   {
       public static void Register()
       {
           JsonRpcDispatcher.RegisterMethod("unity.my_method", MyMethod);
       }
       
       private static JObject MyMethod(JObject p)
       {
           // Implementation
           return new JObject { ["ok"] = true };
       }
   }
   

2. 注册于 McpServer.cs:

   复制

   MyController.Register();
   

3. 在中添加工具定义 gateway/index.js:

   复制

   {
     name: "unity_my_tool",
     description: "What this tool does",
     inputSchema: {
       type: "object",
       properties: { /* ... */ },
       required: ["param1"],
     },
   },
   

4. 添加处理程序 在 CallToolRequestSchema 如果需要，请使用处理器。

添加新资源

1. 在Unity中添加RPC方法（类似于工具）
2. 将资源定义添加到 RESOURCES 数组in gateway/index.js
3. 将URI添加到中的方法映射 ReadResourceRequestSchema 处理器

添加新提示

添加到 PROMPTS 数组和实现 generatePromptContent() 函数 gateway/index.js.

测试

快速RPC检查 （Unity打开，MCP服务器正在运行）：

curl -X POST http://localhost:17890/mcp/rpc \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"unity.get_project_info","params":{},"id":1}'

烟雾测试 （验证图元→ 转变→ 任何支持的Unity版本上的材料）：

1. unity.create_primitive — Sphere，名称例如。 SmokeSphere
2. unity.set_transform --职位 (0,0,0)，规模 (5,5,5)
3. unity.create_material --例如。 SmokeMaterial （标准着色器）
4. unity.set_material_property --set _Color （例如红色或黄色）
5. unity.set_material --将材质应用于球体
6. unity.get_object_details --确认转换和材料

批量干运行： 打电话给 unity_batch 工具与 "dryRun": true 验证工具名称和 $N 插值而不修改场景。

操作审核日志： 阅读 unity://operations/history 用于查看网关记录的最近MCP工具调用的资源（工具名称、参数、成功/错误、持续时间）。

EditMode测试： 窗口→ 通用→ 测试运行器→ 编辑模式（包中有4个测试）。

# WebSocket events
wscat -c ws://localhost:17891/mcp/events

需要了解的关键文件

拉取请求指南

1. 创建要素分支： feature/my-feature
2. 遵循现有代码样式
3. 如果添加面向用户的功能，请更新文档
4. 使用Cursor进行测试，以验证MCP集成
5. 更新 TODO.md 如果实施积压项目

看 TODO.md 计划改进的路线图。

✨ 特性

📦 可用工具、资源和提示

工具（80）

服务器暴露 80工具 按类别组织。许多人使用 action 参数以合并相关操作。

{
  "dryRun": true,
  "operations": [
    { "tool": "unity_create_primitive", "args": { "type": "Cube", "name": "TestCube" } },
    { "tool": "unity_set_transform", "args": { "id": "$0.id", "position": { "x": 0, "y": 1, "z": 0 } } }
  ]
}

资源（43）

资源提供 只读上下文 AI会自动读取。

提示（8）

用于复杂任务的预定义工作流模板：

🏗 建筑

┌─────────────┐     stdio      ┌─────────────┐     HTTP      ┌─────────────┐
│   IDE/AI    │ ◄────────────► │   Gateway   │ ◄───────────► │    Unity    │
│  (Cursor)   │     MCP        │  (Node.js)  │   JSON-RPC    │   Editor    │
└─────────────┘                └─────────────┘               └─────────────┘
                                     │
                                     │ WebSocket
                                     ▼
                               Real-time Events

组件

演出

• 通过以下方式连续处理请求队列 EditorApplication.update
• Unity处于后台时自动唤醒编辑器
• 典型响应时间： 30-175毫秒

📚 文档

完整文档可在 Docs/ 目录：

• RPC API参考
• 2D开发指南
• 脚本辅助
• 事件系统
• IDE配置

另请参见： TODO.md 计划中的改进。

🐛 问题和功能请求

• 错误报告: 打开一个问题 带有复制步骤
• 功能请求: 打开一个问题 并为其添加标签 enhancement
• 问题：使用 GitHub讨论 或打开一个问题

看 TODO.md 规划功能的路线图。

📄 许可证

MIT许可证-请参阅 许可证 了解详情。

由以下材料制成❤️ Unity+AI社区