Unity MCP

SKILL: unity-mcp

Unity MCP (Model Context Protocol) Server 的完整部署指南、API 使用技巧和故障排查手册。

Description

本技能涵盖：

• Unity MCP Server 的启动与连接
• 常用 API 操作（GameObject、Component、Scene、Asset）
• 参数格式规范（Color、Vector3 等特殊类型）
• 常见问题排查与解决思路

When to Invoke

使用场景：

• 需要通过 AI 控制 Unity 编辑器执行自动化操作
• 批量创建/修改场景物体、组件
• 程序化生成资源或脚本
• 远程调试和场景检查
• 自动化测试工作流

Prerequisites

环境要求：

• Unity 6000+ (或其他支持版本)
• Unity MCP 插件/包已安装
• Python uvx 工具

1. 检查 MCP 插件是否安装

在 Unity 编辑器中检查：

• 菜单栏是否有 MCP 或 Window → MCP
• Project 窗口是否有 MCP 或 McpForUnity 相关文件夹

如果未安装 MCP 插件：

1. 通过 Unity Asset Store 安装:

   • 打开 Window → Package Manager
   • 选择 Unity Registry 或 My Assets
   • 搜索 "MCP" 或 "MCP for Unity"
   • 点击 Install 安装

2. 或通过 Git URL 安装:

   • Package Manager → + → Add package from git URL
   • 输入: https://github.com/anthropics/unity-mcp.git
   • 点击 Add

3. 安装后重启 Unity

2. 检查 uvx 是否安装

# Windows
Test-Path "$env:USERPROFILE\.local\bin\uvx.exe"

# macOS/Linux
which uvx

如果未安装:

1. 在 Unity 编辑器中打开 Window → MCP → Local Setup
2. 点击 "Install" 或 "Setup Environment"
3. 等待自动下载安装 uvx 和相关依赖
4. 重启终端/IDE 以加载新的环境变量

插件来源：

• Unity MCP Server: mcpforunityserver>=0.0.0a0

Deployment

1. 启动 MCP Server

检查 uvx 安装位置

uvx 通常安装在以下位置：

Windows:

# 标准安装路径
$env:USERPROFILE\.local\bin\uvx.exe
# 或
C:\Users\<用户名>\.local\bin\uvx.exe

# 检查是否存在
Test-Path "$env:USERPROFILE\.local\bin\uvx.exe"

macOS/Linux:

~/.local/bin/uvx
# 或
/usr/local/bin/uvx

如果 uvx 不存在

⚠️ 提示用户:

未找到 uvx 工具。请在 Unity 编辑器中：
1. 打开 Window → MCP → Local Setup
2. 点击 "Install Dependencies" 或 "Setup Local Environment"
3. 等待安装完成
4. 重新尝试启动 MCP Server

启动命令

Windows (动态路径):

$uvxPath = "$env:USERPROFILE\.local\bin\uvx.exe"
if (Test-Path $uvxPath) {
    & $uvxPath --prerelease explicit --from "mcpforunityserver>=0.0.0a0" mcp-for-unity --transport http --http-url http://localhost:8080 --project-scoped-tools
} else {
    Write-Host "错误: 未找到 uvx。请在 Unity 中点击 MCP → Local Setup 安装依赖。"
}

macOS/Linux:

~/.local/bin/uvx --prerelease explicit --from "mcpforunityserver>=0.0.0a0" mcp-for-unity --transport http --http-url http://localhost:8080 --project-scoped-tools

注意：

• 首次启动会下载 Python 依赖（约 30MB，需要 1-2 分钟）
• 保持运行，不要关闭终端
• 使用 --project-scoped-tools 启用项目级工具

2. 连接流程

1. 初始化会话
   POST http://localhost:8080/mcp
   Headers: Accept: application/json, text/event-stream
   Body: {"jsonrpc":"2.0","id":1,"method":"initialize",...}
   ↓
2. 提取 Session ID (从响应头 mcp-session-id)
   ↓
3. 设置活动 Unity 实例
   ↓
4. 执行工具调用

PowerShell 示例：

$headers = @{
    "Content-Type" = "application/json"
    "Accept" = "application/json, text/event-stream"
    "mcp-session-id" = "your-session-id"
}

# 初始化
$init = '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"openclaw","version":"1.0"}}}'
$response = Invoke-WebRequest -Uri "http://localhost:8080/mcp" -Method Post -Headers $headers -Body $init
$sessionId = $response.Headers["mcp-session-id"]

# 设置活动实例
$setInstance = '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"set_active_instance","arguments":{"instance":"ProjectName@hash"}}}'

Common Operations

GameObject 管理

// 创建空物体
{
  "name": "manage_gameobject",
  "arguments": {
    "action": "create",
    "name": "MyObject",
    "position": [0, 0, 0]
  }
}

