SKILL: unity-mcp

Overview

A reference guide for deploying and using the Unity MCP Server, covering API operations, data type formats, and common issue resolution.

Complete deployment guide, API usage tips, and troubleshooting manual for the Unity MCP (Model Context Protocol) Server.

Description

This skill covers:

• Starting and connecting the Unity MCP Server
• Common API operations (GameObject, Component, Scene, Asset)
• Parameter format specifications (Color, Vector3, and other special types)
• Common problem troubleshooting and resolution approaches

When to Use

• You need to control the Unity editor via AI automation
• You are batch-creating or modifying GameObjects, components, or scenes
• You are programmatically generating Unity assets or scripts
• You encounter connection issues, session errors, or data type format problems with Unity MCP
• You need to remotely debug or inspect a Unity scene

Do not use when:

• The task is purely about Unity game logic coding without MCP integration
• You only need general Unity scripting help without editor automation
• You are working with a different MCP server or game engine

When to Invoke

Usage scenarios:

• Need to control the Unity editor via AI to perform automated operations
• Batch create/modify scene objects, components
• Procedurally generate assets or scripts
• Remote debugging and scene inspection
• Automated testing workflows

Prerequisites

Environment requirements:

• Unity 6000+ (or other supported versions)
• Unity MCP plugin/package installed
• Python uvx tool

1. Check if MCP Plugin is Installed

Check in the Unity editor:

• Whether the menu bar has MCP or Window → MCP
• Whether the Project window has MCP or McpForUnity related folders

If the MCP plugin is not installed:

1. Install via Unity Asset Store:
   • Open Window → Package Manager
   • Select Unity Registry or My Assets
   • Search for "MCP" or "MCP for Unity"
   • Click Install
2. Or install via Git URL:
   • Package Manager → + → Add package from git URL
   • Enter: https://github.com/anthropics/unity-mcp.git
   • Click Add
3. Restart Unity after installation

2. Check if uvx is Installed

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

# macOS/Linux
which uvx

If not installed:

1. In the Unity editor, open Window → MCP → Local Setup
2. Click "Install" or "Setup Environment"
3. Wait for automatic download and installation of uvx and related dependencies
4. Restart the terminal/IDE to load the new environment variables

Plugin source:

• Unity MCP Server: mcpforunityserver>=0.0.0a0

Deployment

1. Start the MCP Server

Check uvx Installation Location

uvx is usually installed in the following locations:

Windows:

# Standard installation path
$env:USERPROFILE\.local\bin\uvx.exe
# Or
C:\Users\<Username>\.local\bin\uvx.exe

# Check if it exists
Test-Path "$env:USERPROFILE\.local\bin\uvx.exe"

macOS/Linux:

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

If uvx Does Not Exist

⚠️ Prompt the user:

uvx tool not found. Please do the following in the Unity editor:
1. Open Window → MCP → Local Setup
2. Click "Install Dependencies" or "Setup Local Environment"
3. Wait for the installation to complete
4. Try starting the MCP Server again

Start Command

Windows (dynamic path):

$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 "Error: uvx not found. Please install dependencies by clicking MCP → Local Setup in Unity."
}

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

Note:

• First launch will download Python dependencies (approx. 30MB, takes 1-2 minutes)
• Keep it running, do not close the terminal
• Use --project-scoped-tools to enable project-level tools

2. Connection Flow

1. Initialize session
   POST http://localhost:8080/mcp
   Headers: Accept: application/json, text/event-stream
   Body: {"jsonrpc":"2.0","id":1,"method":"initialize",...}
   ↓
2. Extract Session ID (from response header mcp-session-id)
   ↓
3. Set active Unity instance
   ↓
4. Execute tool calls

PowerShell Example:

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

# Initialize
$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"]

# Set active instance
$setInstance = '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"set_active_instance","arguments":{"instance":"ProjectName@hash"}}}'

Common Operations

GameObject Management

// Create empty object
{
  "name": "manage_gameobject",
  "arguments": {
    "action": "create",
    "name": "MyObject",
    "position": [0, 0, 0]
  }
}

// Create Sprite object (2D)
{
  "action": "create",
  "name": "Tree2D",
  "position": [1, 2, 0]
}
// Then add SpriteRenderer component

// Delete object
{
  "action": "delete",
  "name": "MyObject"
}

Component Management

// Add component
{
  "name": "manage_components",
  "arguments": {
    "action": "add",
    "target": "Tree2D",
    "component_type": "SpriteRenderer"
  }
}

// Set property ⚠️ Pay attention to type format
{
  "action": "set_property",
  "target": "Tree2D",
  "component_type": "SpriteRenderer",
  "property": "color",
  "value": {"r": 0.1, "g": 0.5, "b": 0.2, "a": 1.0}  // ✅ Object format
  // ❌ Incorrect: [0.1, 0.5, 0.2, 1]
}

Scene Management

// Create scene
{
  "name": "manage_scene",
  "arguments": {
    "action": "create",
    "name": "MyScene",
    "path": "MyFolder"
  }
}

// Save scene
{
  "action": "save"
}

// Get hierarchy
{
  "action": "get_hierarchy",
  "page_size": 50
}

Asset Management

// Create folder
{
  "name": "manage_asset",
  "arguments": {
    "action": "create_folder",
    "path": "MyFolder"
  }
}

// Create texture
{
  "action": "create",
  "width": 64,
  "height": 64,
  "path": "MyFolder/Texture.png"
}

// Search assets
{
  "action": "search",
  "path": "MyFolder",
  "page_size": 50
}

Critical Data Types

⚠️ Color Format

Incorrect format (array):

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

Correct format (object):

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

PowerShell construction:

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

Vector3 Format

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

