# unity-mcp-cli reference

Command reference for unity-mcp-cli - install Unity MCP, sign in, write AI agent configs, open Unity headless, run tools and C# from the terminal.

_Last updated: 2026-11-04_

`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

```bash
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:

| Option | Description |
| --- | --- |
| `-v, --verbose` | Detailed diagnostic output |
| `-V, --version` | Print the CLI version |
| `--help` | Help for the 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

```bash
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.

| Argument / option | Description |
| --- | --- |
| `[version]` | Editor version, for example `6000.3.1f1` |
| `--path <path>` | Read the required version from an existing project |

### create-project

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

| Argument / option | Description |
| --- | --- |
| `[path]` | Where to create the project (required, or `--path`) |
| `--unity <version>` | Editor version (default: highest installed) |

### 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.

| Option | Description |
| --- | --- |
| `[path]` | Unity project (default: current folder) |
| `--plugin-version <version>` | Version to install (default: latest on OpenUPM) |
| `--with-server` | Also download the `gamedev-mcp-server` binary for this machine into the CLI's own folder |
| `--server-version <version>` | Server version for `--with-server` |
| `--server-source <path-or-url>` | Install the server from a local zip or URL (offline or CI; skips checksum verification) |
| `--enroll <code>` | Redeem a team enrollment code for a plugin credential pinned to this project |
| `--enroll-stdin` | Read the enrollment code from stdin, keeping it out of shell history |
| `--yes` | Confirm prompts, such as an account switch during `--enroll` |

### install-extension

Installs an official extension into `Packages/manifest.json`. See [Extensions](https://ai-game.dev/docs/wiki/unity/extensions).

| Argument / option | Description |
| --- | --- |
| `[id]` | Catalogue name (`Tilemap`) or package id (`com.ivanmurzak.unity.mcp.tilemap`) |
| `[path]` | Unity project (default: current folder) |
| `--extension-version <version>` | Version to install (default: latest on OpenUPM) |
| `--list` | List installable extensions and exit (no project or network needed) |

### 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.

| Option | Description |
| --- | --- |
| `[path]` | Unity project (required, or `--path`) |
| `--list` | Print the current configuration and exit |
| `--enable-tools <names>`, `--disable-tools <names>` | Show or hide specific tools (comma-separated) |
| `--enable-all-tools`, `--disable-all-tools` | Show or hide all tools |
| `--enable-prompts <names>`, `--disable-prompts <names>` | Same for prompts |
| `--enable-all-prompts`, `--disable-all-prompts` | All prompts |
| `--enable-resources <names>`, `--disable-resources <names>` | Same for resources |
| `--enable-all-resources`, `--disable-all-resources` | All resources |
| `--agent <id>` | Write an AI agent config through the managed server's configurator instead |
| `--url <url>` | Server URL passed along with `--agent` |

### bootstrap-local

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

| Option | Description |
| --- | --- |
| `[path]` | Unity project (default: current folder) |
| `--url <url>` | Local MCP server URL (required) |
| `--token <token>` | Local bearer token (required) |
| `--dry-run` | Report what would change without writing |

## 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.

| Option | Description |
| --- | --- |
| `--project <path>` | Store the credential in `<path>/.ai-game-dev/` instead of the machine store |
| `--force` | Sign in again even if a credential exists |
| `--tools-only` | Authorize engine tools only, for CI runners; no agent credential is stored |
| `--yes` | Confirm an account switch without a prompt |

### 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](https://ai-game.dev/docs/wiki/unity/connecting-ai-clients).

| Option | Description |
| --- | --- |
| `[agent-id]` | Agent to configure, for example `claude-code`, `cursor`, `codex` |
| `[path]` | Unity project (default: current folder) |
| `--transport <transport>` | `http` (default) or `stdio` |
| `--url <url>` | Server URL override for `http` |
| `--token <token>` | Write this Personal Access Token instead of the project key |
| `--oauth` | Write a URL-only config; the agent signs in with its own OAuth |
| `--regenerate-key` | Mint a new project key, rewrite configs and revoke the old key |
| `--no-pin` | Use the unpinned `https://ai-game.dev/mcp` endpoint |
| `--list` | List agent ids and their config paths |

