# Unity MCP CLI Usage Guide

> **For AI Assistants and Developers**: This document explains the correct syntax and common pitfalls when using the Unity MCP CLI.

## Table of Contents

1. [Installation](#installation)
2. [Quick Start](#quick-start)
3. [Command Structure](#command-structure)
4. [Global Options](#global-options)
5. [Argument vs Option Syntax](#argument-vs-option-syntax)
6. [Common Mistakes and Corrections](#common-mistakes-and-corrections)
7. [Output Formats](#output-formats)
8. [Command Reference by Category](#command-reference-by-category)

---

## Installation

### Prerequisites

- **Python 3.10+** installed
- **Unity Editor** running with the MCP plugin enabled
- **MCP Server** running (HTTP transport on port 8080)

### Install via pip (from source)

```bash
# Navigate to the Server directory
cd /path/to/unity-mcp/Server

# Install in development mode
pip install -e .

# Or install with uv (recommended)
uv pip install -e .
```

### Install via uv tool

```bash
# Run directly without installing
uvx --from /path/to/unity-mcp/Server unity-mcp --help

# Or install as a tool
uv tool install /path/to/unity-mcp/Server
```

### Verify Installation

```bash
# Check version
unity-mcp --version

# Check help
unity-mcp --help

# Test connection to Unity
unity-mcp status
```

---

## Quick Start

### 1. Start the MCP Server

Make sure the Unity MCP server is running with HTTP transport:

```bash
# The server is typically started via the Unity-MCP window, select HTTP local, and start server, or try this manually:
cd /path/to/unity-mcp/Server
uv run mcp-for-unity --transport http --http-url http://localhost:8080
```

### 2. Verify Connection

```bash
unity-mcp status
```

Expected output:
```
Checking connection to 127.0.0.1:8080...
✅ Connected to Unity MCP server at 127.0.0.1:8080

Connected Unity instances:
  • MyProject (Unity 6000.2.10f1) [09abcc51]
```

### 3. Run Your First Commands

```bash
# Get scene hierarchy
unity-mcp scene hierarchy

# Create a cube
unity-mcp gameobject create "MyCube" --primitive Cube

# Move the cube
unity-mcp gameobject modify "MyCube" --position 0 2 0

# Take a screenshot
unity-mcp scene screenshot

# Enter play mode
unity-mcp editor play
```

### 4. Get Help on Any Command

```bash
# List all commands
unity-mcp --help

# Help for a command group
unity-mcp gameobject --help

# Help for a specific command
unity-mcp gameobject create --help
```

---

## Command Structure

The CLI follows this general pattern:

```
unity-mcp [GLOBAL_OPTIONS] COMMAND_GROUP [SUBCOMMAND] [ARGUMENTS] [OPTIONS]
```

**Example breakdown:**
```bash
unity-mcp -f json gameobject create "MyCube" --primitive Cube --position 0 1 0
#         ^^^^^^^ ^^^^^^^^^^^ ^^^^^^ ^^^^^^^^ ^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^
#         global  cmd group   subcmd argument option          multi-value option
```

---

## Global Options

Global options come **BEFORE** the command group:

| Option | Short | Description | Default |
|--------|-------|-------------|---------|
| `--host` | `-h` | MCP server host | `127.0.0.1` |
| `--port` | `-p` | MCP server port | `8080` |
| `--format` | `-f` | Output format: `text`, `json`, `table` | `text` |
| `--timeout` | `-t` | Command timeout in seconds | `30` |
| `--instance` | `-i` | Target Unity instance (hash or Name@hash) | auto |
| `--verbose` | `-v` | Enable verbose output | `false` |

**✅ Correct:**
```bash
unity-mcp -f json scene hierarchy
unity-mcp --format json --timeout 60 gameobject find "Player"
```

**❌ Wrong:**
```bash
unity-mcp scene hierarchy -f json  # Global option after command
```

---

## Argument vs Option Syntax

### Arguments (Positional)
Arguments are **required values** that come in a specific order, **without** flags.

```bash
unity-mcp gameobject find "Player"
#                         ^^^^^^^^ This is an ARGUMENT (positional)
```

### Options (Named)
Options use `--name` or `-n` flags and can appear in any order after arguments.

```bash
unity-mcp gameobject create "MyCube" --primitive Cube
#                                    ^^^^^^^^^^^ ^^^^ This is an OPTION with value
```

### Multi-Value Options
Some options accept multiple values. **Do NOT use commas** - use spaces:

**✅ Correct:**
```bash
unity-mcp gameobject modify "Cube" --position 1 2 3
unity-mcp gameobject modify "Cube" --rotation 0 45 0
unity-mcp gameobject modify "Cube" --scale 2 2 2
```

**❌ Wrong:**
```bash
unity-mcp gameobject modify "Cube" --position "1,2,3"   # Wrong: comma-separated string
unity-mcp gameobject modify "Cube" --position 1,2,3    # Wrong: comma-separated
unity-mcp gameobject modify "Cube" -pos "1 2 3"        # Wrong: quoted as single string
```

---

## Common Mistakes and Corrections

### 1. Multi-Value Options (Position, Rotation, Scale, Color)

These options expect **separate float arguments**, not comma-separated strings:

| Option | ❌ Wrong | ✅ Correct |
|--------|----------|-----------|
| `--position` | `--position "2,1,0"` | `--position 2 1 0` |
| `--rotation` | `--rotation "0,45,0"` | `--rotation 0 45 0` |
| `--scale` | `--scale "1,1,1"` | `--scale 1 1 1` |
| Color args | `1,0,0,1` | `1 0 0 1` |

**Example - Moving a GameObject:**
```bash
# Wrong - will error "requires 3 arguments"
unity-mcp gameobject modify "Cube" --position "2,1,0"

# Correct
unity-mcp gameobject modify "Cube" --position 2 1 0
```

**Example - Setting material color:**
```bash
# Wrong
unity-mcp material set-color "Assets/Mat.mat" 1,0,0,1

# Correct (R G B or R G B A as separate args)
unity-mcp material set-color "Assets/Mat.mat" 1 0 0
unity-mcp material set-color "Assets/Mat.mat" 1 0 0 1
```

### 2. Argument Order Matters

Some commands have multiple positional arguments. Check `--help` to see the order:

**Material assign:**
```bash
# Wrong - arguments in wrong order
unity-mcp material assign "TestCube" "Assets/Materials/Red.mat"

# ✅ Correct - MATERIAL_PATH comes before TARGET
unity-mcp material assign "Assets/Materials/Red.mat" "TestCube"
```

**Prefab create:**
```bash
# Wrong - using --path option that doesn't exist
unity-mcp prefab create "Cube" --path "Assets/Prefabs/Cube.prefab"

# Correct - PATH is a positional argument
unity-mcp prefab create "Cube" "Assets/Prefabs/Cube.prefab"
```

### 3. Using Options That Don't Exist

Always check `--help` before assuming an option exists:

```bash
# Check available options for any command
unity-mcp gameobject modify --help
unity-mcp material assign --help
unity-mcp prefab create --help
```

### 4. Property Names for Materials

Different shaders use different property names. Use `material info` to discover them:

```bash
# First, check what properties exist
unity-mcp material info "Assets/Materials/MyMat.mat"

# Then use the correct property name
# For URP shaders, often "_BaseColor" instead of "_Color"
unity-mcp material set-color "Assets/Mat.mat" 1 0 0 --property "_BaseColor"
```

### 5. Search Methods

When targeting GameObjects, specify how to search:

```bash
# By name (default)
unity-mcp gameobject modify "Player" --position 0 0 0

# By instance ID (use --search-method)
unity-mcp gameobject modify "-81840" --search-method by_id --position 0 0 0

# By path
unity-mcp gameobject modify "/Canvas/Panel/Button" --search-method by_path --active

# By tag
unity-mcp gameobject find "Player" --search-method by_tag
```

---

## Output Formats

### Text (Default)
Human-readable nested format:
```bash
unity-mcp scene active
# Output:
# status: success
# result:
#   name: New Scene
#   path: Assets/Scenes/New Scene.unity
#   ...
```

### JSON
Machine-readable JSON:
```bash
unity-mcp -f json scene active
# Output: {"status": "success", "result": {...}}
```

### Table
Key-value table format:
```bash
unity-mcp -f table scene active
# Output:
# Key    | Value
# -------+------
# status | success
# ...
```

---

## Command Reference by Category

### Status & Connection

```bash
# Check server connection and Unity instances
unity-mcp status

# List connected Unity instances
unity-mcp instances
```

### Scene Commands

```bash
# Get scene hierarchy
unity-mcp scene hierarchy

# Get active scene info
unity-mcp scene active

# Get build settings
unity-mcp scene build-settings

# Create new scene
unity-mcp scene create "MyScene"

# Load scene
unity-mcp scene load "Assets/Scenes/MyScene.unity"

# Save current scene
unity-mcp scene save

# Take screenshot
unity-mcp scene screenshot
unity-mcp scene screenshot --filename "my_screenshot" --supersize 2
```

### GameObject Commands

```bash
# Find GameObjects
unity-mcp gameobject find "Player"
unity-mcp gameobject find "Enemy" --method by_tag
unity-mcp gameobject find "-81840" --method by_id
unity-mcp gameobject find "Rigidbody" --method by_component

# Create GameObject
unity-mcp gameobject create "Empty"                    # Empty object
unity-mcp gameobject create "MyCube" --primitive Cube  # Primitive
unity-mcp gameobject create "MyObj" --position 0 5 0   # With position
unity-mcp gameobject create "Player" --components "Rigidbody,BoxCollider"  # With components

# Modify GameObject
unity-mcp gameobject modify "Cube" --position 1 2 3
unity-mcp gameobject modify "Cube" --rotation 0 45 0
unity-mcp gameobject modify "Cube" --scale 2 2 2
unity-mcp gameobject modify "Cube" --name "NewName"
unity-mcp gameobject modify "Cube" --active           # Enable
unity-mcp gameobject modify "Cube" --inactive         # Disable
unity-mcp gameobject modify "Cube" --tag "Player"
unity-mcp gameobject modify "Cube" --parent "Parent"

# Delete GameObject
unity-mcp gameobject delete "Cube"
unity-mcp gameobject delete "Cube" --force            # Skip confirmation

# Duplicate GameObject
unity-mcp gameobject duplicate "Cube"

# Move relative to another object
unity-mcp gameobject move "Cube" --reference "Player" --direction up --distance 2
```

### Component Commands

```bash
# Add component
unity-mcp component add "Cube" Rigidbody
unity-mcp component add "Cube" BoxCollider

# Remove component
unity-mcp component remove "Cube" Rigidbody
unity-mcp component remove "Cube" Rigidbody --force  # Skip confirmation

# Set single property
unity-mcp component set "Cube" Rigidbody mass 5
unity-mcp component set "Cube" Rigidbody useGravity false
unity-mcp component set "Cube" Light intensity 2.5

# Set multiple properties at once
unity-mcp component modify "Cube" Rigidbody --properties '{"mass": 5, "drag": 0.5}'
```

### Asset Commands

```bash
# Search assets
unity-mcp asset search "Player"
unity-mcp asset search "t:Material"        # By type
unity-mcp asset search "t:Prefab Player"   # Combined

# Get asset info
unity-mcp asset info "Assets/Materials/Red.mat"

# Create asset
unity-mcp asset create "Assets/Materials/New.mat" Material

# Delete asset
unity-mcp asset delete "Assets/Materials/Old.mat"
unity-mcp asset delete "Assets/Materials/Old.mat" --force  # Skip confirmation

# Move/Rename asset
unity-mcp asset move "Assets/Old/Mat.mat" "Assets/New/Mat.mat"
unity-mcp asset rename "Assets/Materials/Old.mat" "New"

# Create folder
unity-mcp asset mkdir "Assets/NewFolder"

# Import/reimport
unity-mcp asset import "Assets/Textures/image.png"
```

### Script Commands

```bash
# Create script
unity-mcp script create "MyScript" --path "Assets/Scripts"
unity-mcp script create "MyScript" --path "Assets/Scripts" --type MonoBehaviour

# Read script
unity-mcp script read "Assets/Scripts/MyScript.cs"

# Delete script
unity-mcp script delete "Assets/Scripts/MyScript.cs"

# Validate script
unity-mcp script validate "Assets/Scripts/MyScript.cs"
```

### Material Commands

```bash
# Create material
unity-mcp material create "Assets/Materials/New.mat"
unity-mcp material create "Assets/Materials/New.mat" --shader "Standard"

# Get material info
unity-mcp material info "Assets/Materials/Mat.mat"

# Set color (R G B or R G B A)
unity-mcp material set-color "Assets/Materials/Mat.mat" 1 0 0
unity-mcp material set-color "Assets/Materials/Mat.mat" 1 0 0 --property "_BaseColor"

# Set shader property
unity-mcp material set-property "Assets/Materials/Mat.mat" "_Metallic" 0.5

# Assign to GameObject
unity-mcp material assign "Assets/Materials/Mat.mat" "Cube"
unity-mcp material assign "Assets/Materials/Mat.mat" "Cube" --slot 1

# Set renderer color directly
unity-mcp material set-renderer-color "Cube" 1 0 0 1
```

### Editor Commands

```bash
# Play mode control
unity-mcp editor play
unity-mcp editor pause
unity-mcp editor stop

# Console
unity-mcp editor console                    # Read console
unity-mcp editor console --count 20         # Last 20 entries
unity-mcp editor console --clear            # Clear console
unity-mcp editor console --types error,warning  # Filter by type

# Menu items
unity-mcp editor menu "Edit/Preferences"
unity-mcp editor menu "GameObject/Create Empty"

# Tags and Layers
unity-mcp editor add-tag "Enemy"
unity-mcp editor remove-tag "Enemy"
unity-mcp editor add-layer "Interactable"
unity-mcp editor remove-layer "Interactable"

# Editor tool
unity-mcp editor tool View
unity-mcp editor tool Move
unity-mcp editor tool Rotate

# Run tests
unity-mcp editor tests
unity-mcp editor tests --mode PlayMode
```

### Custom Tools

```bash
# List custom tools / default tools for the active Unity project
unity-mcp tool list
unity-mcp custom_tool list

# Execute a custom tool by name
unity-mcp editor custom-tool "MyBuildTool"
unity-mcp editor custom-tool "Deploy" --params '{"target": "Android"}'
```

### Prefab Commands

```bash
# Create prefab from scene object
unity-mcp prefab create "Cube" "Assets/Prefabs/Cube.prefab"
unity-mcp prefab create "Cube" "Assets/Prefabs/Cube.prefab" --overwrite

# Open prefab for editing
unity-mcp prefab open "Assets/Prefabs/Player.prefab"

# Save open prefab
unity-mcp prefab save

# Close prefab stage
unity-mcp prefab close
```

### UI Commands

```bash
# Create a Canvas (adds Canvas, CanvasScaler, GraphicRaycaster)
unity-mcp ui create-canvas "MainCanvas"
unity-mcp ui create-canvas "WorldUI" --render-mode WorldSpace

# Create UI elements (must have a parent Canvas)
unity-mcp ui create-text "TitleText" --parent "MainCanvas" --text "Hello World"
unity-mcp ui create-button "StartButton" --parent "MainCanvas" --text "Click Me"
unity-mcp ui create-image "Background" --parent "MainCanvas"
```

### Lighting Commands

```bash
# Create lights with type, color, intensity
unity-mcp lighting create "Sun" --type Directional
unity-mcp lighting create "Lamp" --type Point --intensity 2 --position 0 5 0
unity-mcp lighting create "Spot" --type Spot --color 1 0 0 --intensity 3
unity-mcp lighting create "GreenLight" --type Point --color 0 1 0
```

### Audio Commands

```bash
# Control AudioSource (target must have AudioSource component)
unity-mcp audio play "MusicPlayer"
unity-mcp audio stop "MusicPlayer"
unity-mcp audio volume "MusicPlayer" 0.5
```

### Animation Commands

```bash
# Control Animator (target must have Animator component)
unity-mcp animation play "Character" "Walk"
unity-mcp animation set-parameter "Character" "Speed" 1.5 --type float
unity-mcp animation set-parameter "Character" "IsRunning" true --type bool
unity-mcp animation set-parameter "Character" "Jump" "" --type trigger
```

### Code Commands

```bash
# Read source files
unity-mcp code read "Assets/Scripts/Player.cs"
unity-mcp code read "Assets/Scripts/Player.cs" --start-line 10 --line-count 20
```

### Raw Commands

For advanced usage, send raw tool calls:

```bash
# Send any MCP tool directly
unity-mcp raw manage_scene '{"action": "get_active"}'
unity-mcp raw manage_gameobject '{"action": "create", "name": "Test"}'
unity-mcp raw manage_components '{"action": "add", "target": "Test", "componentType": "Rigidbody"}'
unity-mcp raw manage_editor '{"action": "play"}'
```

---

## Known Behaviors

### Component Creation

When creating GameObjects with components, the CLI creates the object first, then adds components separately. This is the correct workflow for Unity MCP.

```bash
# This works correctly - creates object then adds components
unity-mcp gameobject create "Player" --components "Rigidbody,BoxCollider"

# Equivalent to:
unity-mcp gameobject create "Player"
unity-mcp component add "Player" Rigidbody
unity-mcp component add "Player" BoxCollider
```

### Light Creation

The `lighting create` command creates a complete light with the specified type, color, and intensity:

```bash
# Creates Point light with green color and intensity 5
unity-mcp lighting create "GreenLight" --type Point --color 0 1 0 --intensity 5
```

### UI Element Creation

UI commands automatically add the required components:

```bash
# create-canvas adds: Canvas, CanvasScaler, GraphicRaycaster
unity-mcp ui create-canvas "MainUI"

# create-button adds: Image, Button
unity-mcp ui create-button "MyButton" --parent "MainUI"
```

---

## Quick Reference Card

### Multi-Value Syntax

```bash
--position X Y Z      # not "X,Y,Z"
--rotation X Y Z      # not "X,Y,Z"
--scale X Y Z         # not "X,Y,Z"
--color R G B         # not "R,G,B"
```

### Argument Order (check --help)

```bash
material assign MATERIAL_PATH TARGET
prefab create TARGET PATH
component set TARGET COMPONENT PROPERTY VALUE
```

### Search Methods

```bash
--method by_name      # default for gameobject find
--method by_id
--method by_path
--method by_tag
--method by_component
```

### Global Options Position

```bash
unity-mcp [GLOBAL_OPTIONS] command subcommand [ARGS] [OPTIONS]
#         ^^^^^^^^^^^^^^^^
#         Must come BEFORE command!
```

---

## Debugging Tips

1. **Always check `--help`** for any command:

   ```bash
   unity-mcp gameobject --help
   unity-mcp gameobject modify --help
   ```

2. **Use verbose mode** to see what's happening:

   ```bash
   unity-mcp -v scene hierarchy
   ```

3. **Use JSON output** for programmatic parsing:

   ```bash
   unity-mcp -f json gameobject find "Player" | jq '.result'
   ```

4. **Check connection first**:

   ```bash
   unity-mcp status
   ```

5. **When in doubt about properties**, use info commands:

   ```bash
   unity-mcp material info "Assets/Materials/Mat.mat"
   unity-mcp asset info "Assets/Prefabs/Player.prefab"
   ```
