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

id, slug, title, sidebar_label, description

id	slug	title	sidebar_label	description
cli	/reference/cli	CLI Reference	CLI	The mcp-for-unity command-line interface — invocation, global flags, command groups, and how each maps to the equivalent MCP tool.

CLI Reference

The mcp-for-unity 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 mcp-for-unity <command> [args]

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

# Run via the dedicated CLI entry point (alias)
uvx --from mcpforunityserver unity-mcp <command> [args]

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

Flag	Default	Meaning
--host	127.0.0.1	Python server host to connect to
--port	8080	Python server port
--instance	(auto)	Target Unity instance (Name@hash, hash prefix, or port number)
--format	text	Output format: text or json
--verbose / -v	off	Print full request/response payloads
--version	—	Print CLI version and exit
--help	—	Show command help

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

Command groups

The CLI mirrors the MCP tool catalog. Each command group wraps one or more manage_* tools.

Group	What it does	Equivalent MCP tool
mcp-for-unity instance	List instances, check connection, set active	set_active_instance
mcp-for-unity scene	Load/save/query/edit scenes	manage_scene
mcp-for-unity gameobject	Create/transform/delete GameObjects	manage_gameobject
mcp-for-unity component	Add/remove/configure components	manage_components
mcp-for-unity script	Create/read/modify C# scripts	manage_script
mcp-for-unity asset	Asset import/create/modify/search	manage_asset
mcp-for-unity material	Material CRUD + shader props	manage_material
mcp-for-unity prefab	Prefab create/instantiate/unpack	manage_prefabs
mcp-for-unity texture	Texture create + patterns/gradients	manage_texture
mcp-for-unity shader	Shader CRUD	manage_shader
mcp-for-unity vfx	VFX, particle systems, trails	manage_vfx
mcp-for-unity camera	Camera + Cinemachine presets	manage_camera
mcp-for-unity graphics	Volumes, post-processing, light bake	manage_graphics
mcp-for-unity lighting	Lighting-specific operations	(subset of graphics)
mcp-for-unity physics	3D + 2D physics, joints, queries	manage_physics
mcp-for-unity audio	Audio operations	(subset of asset)
mcp-for-unity animation	Animator + AnimationClip	manage_animation
mcp-for-unity ui	UI Toolkit — UXML/USS/UIDocument	manage_ui
mcp-for-unity build	Player builds across platforms	manage_build
mcp-for-unity editor	Editor state, play mode, undo/redo	manage_editor
mcp-for-unity packages	UPM install/remove/embed	manage_packages
mcp-for-unity probuilder	ProBuilder meshes	manage_probuilder
mcp-for-unity profiler	Profiler session + counters + snapshots	manage_profiler
mcp-for-unity code	Execute arbitrary C# in the Editor	execute_code
mcp-for-unity batch	Run multiple operations atomically	batch_execute
mcp-for-unity tool	Activate/deactivate tool groups	manage_tools
mcp-for-unity reflect	Inspect Unity APIs via reflection	unity_reflect
mcp-for-unity docs	Fetch Unity docs (ScriptReference, Manual)	unity_docs

Discovering subcommands and flags

Every group supports --help:

mcp-for-unity scene --help
mcp-for-unity 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.