// 创建 Sprite 物体（2D）
{
  "action": "create",
  "name": "Tree2D",
  "position": [1, 2, 0]
}
// 然后添加 SpriteRenderer 组件

// 删除物体
{
  "action": "delete",
  "name": "MyObject"
}

Component 管理

// 添加组件
{
  "name": "manage_components",
  "arguments": {
    "action": "add",
    "target": "Tree2D",
    "component_type": "SpriteRenderer"
  }
}

// 设置属性 ⚠️ 注意类型格式
{
  "action": "set_property",
  "target": "Tree2D",
  "component_type": "SpriteRenderer",
  "property": "color",
  "value": {"r": 0.1, "g": 0.5, "b": 0.2, "a": 1.0}  // ✅ 对象格式
  // ❌ 错误: [0.1, 0.5, 0.2, 1]
}

Scene 管理

// 创建场景
{
  "name": "manage_scene",
  "arguments": {
    "action": "create",
    "name": "MyScene",
    "path": "MyFolder"
  }
}

// 保存场景
{
  "action": "save"
}

// 获取层级
{
  "action": "get_hierarchy",
  "page_size": 50
}

Asset 管理

// 创建文件夹
{
  "name": "manage_asset",
  "arguments": {
    "action": "create_folder",
    "path": "MyFolder"
  }
}

// 创建纹理
{
  "action": "create",
  "width": 64,
  "height": 64,
  "path": "MyFolder/Texture.png"
}

// 搜索资源
{
  "action": "search",
  "path": "MyFolder",
  "page_size": 50
}

Critical Data Types

⚠️ Color 格式

错误格式（数组）：

"value": [0.1, 0.5, 0.2, 1.0]

正确格式（对象）：

"value": {"r": 0.1, "g": 0.5, "b": 0.2, "a": 1.0}

PowerShell 构造：

$color = @{r=0.1; g=0.5; b=0.2; a=1.0} | ConvertTo-Json -Compress
# 结果: {"r":0.1,"g":0.5,"b":0.2,"a":1}

Vector3 格式

"position": [1, 2, 3]
"scale": [1.5, 2, 1]
"rotation": [0, 90, 0]

Common Issues & Solutions

Issue -1: MCP 插件未安装

症状：

• Unity 菜单中没有 MCP 或 Window → MCP
• Project 中没有 MCP 相关文件夹
• 无法找到 MCP 设置界面

解决步骤：

1. 打开 Unity Asset Store:

   • Window → Package Manager
   • 切换到 Unity Registry 标签
   • 搜索 "MCP" 或 "MCP for Unity"

2. 安装插件:

   • 找到 MCP for Unity 包
   • 点击 Install
   • 等待安装完成

3. 重启 Unity 编辑器

4. 验证安装:

   • 检查菜单栏是否有 MCP 或 Window → MCP
   • 检查 Project 窗口是否有 MCP 文件夹

Issue 0: uvx 未找到 / 命令不存在

症状：

The term 'uvx' is not recognized as a cmdlet, function, operable program, or script file.
# 或
无法找到路径 "C:\Users\xxx\.local\bin\uvx.exe" 的一部分

原因：

• uvx 是 Unity MCP 的依赖工具，尚未安装
• 安装路径因系统/用户而异

解决步骤：

1. 在 Unity 中安装:

   • 菜单: Window → MCP → Local Setup
   • 点击: Install Dependencies 或 Setup Local Environment
   • 等待安装完成（可能需要几分钟）

2. 验证安装:

   # Windows
   Get-Command uvx
   # 或
   Test-Path "$env:USERPROFILE\.local\bin\uvx.exe"
   
   # macOS/Linux
   which uvx
   

3. 重启终端 以加载新的 PATH 环境变量

动态路径检测脚本:

function Get-UvxPath {
    # 尝试常见路径
    $paths = @(
        "$env:USERPROFILE\.local\bin\uvx.exe",
        "$env:LOCALAPPDATA\uv\uvx.exe",
        "C:\Program Files\uv\uvx.exe"
    )
    
    foreach ($path in $paths) {
        if (Test-Path $path) { return $path }
    }
    
    # 尝试从 PATH 查找
    $uvx = Get-Command uvx -ErrorAction SilentlyContinue
    if ($uvx) { return $uvx.Source }
    
    return $null
}

$uvxPath = Get-UvxPath
if (-not $uvxPath) {
    Write-Host "❌ 未找到 uvx。请在 Unity 中点击 Window → MCP → Local Setup 安装。"
    exit 1
}
Write-Host "✅ 找到 uvx: $uvxPath"

Issue 1: 无法设置 SpriteRenderer.sprite

症状：

Failed to convert value for property 'sprite' to type 'Sprite'

原因：

• manage_texture 创建的是 Texture2D，但 SpriteRenderer 需要 Sprite 类型
• API 不支持直接将路径字符串转为 Sprite 引用

解决方案：

