CLI Reference

The unity-mcp CLI is a developer-facing terminal for the same Unity automations the MCP tools expose. Both invoke the same C# HandleCommand methods on the Unity side — see Three-Layer Python Design for why both layers exist.

Invocation

# Run via uvx (no install)
uvx --from mcpforunityserver unity-mcp <command> [args]

# Run from a Server checkout
cd Server && uv run unity-mcp <command> [args]

The same package also installs mcp-for-unity, which starts the MCP server, not the CLI.

How it talks to Unity

The CLI uses HTTP to the Python server (default http://127.0.0.1:8080), regardless of how your MCP clients are configured. The Python server in turn talks to the connected Unity Editor via WebSocket. MCP tools take a similar path via WebSocket directly; CLI commands take HTTP.

Global flags

Global flags go before the command group: unity-mcp --format json scene active.

Flag	Env variable	Default	Meaning
--host, -h	UNITY_MCP_HOST	127.0.0.1	Python server host to connect to
--port, -p	UNITY_MCP_HTTP_PORT	8080	Python server port
--timeout, -t	UNITY_MCP_TIMEOUT	30	Command timeout in seconds
--format, -f	UNITY_MCP_FORMAT	text	Output format: text, json or table
--instance, -i	UNITY_MCP_INSTANCE	(auto)	Target Unity instance (hash or Name@hash)
--verbose, -v	—	off	Print each command sent to Unity and its raw response to stderr
--version	—	—	Print CLI version and exit
--help	—	—	Show command help (-h is --host, not help)

For multi-instance setups, see Multi-Instance Routing.

Command groups

The CLI mirrors the MCP tool catalog. Each command sends one or more MCP tool calls to Unity; the last column names them. Commands marked — only talk to the Python server.

Command	What it does	MCP tool(s) it calls
unity-mcp status	Check the server connection and list Unity instances	— (server /health, /api/instances)
unity-mcp instances	List connected Unity instances	— (server /api/instances)
unity-mcp raw	Send any tool by name with JSON params	The named tool
unity-mcp instance	List instances, show the one this shell targets (--instance / UNITY_MCP_INSTANCE)	— (server /api/instances)
unity-mcp scene	Load/save/query/edit scenes	manage_scene
unity-mcp gameobject	Find/create/modify/move/duplicate/delete GameObjects	manage_gameobject, find_gameobjects (find), manage_components (create --components)
unity-mcp component	Add/remove/configure components	manage_components
unity-mcp script	Create/read/edit/validate/delete C# scripts	manage_script
unity-mcp asset	Asset import/create/modify/search	manage_asset
unity-mcp asset-gen	Generate images, 3D models and audio; import models	generate_image, generate_model, generate_audio, import_model, import_model_file
unity-mcp blender	Talk to a running Blender through the Blender Bridge	blender_bridge
unity-mcp material	Material CRUD + shader props	manage_material
unity-mcp prefab	Prefab create/open/save/close, inspect, headless modify	manage_prefabs
unity-mcp texture	Procedural or image textures, sprites, pixel edits	manage_texture
unity-mcp shader	Shader CRUD	manage_shader
unity-mcp vfx	Particle systems, line and trail renderers; raw for any manage_vfx action	manage_vfx
unity-mcp camera	Camera + Cinemachine presets, screenshots	manage_camera
unity-mcp graphics	Volumes, render pipeline, light baking, URP features, skybox	manage_graphics
unity-mcp lighting	Create a light GameObject	manage_gameobject + manage_components
unity-mcp physics	3D + 2D physics, joints, queries	manage_physics
unity-mcp audio	Play, stop or set the volume of an AudioSource	manage_components
unity-mcp animation	Animator, AnimationClip and AnimatorController	manage_animation
unity-mcp sprite	Sprite sheet slicing → clips → Animator controller	manage_sprite
unity-mcp ui	Create uGUI Canvas, text, button and image GameObjects	manage_gameobject + manage_components
unity-mcp build	Player builds across platforms	manage_build
unity-mcp editor	Play mode, tags/layers, undo/redo, console, refresh, menu items, tests, custom tools	manage_editor, read_console (console), refresh_unity (refresh), execute_menu_item (menu), run_tests (tests), get_test_job (poll-test), execute_custom_tool (custom-tool)
unity-mcp packages	UPM install/remove/embed	manage_packages
unity-mcp probuilder	ProBuilder meshes	manage_probuilder
unity-mcp profiler	Profiler session + counters + snapshots	manage_profiler
unity-mcp code	Execute C# in the Editor; read and search script files	execute_code, manage_script (read, search)
unity-mcp batch	Run many commands in one request	batch_execute
unity-mcp tool	List the custom tools registered for the active Unity project	— (server /api/custom-tools)
unity-mcp custom_tool	Same as tool	— (server /api/custom-tools)
unity-mcp reflect	Inspect Unity APIs via reflection	unity_reflect
unity-mcp docs	Fetch a Unity ScriptReference page	unity_docs (runs in the CLI process)

Discovering subcommands and flags

Every group supports --help:

unity-mcp scene --help
unity-mcp scene load --help

The help text is the authoritative per-command reference — flags, choices, and defaults all live there because the CLI is built on Click and self-describes.

Examples

See CLI Examples for end-to-end walkthroughs and the CLI Usage Guide for narrative context (when to use the CLI vs an MCP client).

Source

CLI command definitions: Server/src/cli/commands/. Entry point: Server/src/cli/main.py.