coplaydev--unity-mcp/website/docs/guides/cli.md

Unity MCP CLI Usage Guide

The Unity MCP CLI provides command-line access to control the Unity Editor through the Model Context Protocol. It currently only supports local HTTP.

Note: Some tools are still experimental and might fail under some circumstances. Please submit an issue to help us make it better.

Installation

cd Server
pip install -e .
# Or with uv:
uv pip install -e .

Quick Start

# Check connection
unity-mcp status

# List Unity instances
unity-mcp instance list

# Get scene hierarchy
unity-mcp scene hierarchy

# Find a GameObject
unity-mcp gameobject find "Player"

Global Options

Option	Env Variable	Description
-h, --host	UNITY_MCP_HOST	Server host (default: 127.0.0.1)
-p, --port	UNITY_MCP_HTTP_PORT	Server port (default: 8080)
-t, --timeout	UNITY_MCP_TIMEOUT	Timeout in seconds (default: 30)
-f, --format	UNITY_MCP_FORMAT	Output format: text, json, table
-i, --instance	UNITY_MCP_INSTANCE	Target Unity instance

Command Reference

Instance Management

# List connected Unity instances
unity-mcp instance list

# Set active instance
unity-mcp instance set "ProjectName@abc123"

# Show current instance
unity-mcp instance current

Scene Operations

# Get scene hierarchy
unity-mcp scene hierarchy
unity-mcp scene hierarchy --limit 20 --depth 3

# Get active scene info
unity-mcp scene active

# Load/save scenes
unity-mcp scene load "Assets/Scenes/Main.unity"
unity-mcp scene save

# Screenshots (use camera command)
unity-mcp camera screenshot
unity-mcp camera screenshot --file-name "level_preview"
unity-mcp camera screenshot --camera-ref "SecondCamera" --include-image
unity-mcp camera screenshot --batch surround --max-resolution 256
unity-mcp camera screenshot --batch orbit --view-target "Player"
unity-mcp camera screenshot --capture-source scene_view --view-target "Canvas" --include-image
unity-mcp camera screenshot-multiview --view-target "Player" --max-resolution 480

GameObject Operations

# Find GameObjects
unity-mcp gameobject find "Player"
unity-mcp gameobject find "Enemy" --method by_tag

# Create GameObjects
unity-mcp gameobject create "NewCube" --primitive Cube
unity-mcp gameobject create "Empty" --position 0 5 0

# Modify GameObjects
unity-mcp gameobject modify "Cube" --position 1 2 3 --rotation 0 45 0

# Delete/duplicate
unity-mcp gameobject delete "OldObject" --force
unity-mcp gameobject duplicate "Template"

Component Operations

# Add component
unity-mcp component add "Player" Rigidbody

# Remove component
unity-mcp component remove "Player" Rigidbody

# Set property
unity-mcp component set "Player" Rigidbody mass 10

Script Operations

# Create script
unity-mcp script create "PlayerController" --path "Assets/Scripts"

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

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

Code Search

# Search with regex
unity-mcp code search "class.*Player" "Assets/Scripts/Player.cs"
unity-mcp code search "TODO|FIXME" "Assets/Scripts/Utils.cs"
unity-mcp code search "void Update" "Assets/Scripts/Game.cs" --max-results 20

Shader Operations

# Create shader
unity-mcp shader create "MyShader" --path "Assets/Shaders"

# Read shader
unity-mcp shader read "Assets/Shaders/Custom.shader"

# Update from file
unity-mcp shader update "Assets/Shaders/Custom.shader" --file local.shader

# Delete shader
unity-mcp shader delete "Assets/Shaders/Old.shader" --force

Editor Controls

# Play mode
unity-mcp editor play
unity-mcp editor pause
unity-mcp editor stop

# Refresh assets
unity-mcp editor refresh
unity-mcp editor refresh --compile

# Console
unity-mcp editor console
unity-mcp editor console --clear

# Tags and layers
unity-mcp editor add-tag "Enemy"
unity-mcp editor add-layer "Projectiles"

# Menu items
unity-mcp editor menu "Edit/Project Settings..."

# Custom tools
unity-mcp editor custom-tool "MyBuildTool"
unity-mcp editor custom-tool "Deploy" --params '{"target": "Android"}'

# List custom tools for the active Unity project
unity-mcp tool list
unity-mcp custom_tool list

Screenshot Parameters

