unity-mcp-cli reference

unity-mcp-cli is the command-line tool for Unity MCP. It installs Unity and the plugin, signs you in to ai-game.dev, writes AI agent configs, opens and closes the Editor, and calls MCP tools or runs C# in the Editor from a terminal or a CI script. This page lists every command and flag in version 1.6.2.

Install#

npm install -g unity-mcp-cli

Or run any command without installing: npx unity-mcp-cli <command>. It needs Node.js ^20.19.0 or >=22.12.0 and works on Windows, macOS and Linux. Commands that manage editors use the Unity Hub CLI; if Unity Hub is missing, the CLI installs it.

Global options, available on every command:

In a non-interactive terminal (CI) the CLI disables spinners and colors automatically. Most commands that take a project path accept it as a positional argument or as --path, and default to the current folder.

A typical session#

unity-mcp-cli install-plugin ./MyGame
unity-mcp-cli login
unity-mcp-cli setup-mcp claude-code ./MyGame
unity-mcp-cli open ./MyGame
unity-mcp-cli wait-for-ready ./MyGame
unity-mcp-cli run-tool tests-run ./MyGame --input '{"testMode":"EditMode"}'
unity-mcp-cli close ./MyGame

Project setup commands#

install-unity#

Installs a Unity Editor through Unity Hub. With no argument it installs the latest stable release.

create-project#

Creates a new Unity project with the Editor: unity-mcp-cli create-project ./MyGame --unity 6000.3.1f1.

install-plugin#

Adds the OpenUPM scoped registry and com.ivanmurzak.unity.mcp to Packages/manifest.json. Never downgrades a higher installed version. The folder must be a Unity project.

install-extension#

Installs an official extension into Packages/manifest.json. See Extensions.

remove-plugin#

Removes com.ivanmurzak.unity.mcp from Packages/manifest.json and keeps the scoped registries. Takes [path] (required, or --path).

configure#

Shows or hides tools, prompts and resources in UserSettings/AI-Game-Developer-Config.json. A hidden item still runs when called by name.

bootstrap-local#

Pins a project's config to Custom (local) mode with a given server URL and token. Idempotent.

Sign-in and AI agent commands#

login#

Signs in to ai-game.dev with the browser OAuth device flow and stores the credential in ~/.ai-game-dev/credentials.json. The Editor plugin and the desktop app use the same credential. If you are already signed in it exits early.

setup-mcp#

Writes an AI agent's MCP config, the same output as Configure in the Editor window. By default the URL is pinned to this project (https://ai-game.dev/mcp/p/<pin>), and for Cloud HTTP configs it carries this project's key when you are signed in. See Connecting AI clients.

setup-skills#

Generates the agent's skill files through the running Editor. Unity must be open with the plugin connected.

Editor commands#

open#

Opens the project in the Unity Editor and sets the plugin's connection environment variables from the options given. The editor starts detached.

Dismissing the launch-errors dialog needs Accessibility permission for the terminal on macOS and xdotool on Linux X11 (Wayland is not supported).

close#

Closes the project's Editor gracefully: unity-mcp-cli close ./MyGame --timeout 60 --force. Closing an Editor that is not running succeeds.

wait-for-ready#

Polls until the Editor and MCP server accept tool calls. Options: [path], --url, --token, --timeout <ms> (default 120000) and --interval <ms> (default 3000).

status#

Shows whether Unity is running, whether the local MCP server answers and whether the configured server (for example the cloud) is reachable. Options: [path], --url, --token, --timeout <ms> (default 5000).

Tool commands#

run-tool#

Calls an MCP tool over the server's HTTP API. The URL and token come from the project config (Custom or Cloud mode) unless you override them.

unity-mcp-cli run-tool rql-query ./MyGame --input '{"query":"objects | where name == \"Player\" | select path name active"}'
unity-mcp-cli run-tool unity-tool-list ./MyGame --raw

run-system-tool#

Same options as run-tool, for system tools that are not exposed to MCP clients (for example skill generation and session control).

exec#

Runs C# in the Editor through script-execute and prints the result. It uses an open Editor if there is one; otherwise it starts a headless Editor that stays warm for later calls and quits after --idle seconds.

unity-mcp-cli exec 'GameObject.FindObjectsOfType<Camera>().Length'
echo 'Application.unityVersion' | unity-mcp-cli exec

A compile error exits with code 1 and points at your lines.

Maintenance#

update#

Updates the CLI to the latest npm version. --check only checks and exits with code 2 when an update is available. Under npx there is nothing to update.

Library use#

The package also exports a typed Node.js API (installPlugin, removePlugin, configure, setupMcp, installExtension and more) that returns result objects instead of printing. See the package README on npm.

Related pages#

• Installation and Getting started.
• Configuration for the environment variables open sets.
• The desktop app's own CLI, gamedev: app CLI.