1. 手动方式（推荐）：在 Unity 中将纹理拖到 SpriteRenderer 的 Sprite 字段，Unity 会自动转换
2. 编辑器脚本：编写 Editor 文件夹下的工具脚本批量赋值
3. 预创建 Sprite：使用 Unity 的 Sprite Editor 将纹理转为 Sprite 资源

Issue 2: Color 格式错误

症状：

Error converting token to UnityEngine.Color: Error reading JObject from JsonReader

解决： 使用对象格式 {"r":x,"g":y,"b":z,"a":w} 而非数组 [x,y,z,w]

Issue 3: Session 过期

症状：

Missing session ID
Bad Request: Missing session ID

解决：

• 重新初始化获取新 Session ID
• 确保每个请求都包含 mcp-session-id Header

Issue 4: Unity 实例未找到 / 找不到活跃实例

症状：

{
  "instance_count": 0,
  "instances": []
}

或

Active instance set to ... : false

原因：

• MCP Server 已启动，但 Unity 编辑器尚未与 Server 建立连接
• Unity 中的 MCP Session 未启动

解决步骤：

1. 确保 Unity 编辑器已打开（且项目已加载）

2. 在 Unity 中启动 MCP Session:

   • 菜单: Window → MCP 或 MCP → Session
   • 在 MCP 窗口中找到 Session 或 Connection 部分
   • 点击 "Start Session" 或 "Connect" 按钮
   • 等待状态变为 "Connected" 或 "Running"

3. 检查连接状态:

   • MCP 窗口应显示: Status: Connected 或 Transport: HTTP
   • 或显示当前连接的 Server 地址: http://localhost:8080

4. 重新获取实例列表:

   {
     "name": "resources/read",
     "params": {
       "uri": "mcpforunity://instances"
     }
   }
   

完整启动流程图:

用户机器
├─ [1] 启动 MCP Server (uvx 命令)
│     └─ 等待连接...
│
└─ [2] 打开 Unity 编辑器
       └─ [3] Window → MCP → Start Session
              └─ 建立连接
                     ↓
              MCP Server 检测到实例
                     ↓
              instance_count: 1

常见问题：

• Q: 点击 Start Session 后没有反应？

  • 检查 MCP Server 是否正在运行（终端窗口是否还在）
  • 检查端口 8080 是否被占用
  • 尝试重启 Unity 和 MCP Server

• Q: 显示 "Connection Failed"？

  • 确认 MCP Server 地址配置正确（默认: http://localhost:8080）
  • 检查防火墙是否阻止了连接

Issue 5: 属性参数错误

症状：

Unexpected keyword argument 'xxx'

解决： 检查 API 文档，使用正确的参数名：

• ❌ "component": "SpriteRenderer" → ✅ "component_type": "SpriteRenderer"
• ❌ "filter": "All" → ✅ 不支持，省略或使用正确参数

Workflow Patterns

Pattern 1: 创建2D物体完整流程

1. 创建 GameObject (空物体)
   manage_gameobject: create
   
2. 添加 SpriteRenderer 组件
   manage_components: add, component_type=SpriteRenderer
   
3. 设置颜色
   manage_components: set_property, property=color, value={r,g,b,a}
   
4. 手动赋值 Sprite（API限制）
   或在 Unity 中拖拽纹理到 Sprite 字段

Pattern 2: 批量创建物体

$objects = @(
    @{name="Obj1"; pos=@(1,2,0); color=@{r=1;g=0;b=0;a=1}},
    @{name="Obj2"; pos=@(-1,1,0); color=@{r=0;g=1;b=0;a=1}}
)

foreach ($obj in $objects) {
    # 创建物体
    # 添加组件
    # 设置属性
}

Pattern 3: 错误检查流程

1. 执行操作
2. 检查控制台日志
   read_console: get
3. 验证结果
   manage_scene: get_hierarchy
4. 如有错误，读取具体组件信息
   resources/read: mcpforunity://scene/gameobject/{id}/components

API Limitations

Best Practices

1. 始终保存场景 在批量操作后执行 manage_scene: save
2. 检查控制台 定期使用 read_console 查看错误
3. 使用 Instance ID 操作具体物体时使用而非名称
4. 批量操作 使用循环批量创建，减少 API 调用次数
5. 错误处理 每个操作后检查 success 字段

Quick Reference

常用工具列表

HTTP Headers (Required)

Content-Type: application/json
Accept: application/json, text/event-stream
mcp-session-id: <session-id>

Response Format

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [{
      "type": "text",
      "text": "{\"success\": true, ...}"
    }]
  }
}

References

• Unity MCP Server Docs
• MCP Protocol: https://modelcontextprotocol.io
• Unity Scripting API: https://docs.unity3d.com/ScriptReference/

Changelog

v1.0.0 (2026-02-11)

• Initial release
• Documented Color format issue
• Documented Sprite assignment limitation
• Added workflow patterns