Option	Type	Description
--filename, -f	string	Output filename (default: timestamp-based)
--supersize, -s	int	Resolution multiplier 1–4 for file-saved screenshots
--camera-ref	string	Camera name/path/ID (default: Camera.main)
--include-image	flag	Return base64 PNG inline in the response
--max-resolution, -r	int	Max longest-edge pixels (default 640)
--batch, -b	string	surround (6 angles) or orbit (configurable grid)
--capture-source	string	game_view (default) or scene_view (editor viewport)
--view-target	string	Target to focus on: GO name/path/ID, or x,y,z. Aims camera (game_view) or frames viewport (scene_view)
--view-position	string	Camera position as x,y,z (positioned screenshot, game_view only)
--view-rotation	string	Camera euler rotation as x,y,z (positioned screenshot, game_view only)
--orbit-angles	int	Number of azimuth steps around target (default 8)
--orbit-elevations	string	Vertical angles as JSON array, e.g. [0,30,-15] (default [0, 30, -15])
--orbit-distance	float	Camera distance from target in world units (auto-fit if omitted)
--orbit-fov	float	Camera FOV in degrees (default 60)
--output-dir, -o	string	Save directory (default: Unity project's Assets/Screenshots/)

Testing

# Run tests synchronously
unity-mcp editor tests --mode EditMode

# Run tests asynchronously
unity-mcp editor tests --mode PlayMode --async

# Poll test job
unity-mcp editor poll-test <job_id>
unity-mcp editor poll-test <job_id> --wait 60 --details

Material Operations

# Create material
unity-mcp material create "Assets/Materials/Red.mat"

# Set color
unity-mcp material set-color "Assets/Materials/Red.mat" 1 0 0

# Assign to object
unity-mcp material assign "Assets/Materials/Red.mat" "Cube"

VFX Operations

Note: VFX Graph tooling is tested against com.unity.visualeffectgraph 12.1.13. Install VFX Graph and use URP/HDRP (set the Render Pipeline Asset) to avoid Unity warnings; other versions may be unsupported.

# Particle systems
unity-mcp vfx particle info "Fire"
unity-mcp vfx particle play "Fire" --with-children
unity-mcp vfx particle stop "Fire"

# Line renderers
unity-mcp vfx line info "LaserBeam"
unity-mcp vfx line create-line "Line" --start 0 0 0 --end 10 5 0
unity-mcp vfx line create-circle "Circle" --radius 5

# Trail renderers
unity-mcp vfx trail info "PlayerTrail"
unity-mcp vfx trail set-time "Trail" 2.0

# Raw VFX actions (access all 60+ actions)
unity-mcp vfx raw particle_set_main "Fire" --params '{"duration": 5}'

ProBuilder Operations

Note: Requires com.unity.probuilder package installed in your Unity project.

# Create shapes
unity-mcp probuilder create-shape Cube
unity-mcp probuilder create-shape Torus --name "MyTorus" --params '{"rows": 16, "columns": 16}'
unity-mcp probuilder create-shape Stair --position 0 0 5 --params '{"steps": 10}'

# Create from polygon footprint
unity-mcp probuilder create-poly --points "[[0,0,0],[5,0,0],[5,0,5],[0,0,5]]" --height 3

# Get mesh info
unity-mcp probuilder info "MyCube"

# Raw ProBuilder actions
unity-mcp probuilder raw extrude_faces "MyCube" --params '{"faceIndices": [0], "distance": 1.0}'
unity-mcp probuilder raw bevel_edges "MyCube" --params '{"edgeIndices": [0,1], "amount": 0.2}'
unity-mcp probuilder raw set_face_material "MyCube" --params '{"faceIndices": [0], "materialPath": "Assets/Materials/Red.mat"}'

Batch Operations

# Execute from JSON file
unity-mcp batch run commands.json
unity-mcp batch run commands.json --parallel --fail-fast

# Execute inline JSON
unity-mcp batch inline '[{"tool": "manage_scene", "params": {"action": "get_active"}}]'

# Generate template
unity-mcp batch template > my_commands.json

Prefab Operations

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

# Save and close
unity-mcp prefab save
unity-mcp prefab close

# Create from GameObject
unity-mcp prefab create "Player" --path "Assets/Prefabs"

# Modify prefab contents (headless, no UI)
unity-mcp prefab modify "Assets/Prefabs/Player.prefab" --target Weapon --position "0,1,2"
unity-mcp prefab modify "Assets/Prefabs/Player.prefab" --delete-child Child1 --delete-child "Turret/Barrel"
unity-mcp prefab modify "Assets/Prefabs/Player.prefab" --set-property "Rigidbody.mass=5"
unity-mcp prefab modify "Assets/Prefabs/Player.prefab" --add-component BoxCollider
unity-mcp prefab modify "Assets/Prefabs/Player.prefab" --create-child '{"name":"Spawn","primitive_type":"Sphere"}'

Asset Operations

# Search assets
unity-mcp asset search --pattern "*.mat" --path "Assets/Materials"

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

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

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

Animation Operations

# Play animation state
unity-mcp animation play "Player" "Run"

# Set animator parameter
unity-mcp animation set-parameter "Player" Speed 1.5
unity-mcp animation set-parameter "Player" IsRunning true

Audio Operations

# Play audio
unity-mcp audio play "AudioPlayer"

# Stop audio
unity-mcp audio stop "AudioPlayer"

# Set volume
unity-mcp audio volume "AudioPlayer" 0.5

Lighting Operations

# Create light
unity-mcp lighting create "NewLight" --type Point --position 0 5 0
unity-mcp lighting create "Spotlight" --type Spot --intensity 2

UI Operations

# Create canvas
unity-mcp ui create-canvas "MainCanvas"

# Create text
unity-mcp ui create-text "Title" --parent "MainCanvas" --text "Hello World"

# Create button
unity-mcp ui create-button "StartBtn" --parent "MainCanvas" --text "Start"

# Create image
unity-mcp ui create-image "Background" --parent "MainCanvas"

Camera Operations

unity-mcp camera ping                                       # Check Cinemachine availability
unity-mcp camera list                                       # List all cameras
unity-mcp camera create --name "Cam" --preset follow --follow "Player"
unity-mcp camera set-target "Cam" --follow "Player" --look-at "Enemy"
unity-mcp camera set-lens "Cam" --fov 60 --near 0.1 --far 1000
unity-mcp camera set-priority "Cam" --priority 15
unity-mcp camera set-body "Cam" --body-type "CinemachineFollow"
unity-mcp camera set-aim "Cam" --aim-type "CinemachineRotationComposer"
unity-mcp camera set-noise "Cam" --amplitude 1.5 --frequency 0.5
unity-mcp camera add-extension "Cam" CinemachineConfiner3D
unity-mcp camera ensure-brain --blend-style "EaseInOut" --blend-duration 1.5
unity-mcp camera brain-status
unity-mcp camera force "Cam"                                # Force Brain to use camera
unity-mcp camera release                                    # Release override
unity-mcp camera screenshot --file-name "capture" --super-size 2
unity-mcp camera screenshot --batch orbit --view-target "Player" --max-resolution 256
unity-mcp camera screenshot --capture-source scene_view --view-target "Canvas" --include-image
unity-mcp camera screenshot-multiview --view-target "Player" --max-resolution 480

Graphics Operations

# Volumes
unity-mcp graphics volume-create --name "PostFX" --global
unity-mcp graphics volume-add-effect --target "PostFX" --effect "Bloom"
unity-mcp graphics volume-set-effect --target "PostFX" --effect "Bloom" -p intensity 1.5
unity-mcp graphics volume-info --target "PostFX"
unity-mcp graphics volume-list-effects

# Render Pipeline
unity-mcp graphics pipeline-info
unity-mcp graphics pipeline-set-quality --level "High"
unity-mcp graphics pipeline-set-settings -s renderScale 1.5

# Light Baking
unity-mcp graphics bake-start [--sync]
unity-mcp graphics bake-status
unity-mcp graphics bake-cancel
unity-mcp graphics bake-settings
unity-mcp graphics bake-create-probes --spacing 5
unity-mcp graphics bake-create-reflection --resolution 512

# Stats & Debug
unity-mcp graphics stats
unity-mcp graphics stats-memory
unity-mcp graphics stats-debug-mode --mode "Wireframe"

# URP Renderer Features
unity-mcp graphics feature-list
unity-mcp graphics feature-add --type "ScreenSpaceAmbientOcclusion"
unity-mcp graphics feature-configure --name "SSAO" -p Intensity 1.5
unity-mcp graphics feature-toggle --name "SSAO" --active|--inactive

# Skybox & Environment
unity-mcp graphics skybox-info
unity-mcp graphics skybox-set-material --material "Assets/Materials/Sky.mat"
unity-mcp graphics skybox-set-ambient --mode Flat --color "0.2,0.2,0.3"
unity-mcp graphics skybox-set-fog --enable --mode ExponentialSquared --density 0.02
unity-mcp graphics skybox-set-reflection --intensity 1.0 --bounces 2
unity-mcp graphics skybox-set-sun --target "DirectionalLight"

Package Operations

unity-mcp packages ping                                     # Check package manager
unity-mcp packages list                                     # List installed packages
unity-mcp packages search "cinemachine"                     # Search registry
unity-mcp packages info "com.unity.cinemachine"             # Package details
unity-mcp packages add "com.unity.cinemachine"              # Install package
unity-mcp packages add "com.unity.cinemachine@4.1.1"        # Specific version
unity-mcp packages remove "com.unity.cinemachine" [--force]
unity-mcp packages embed "com.unity.cinemachine"            # Embed for local editing
unity-mcp packages resolve                                  # Force re-resolution
unity-mcp packages status <job_id>                          # Check async op
unity-mcp packages list-registries
unity-mcp packages add-registry "Name" --url URL -s "com.example"
unity-mcp packages remove-registry "Name"

Texture Operations

unity-mcp texture create "Assets/Textures/Red.png" --color "1,0,0,1"
unity-mcp texture create "Assets/Textures/Check.png" --pattern checkerboard --width 256 --height 256
unity-mcp texture create "Assets/Textures/Img.png" --image-path "/path/to/source.png"
unity-mcp texture sprite "Assets/Sprites/Player.png" --width 32 --height 32 --ppu 16
unity-mcp texture modify "Assets/Textures/Img.png" --set-pixels '{"x":0,"y":0,"width":16,"height":16,"color":[1,0,0,1]}'
unity-mcp texture delete "Assets/Textures/Old.png" [--force]
# Patterns: checkerboard, stripes, stripes_h, stripes_v, stripes_diag, dots, grid, brick

Raw Commands

For any MCP tool not covered by dedicated commands:

unity-mcp raw manage_scene '{"action": "get_hierarchy", "max_nodes": 100}'
unity-mcp raw read_console '{"count": 20}'
unity-mcp raw manage_camera '{"action": "screenshot", "include_image": true}'
unity-mcp raw manage_graphics '{"action": "volume_get_info", "target": "PostProcessing"}'
unity-mcp raw manage_packages '{"action": "list_packages"}'

---

Complete Command Reference

Group	Subcommands
instance	list, set, current
scene	hierarchy, active, load, save, create, build-settings
code	read, search
gameobject	find, create, modify, delete, duplicate, move
component	add, remove, set, modify
script	create, read, delete, edit, validate
shader	create, read, update, delete
editor	play, pause, stop, refresh, console, menu, tool, add-tag, remove-tag, add-layer, remove-layer, tests, poll-test, custom-tool
asset	search, info, create, delete, duplicate, move, rename, import, mkdir
prefab	open, close, save, create, modify
material	info, create, set-color, set-property, assign, set-renderer-color
camera	ping, list, create, set-target, set-lens, set-priority, set-body, set-aim, set-noise, add-extension, remove-extension, ensure-brain, brain-status, set-blend, force, release, screenshot, screenshot-multiview
graphics	ping, volume-create, volume-add-effect, volume-set-effect, volume-remove-effect, volume-info, volume-set-properties, volume-list-effects, volume-create-profile, pipeline-info, pipeline-settings, pipeline-set-quality, pipeline-set-settings, bake-start, bake-cancel, bake-status, bake-clear, bake-settings, bake-set-settings, bake-reflection-probe, bake-create-probes, bake-create-reflection, stats, stats-memory, stats-debug-mode, feature-list, feature-add, feature-remove, feature-configure, feature-reorder, feature-toggle, skybox-info, skybox-set-material, skybox-set-properties, skybox-set-ambient, skybox-set-fog, skybox-set-reflection, skybox-set-sun
packages	ping, list, search, info, add, remove, embed, resolve, status, list-registries, add-registry, remove-registry
texture	create, sprite, modify, delete
vfx particle	info, play, stop, pause, restart, clear
vfx line	info, set-positions, create-line, create-circle, clear
vfx trail	info, set-time, clear
vfx	raw (access all 60+ actions)
probuilder	create-shape, create-poly, info, raw (access all 35+ actions)
batch	run, inline, template
animation	play, set-parameter
audio	play, stop, volume
lighting	create
tool	list
custom_tool	list
ui	create-canvas, create-text, create-button, create-image

---

Output Formats

# Text (default) - human readable
unity-mcp scene hierarchy

# JSON - for scripting
unity-mcp --format json scene hierarchy

# Table - structured display
unity-mcp --format table instance list

Environment Variables

Set defaults via environment:

export UNITY_MCP_HOST=192.168.1.100
export UNITY_MCP_HTTP_PORT=8080
export UNITY_MCP_FORMAT=json
export UNITY_MCP_INSTANCE=MyProject@abc123

Troubleshooting

Connection Issues

# Check server status
unity-mcp status

# Verify Unity is running with MCP plugin
# Check Unity console for MCP connection messages

Common Errors

Error	Solution
Cannot connect to server	Ensure Unity MCP server is running
Unknown command type	Unity plugin may not support this tool
Timeout	Increase timeout with -t 60