Common Issues & Solutions

Issue -1: MCP Plugin Not Installed

Symptoms:

• No MCP or Window → MCP in the Unity menu
• No MCP-related folders in the Project
• Unable to find the MCP settings interface

Resolution steps:

1. Open Unity Asset Store:
   • Window → Package Manager
   • Switch to the Unity Registry tab
   • Search for "MCP" or "MCP for Unity"
2. Install the plugin:
   • Find the MCP for Unity package
   • Click Install
   • Wait for the installation to complete
3. Restart the Unity editor
4. Verify installation:
   • Check if the menu bar has MCP or Window → MCP
   • Check if the Project window has the MCP folder

Issue 0: uvx Not Found / Command Does Not Exist

Symptoms:

The term 'uvx' is not recognized as a cmdlet, function, operable program, or script file.
# Or
Cannot find part of the path "C:\Users\xxx\.local\bin\uvx.exe"

Cause:

• uvx is a dependency tool for Unity MCP and has not been installed yet
• The installation path varies depending on the system/user

Resolution steps:

1. Install in Unity:
   • Menu: Window → MCP → Local Setup
   • Click: Install Dependencies or Setup Local Environment
   • Wait for the installation to complete (may take a few minutes)
2. Verify installation:

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

3. Restart the terminal to load the new PATH environment variable

Dynamic path detection script:

function Get-UvxPath {
    # Try common paths
    $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 }
    }
    
    # Try to find from PATH
    $uvx = Get-Command uvx -ErrorAction SilentlyContinue
    if ($uvx) { return $uvx.Source }
    
    return $null
}

$uvxPath = Get-UvxPath
if (-not $uvxPath) {
    Write-Host "❌ uvx not found. Please install it by clicking Window → MCP → Local Setup in Unity."
    exit 1
}
Write-Host "✅ Found uvx: $uvxPath"

Issue 1: Unable to Set SpriteRenderer.sprite

Symptoms:

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

Cause:

• manage_texture creates a Texture2D, but SpriteRenderer requires a Sprite type
• The API does not support directly converting a path string to a Sprite reference

Solutions:

1. Manual method (recommended): Drag the texture onto the SpriteRenderer's Sprite field in Unity, and Unity will automatically convert it
2. Editor script: Write a tool script under the Editor folder to batch assign values
3. Pre-create Sprite: Use Unity's Sprite Editor to convert the texture into a Sprite asset

Issue 2: Color Format Error

Symptoms:

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

Solution: Use the object format {"r":x,"g":y,"b":z,"a":w} instead of the array [x,y,z,w]

Issue 3: Session Expired

Symptoms:

Missing session ID
Bad Request: Missing session ID

Solution:

• Re-initialize to get a new Session ID
• Ensure every request includes the mcp-session-id Header

Issue 4: Unity Instance Not Found / Cannot Find Active Instance

Symptoms:

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

Or

Active instance set to ... : false

Cause:

• The MCP Server has started, but the Unity editor has not yet established a connection with the Server
• The MCP Session in Unity has not been started

Resolution steps:

1. Ensure the Unity editor is open (and the project is loaded)
2. Start the MCP Session in Unity:
   • Menu: Window → MCP or MCP → Session
   • In the MCP window, find the Session or Connection section
   • Click the "Start Session" or "Connect" button
   • Wait for the status to change to "Connected" or "Running"
3. Check connection status:
   • The MCP window should display: Status: Connected or Transport: HTTP
   • Or display the currently connected Server address: http://localhost:8080
4. Re-fetch the instance list:

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

Full startup flow chart:

User Machine
├─ [1] Start MCP Server (uvx command)
│     └─ Waiting for connection...
│
└─ [2] Open Unity Editor
       └─ [3] Window → MCP → Start Session
              └─ Establish connection
                     ↓
              MCP Server detects instance
                     ↓
              instance_count: 1

Common Questions:

• Q: Nothing happens after clicking Start Session?
  • Check if the MCP Server is running (is the terminal window still open)
  • Check if port 8080 is occupied
  • Try restarting Unity and the MCP Server
• Q: Shows "Connection Failed"?
  • Confirm the MCP Server address is configured correctly (default: http://localhost:8080)
  • Check if the firewall is blocking the connection

Issue 5: Property Parameter Error

Symptoms:

Unexpected keyword argument 'xxx'

Solution: Check the API documentation and use the correct parameter names:

• ❌ "component": "SpriteRenderer" → ✅ "component_type": "SpriteRenderer"
• ❌ "filter": "All" → ✅ Not supported, omit or use the correct parameter

Workflow Patterns

Pattern 1: Complete Workflow for Creating a 2D Object

1. Create GameObject (empty object)
   manage_gameobject: create
   
2. Add SpriteRenderer component
   manage_components: add, component_type=SpriteRenderer
   
3. Set color
   manage_components: set_property, property=color, value={r,g,b,a}
   
4. Manually assign Sprite (API limitation)
   Or drag and drop the texture onto the Sprite field in Unity

Pattern 2: Batch Create Objects

$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) {
    # Create object
    # Add component
    # Set property
}

Pattern 3: Error Checking Workflow

1. Execute operation
2. Check console logs
   read_console: get
3. Verify result
   manage_scene: get_hierarchy
4. If there is an error, read specific component information
   resources/read: mcpforunity://scene/gameobject/{id}/components

API Limitations

Best Practices

1. Always save the scene Execute manage_scene: save after batch operations
2. Check the console Regularly use read_console to view errors
3. Use Instance ID Use the Instance ID instead of the name when operating on specific objects
4. Batch operations Use loops for batch creation to reduce the number of API calls
5. Error handling Check the success field after each operation

Quick Reference

Common Tool List

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