### setup-skills

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

| Option | Description |
| --- | --- |
| `[agent-id]` | Agent to generate skills for |
| `[path]` | Unity project (default: current folder) |
| `--url <url>`, `--token <token>` | Server URL and token overrides |
| `--timeout <ms>` | Request timeout (default 60000) |
| `--list` | List agents and whether they support skills |

## 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.

| Option | Description |
| --- | --- |
| `[path]` | Unity project (default: current folder) |
| `--unity <version>` | Editor version (default: the project's version, then the highest installed) |
| `--editor-path <path>` | Explicit Editor executable; skips Unity Hub discovery |
| `--no-connect` | Open without MCP connection variables |
| `--url <url>` | Server URL (sets `UNITY_MCP_HOST`, the alias of `UNITY_MCP_CLOUD_URL`) |
| `--keep-connected` | Force the connection on |
| `--token <token>` | Local server token (sets `UNITY_MCP_TOKEN`) |
| `--auth <option>` | Authorization mode (sets `UNITY_MCP_AUTH_OPTION`); this version accepts `none` or `required` |
| `--tools <names>` | Comma-separated tools to show (sets `UNITY_MCP_TOOLS`) |
| `--transport <method>` | `streamableHttp` or `stdio` |
| `--start-server <value>` | `true` or `false` for local server auto-start |
| `--headless` | Start without a window (`-batchmode`, graphics kept) and wait until the MCP server answers |
| `--idle-timeout <seconds>` | Quit after this many seconds without a tool call, saving changed scenes and assets first |
| `--ready-timeout <ms>` | With `--headless`, how long to wait (default 300000) |
| `--no-auto-dismiss-launch-errors` | Do not click **Ignore** on Unity's "compile errors at launch" dialog |
| `--launch-dismiss-timeout-ms <ms>` | Total time to watch for that dialog (default 30000) |
| `--launch-dismiss-poll-interval-ms <ms>` | Polling interval for the dialog (default 1500) |

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.

| Option | Description |
| --- | --- |
| `[path]` | Unity project (default: current folder) |
| `--timeout <seconds>` | Wait for a polite quit (default 30) |
| `--force` | Kill the Editor if it has not quit by then |
| `--owned-only` | Close only an Editor the CLI started (`exec`, `open --headless`) |

### 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.

```bash
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
```

| Option | Description |
| --- | --- |
| `<tool-name>` | Tool to call |
| `[path]` | Unity project, used for config and port detection |
| `--url <url>`, `--token <token>` | Overrides that bypass the config |
| `--input <json>`, `--input-file <file>` | Tool arguments (default `{}`) |
| `--raw` | Raw JSON output |
| `--timeout <ms>` | Request timeout (default 60000) |

### 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.

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

| Option | Description |
| --- | --- |
| `[code]` | C# statements; the last expression is the result (or use `-f` or stdin) |
| `--path <path>` | Unity project (default: current folder) |
| `-f, --file <file>` | Read code from a file (`-` for stdin) |
| `--using <namespace>` | Extra namespace, repeatable |
| `--include <path>` | Helper `.cs` file or folder under `.ai-game-dev/snippets`, repeatable |
| `--window` | Start the Editor with a window instead of headless |
| `--idle <seconds>` | Idle time before an Editor started by `exec` quits (default 300, 0 for never) |
| `--ready-timeout <ms>` | Wait for the Editor (default 300000) |
| `--timeout <ms>` | Tool call timeout |
| `--raw` | Raw tool response JSON |
| `--url <url>`, `--token <token>` | Overrides |

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](https://www.npmjs.com/package/unity-mcp-cli).

## Related pages

- [Installation](https://ai-game.dev/docs/wiki/unity/installation) and [Getting started](https://ai-game.dev/docs/wiki/unity/getting-started).
- [Configuration](https://ai-game.dev/docs/wiki/unity/configuration#overrides) for the environment variables `open` sets.
- The desktop app's own CLI, `gamedev`: [app CLI](https://ai-game.dev/docs/wiki/app/cli).

---

Source (HTML): https://ai-game.dev/docs/wiki/unity/cli