Unity MCP (CLI Mode)
We use Unity MCP via CLI commands instead of MCP server connection. This avoids the reconnection issues that occur when Unity restarts.
Why CLI Instead of MCP Connection?
- MCP connection breaks when Unity restarts
/mcp reconnectrequires human intervention- CLI works directly via HTTP to the MCP server - no persistent connection needed
- Claude can call CLI commands autonomously without reconnection issues
Installation
cd Server # In unity-mcp repo
pip install -e .
# Or with uv:
uv pip install -e .
Global Options
| Option | Description | Default | Env Variable |
|---|---|---|---|
-h, --host | Server host | 127.0.0.1 | UNITY_MCP_HOST |
-p, --port | Server port | 8080 | UNITY_MCP_HTTP_PORT |
-t, --timeout | Timeout seconds | 30 | UNITY_MCP_TIMEOUT |
-f, --format | Output: text, json, table | text | UNITY_MCP_FORMAT |
-i, --instance | Target Unity instance | - | UNITY_MCP_INSTANCE |
-v, --verbose | Print each command sent to Unity and its raw response to stderr | off | - |
Core CLI Commands
Status & Connection
unity-mcp status # Check server + Unity connection
Instance Management
unity-mcp instance list # List connected Unity instances
unity-mcp --instance "ProjectName@abc" editor play # Target one instance for one call
unity-mcp instance current # Show current instance
Editor Control
unity-mcp editor play|pause|stop # Control play mode
unity-mcp editor console [--clear] # Get/clear console logs
unity-mcp editor refresh [--compile] # Refresh assets
unity-mcp editor menu "Edit/Project Settings..." # Execute menu item
unity-mcp editor add-tag "TagName" # Add tag
unity-mcp editor add-layer "LayerName" # Add layer
unity-mcp editor tests --mode PlayMode [--async]
unity-mcp editor poll-test <job_id> [--wait 60] [--details]
unity-mcp --instance "MyProject@abc123" editor play # Target a specific instance
Custom Tools
unity-mcp tool list
unity-mcp custom_tool list
unity-mcp editor custom-tool "bake_lightmaps"
unity-mcp editor custom-tool "capture_screenshot" --params '{"filename":"shot_01","width":1920,"height":1080}'
Scene Operations
unity-mcp scene hierarchy [--limit 20] [--max-depth 3]
unity-mcp scene active
unity-mcp scene load "Assets/Scenes/Main.unity"
unity-mcp scene save
unity-mcp --format json scene hierarchy
Screenshots (via camera command):
unity-mcp camera screenshot --file-name "capture"
unity-mcp camera screenshot --camera-ref "MainCam" --include-image --max-resolution 512
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
unity-mcp gameobject find "Name" [--method by_tag|by_name|by_layer|by_component]
unity-mcp gameobject create "Name" [--primitive Cube] [--position X Y Z]
unity-mcp gameobject modify "Name" [--position X Y Z] [--rotation X Y Z]
unity-mcp gameobject delete "Name" [--force]
unity-mcp gameobject duplicate "Name"
Component Operations
unity-mcp component add "GameObject" ComponentType
unity-mcp component remove "GameObject" ComponentType
unity-mcp component set "GameObject" Component property value
Script Operations
unity-mcp script create "ScriptName" --path "Assets/Scripts"
unity-mcp script read "Assets/Scripts/File.cs"
unity-mcp script delete "Assets/Scripts/File.cs" [--force]
unity-mcp code search "pattern" "path/to/file.cs" [--max-results 20]
Asset Operations
unity-mcp asset search "*.mat" --path "Assets/Materials"
unity-mcp asset info "Assets/Materials/File.mat"
unity-mcp asset mkdir "Assets/NewFolder"
unity-mcp asset move "Old/Path" "New/Path"
Prefab Operations
unity-mcp prefab open "Assets/Prefabs/File.prefab"
unity-mcp prefab save
unity-mcp prefab close
unity-mcp prefab create "GameObject" "Assets/Prefabs/File.prefab"
unity-mcp prefab modify "Assets/Prefabs/File.prefab" --delete-child Child1
unity-mcp prefab modify "Assets/Prefabs/File.prefab" --target Weapon --position "0,1,2"
unity-mcp prefab modify "Assets/Prefabs/File.prefab" --set-property "Rigidbody.mass=5"
Material Operations
unity-mcp material create "Assets/Materials/File.mat"
unity-mcp material set-color "File.mat" R G B
unity-mcp material assign "File.mat" "GameObject"
Shader Operations
unity-mcp shader create "Name" --path "Assets/Shaders"
unity-mcp shader read "Assets/Shaders/Custom.shader"
unity-mcp shader update "Assets/Shaders/Custom.shader" --file local.shader
unity-mcp shader delete "Assets/Shaders/File.shader" [--force]
VFX Operations
unity-mcp vfx particle info|play|stop|pause|restart|clear "Name"
unity-mcp vfx line info "Name"
unity-mcp vfx line create-line "Name" --start X Y Z --end X Y Z
unity-mcp vfx line create-circle "Name" --radius N
unity-mcp vfx trail info|set-time|clear "Name" [time]
Camera Operations
unity-mcp camera ping # Check Cinemachine
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
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 ensure-brain --blend-style "EaseInOut" --blend-duration 1.5
unity-mcp camera force "Cam" # Force Brain to use camera
unity-mcp camera release # Release override
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"
# Pipeline
unity-mcp graphics pipeline-info
unity-mcp graphics pipeline-set-quality --level "High"
# Baking
unity-mcp graphics bake-start [--sync]
unity-mcp graphics bake-status
unity-mcp graphics bake-create-probes --spacing 5
# Stats
unity-mcp graphics stats
unity-mcp graphics stats-memory
# URP Features
unity-mcp graphics feature-list
unity-mcp graphics feature-add --type "ScreenSpaceAmbientOcclusion"
# Skybox
unity-mcp graphics skybox-info
unity-mcp graphics skybox-set-fog --enable --mode ExponentialSquared --density 0.02
unity-mcp graphics skybox-set-sun --target "DirectionalLight"
Package Operations
unity-mcp packages list # List installed
unity-mcp packages search "cinemachine" # Search registry
unity-mcp packages info "com.unity.cinemachine" # Details
unity-mcp packages add "com.unity.cinemachine" # Install
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" # Local editing
unity-mcp packages resolve # Re-resolve
unity-mcp packages list-registries
unity-mcp packages add-registry "Name" --url URL -s "com.example"
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 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]
Sprite Animation
unity-mcp sprite info "Assets/Sprites/Hero.png" # Size, import settings, slices
unity-mcp sprite slice "Assets/Sprites/Hero.png" --cols 6 --rows 4 # Or --frame-width/--frame-height
unity-mcp sprite full-setup "Assets/Sprites/Coin.png" --cols 8 --clips '[{"name":"spin","start_frame":0,"end_frame":7,"loop":true}]'
unity-mcp sprite full-setup "Assets/Sprites/Hero.png" --cols 6 --rows 4 --clips '[{"name":"idle","start_frame":0,"end_frame":5},{"name":"walk","start_frame":6,"end_frame":11}]' --controller-path "Assets/Animators/Hero.controller"
Lighting & UI
unity-mcp lighting create "Name" --type Point|Spot [--intensity N] [--position X Y Z]
unity-mcp ui create-canvas "Name"
unity-mcp ui create-text "Name" --parent "Canvas" --text "Content"
unity-mcp ui create-button "Name" --parent "Canvas" --text "Label"
Batch Operations
unity-mcp batch run commands.json [--parallel] [--fail-fast]
unity-mcp batch inline '[{"tool": "manage_scene", "params": {...}}]'
unity-mcp batch template > commands.json
Animation
unity-mcp animation animator play "Player" "Run"
unity-mcp animation animator set-parameter "Player" "Speed" 1.5
unity-mcp animation clip create "Assets/Animations/Bounce.anim" --length 2.0 --loop
unity-mcp animation controller info "Assets/Animations/Player.controller"
Build
unity-mcp build platform [android] # Read or switch platform
unity-mcp build run --target windows64 --development
unity-mcp build status
Physics
unity-mcp physics raycast --origin "0,5,0" --direction "0,-1,0"
unity-mcp physics simulate --steps 10
unity-mcp physics validate
Profiler
unity-mcp profiler start
unity-mcp profiler get-counters --category Render
unity-mcp profiler stop
Reflection & Docs
unity-mcp reflect type NavMeshAgent
unity-mcp docs get Physics Raycast
Asset Generation & Blender
unity-mcp asset-gen generate-image --provider fal --prompt "a stone texture"
unity-mcp asset-gen status --job-id abc123
unity-mcp blender import-model --selection-only --target-size 2
Raw Access (Any Tool)
unity-mcp raw tool_name 'JSON_params'
unity-mcp raw manage_scene '{"action":"get_active"}'
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"}'
Note on MCP Server
The MCP HTTP server still needs to be running for CLI to work. Here is an example to run the server manually on Mac:
/opt/homebrew/bin/uvx --no-cache --refresh --from /XXX/unity-mcp/Server mcp-for-unity --transport http --http-url http://localhost:8080