Unity MCP — CLI

[![npm](https://img.shields.io/npm/v/unity-mcp-cli?label=npm&labelColor=333A41 'npm package')](https://www.npmjs.com/package/unity-mcp-cli) [![Node.js](https://img.shields.io/badge/Node.js-%5E20.19.0%20%7C%7C%20%3E%3D22.12.0-5FA04E?logo=nodedotjs&labelColor=333A41 'Node.js')](https://nodejs.org/) [![License](https://img.shields.io/github/license/IvanMurzak/Unity-MCP?label=License&labelColor=333A41)](https://github.com/IvanMurzak/Unity-MCP/blob/main/LICENSE) [![Stand With Ukraine](https://raw.githubusercontent.com/vshymanskyy/StandWithUkraine/main/badges/StandWithUkraine.svg)](https://stand-with-ukraine.pp.ua)

[中文](https://github.com/IvanMurzak/Unity-MCP/blob/main/cli/docs/README.zh-CN.md) | [日本語](https://github.com/IvanMurzak/Unity-MCP/blob/main/cli/docs/README.ja.md) | [Español](https://github.com/IvanMurzak/Unity-MCP/blob/main/cli/docs/README.es.md) Cross-platform CLI tool for **[Unity MCP](https://github.com/IvanMurzak/Unity-MCP)** — create projects, install plugins, configure MCP tools, and launch Unity with active MCP connections. All from a single command line. ## ![AI Game Developer — Unity SKILLS and MCP](https://github.com/IvanMurzak/Unity-MCP/blob/main/docs/img/promo/hazzard-features.svg?raw=true) - :white_check_mark: **Create projects** — scaffold new Unity projects via Unity Editor - :white_check_mark: **Install editors** — install any Unity Editor version from the command line - :white_check_mark: **Install plugin** — add Unity-MCP plugin to `manifest.json` with all required scoped registries - :white_check_mark: **Remove plugin** — remove Unity-MCP plugin from `manifest.json` - :white_check_mark: **Configure** — enable/disable MCP tools, prompts, and resources - :white_check_mark: **Status check** — see Unity process, local server, and cloud server connection status at a glance - :white_check_mark: **Run tools** — execute MCP tools directly from the command line - :white_check_mark: **Setup MCP** — write AI agent MCP config files for any of 14 supported agents - :white_check_mark: **Setup skills** — generate skill files for AI agents via the MCP server - :white_check_mark: **Wait for ready** — poll until Unity Editor and MCP server are connected and accepting tool calls - :white_check_mark: **Open & Connect** — launch Unity with optional MCP environment variables for automated server connection - :white_check_mark: **Cross-platform** — Windows, macOS, and Linux - :white_check_mark: **CI-friendly** — auto-detects non-interactive terminals and disables spinners/colors - :white_check_mark: **Verbose mode** — use `--verbose` on any command for detailed diagnostic output - :white_check_mark: **Version-aware** — never downgrades plugin versions, resolves latest from OpenUPM ![AI Game Developer — Unity SKILLS and MCP](https://github.com/IvanMurzak/Unity-MCP/blob/main/docs/img/promo/hazzard-divider.svg?raw=true) # Quick Start Install globally and run: ```bash # 1.1 Install unity-mcp-cli # ┌────────────────────┐ npm install -g unity-mcp-cli # │ Available AI agent │ # ├────────────────────┤ # 1.2 (Optional) Install Unity # │ antigravity │ unity-mcp-cli install-unity # │ claude-code │ # │ claude-desktop │ # 1.3 (Optional) Create Unity project # │ cline │ unity-mcp-cli create-project ./MyUnityProject # │ codex │ # │ cursor │ # 2. Install "AI Game Developer" in Unity project # │ gemini │ unity-mcp-cli install-plugin ./MyUnityProject # │ github-copilot-cli │ # │ kilo-code │ # 3. Login to cloud server # │ open-code │ unity-mcp-cli login ./MyUnityProject # │ rider-junie │ # │ unity-ai │ # 4. Open Unity project (auto-connects and generates skills) │ vs-copilot │ unity-mcp-cli open ./MyUnityProject # │ vscode-copilot │ # └────────────────────┘ # 5. Wait for Unity Editor to be ready unity-mcp-cli wait-for-ready ./MyUnityProject ``` Or run any command instantly with `npx` — no global installation required: ```bash npx unity-mcp-cli install-plugin /path/to/unity/project ``` > **Requirements:** [Node.js](https://nodejs.org/) ^20.19.0 || >=22.12.0. [Unity Hub](https://unity.com/download) is installed automatically if not found. ![AI Game Developer — Unity SKILLS and MCP](https://github.com/IvanMurzak/Unity-MCP/blob/main/docs/img/promo/hazzard-divider.svg?raw=true) # Contents - [Quick Start](#quick-start) - [Contents](#contents) - [Commands](#commands) - [`configure`](#configure) - [`create-project`](#create-project) - [`install-plugin`](#install-plugin) - [`install-unity`](#install-unity) - [`open`](#open) - [`close`](#close) - [`run-tool`](#run-tool) - [`wait-for-ready`](#wait-for-ready) - [`setup-mcp`](#setup-mcp) - [`setup-skills`](#setup-skills) - [`remove-plugin`](#remove-plugin) - [`status`](#status) - [Global Options](#global-options) - [Full Automation Example](#full-automation-example) - [How It Works](#how-it-works) - [Deterministic Port](#deterministic-port) - [Plugin Installation](#plugin-installation) - [Configuration File](#configuration-file) - [Unity Hub Integration](#unity-hub-integration) ![AI Game Developer — Unity SKILLS and MCP](https://github.com/IvanMurzak/Unity-MCP/blob/main/docs/img/promo/hazzard-divider.svg?raw=true) # Commands ## `configure` Configure MCP tools, prompts, and resources in `UserSettings/AI-Game-Developer-Config.json`. ```bash unity-mcp-cli configure ./MyGame --list ``` | Option | Required | Description | |---|---|---| | `[path]` | Yes | Path to the Unity project (positional or `--path`) | | `--list` | No | List current configuration and exit | | `--enable-tools ` | No | Enable specific tools (comma-separated) | | `--disable-tools ` | No | Disable specific tools (comma-separated) | | `--enable-all-tools` | No | Enable all tools | | `--disable-all-tools` | No | Disable all tools | | `--enable-prompts ` | No | Enable specific prompts (comma-separated) | | `--disable-prompts ` | No | Disable specific prompts (comma-separated) | | `--enable-all-prompts` | No | Enable all prompts | | `--disable-all-prompts` | No | Disable all prompts | | `--enable-resources ` | No | Enable specific resources (comma-separated) | | `--disable-resources ` | No | Disable specific resources (comma-separated) | | `--enable-all-resources` | No | Enable all resources | | `--disable-all-resources` | No | Disable all resources | **Example — enable specific tools and disable all prompts:** ```bash unity-mcp-cli configure ./MyGame \ --enable-tools gameobject-create,gameobject-find \ --disable-all-prompts ``` **Example — enable everything:** ```bash unity-mcp-cli configure ./MyGame \ --enable-all-tools \ --enable-all-prompts \ --enable-all-resources ``` ![AI Game Developer — Unity SKILLS and MCP](https://github.com/IvanMurzak/Unity-MCP/blob/main/docs/img/promo/hazzard-divider.svg?raw=true) ## `create-project` Create a new Unity project using the Unity Editor. ```bash unity-mcp-cli create-project /path/to/new/project ``` | Option | Required | Description | |---|---|---| | `[path]` | Yes | Path where the project will be created (positional or `--path`) | | `--unity ` | No | Unity Editor version to use (defaults to highest installed) | **Example — create a project with a specific editor version:** ```bash unity-mcp-cli create-project ./MyGame --unity 2022.3.62f1 ``` ![AI Game Developer — Unity SKILLS and MCP](https://github.com/IvanMurzak/Unity-MCP/blob/main/docs/img/promo/hazzard-divider.svg?raw=true) ## `install-plugin` Install the Unity-MCP plugin into a Unity project's `Packages/manifest.json`. ```bash unity-mcp-cli install-plugin ./MyGame ``` | Option | Required | Description | |---|---|---| | `[path]` | Yes | Path to the Unity project (positional or `--path`) | | `--plugin-version ` | No | Plugin version to install (defaults to latest from [OpenUPM](https://openupm.com/packages/com.ivanmurzak.unity.mcp/)) | This command: 1. Adds the **OpenUPM scoped registry** with all required scopes 2. Adds `com.ivanmurzak.unity.mcp` to `dependencies` 3. **Never downgrades** — if a higher version is already installed, it is preserved **Example — install a specific plugin version:** ```bash unity-mcp-cli install-plugin ./MyGame --plugin-version 0.51.6 ``` > After running this command, open the project in Unity Editor to complete the package installation. ![AI Game Developer — Unity SKILLS and MCP](https://github.com/IvanMurzak/Unity-MCP/blob/main/docs/img/promo/hazzard-divider.svg?raw=true) ## `install-unity` Install a Unity Editor version via Unity Hub CLI. ```bash unity-mcp-cli install-unity 6000.3.1f1 ``` | Argument / Option | Required | Description | |---|---|---| | `[version]` | No | Unity Editor version to install (e.g. `6000.3.1f1`) | | `--path ` | No | Read the required version from an existing project | If neither argument nor option is provided, the command installs the latest stable release from Unity Hub's releases list. **Example — install the editor version that a project needs:** ```bash unity-mcp-cli install-unity --path ./MyGame ``` ![AI Game Developer — Unity SKILLS and MCP](https://github.com/IvanMurzak/Unity-MCP/blob/main/docs/img/promo/hazzard-divider.svg?raw=true) ## `open` Open a Unity project in the Unity Editor. By default, sets MCP connection environment variables if connection options are provided. Use `--no-connect` to open without MCP connection. ```bash # Explicit path unity-mcp-cli open ./MyGame # From inside the Unity project folder — path defaults to the current directory cd ./MyGame && unity-mcp-cli open ``` | Option | Env Variable | Required | Description | |---|---|---|---| | `[path]` | — | No | Path to the Unity project (positional or `--path`). Defaults to the current working directory. | | `--unity ` | — | No | Specific Unity Editor version to use (defaults to version from project settings, falls back to highest installed) | | `--editor-path ` | — | No | Explicit path to the Unity Editor executable. Skips Unity Hub discovery, useful for custom install locations. | | `--no-connect` | — | No | Open without MCP connection environment variables | | `--url ` | `UNITY_MCP_HOST` | No | MCP server URL to connect to | | `--keep-connected` | `UNITY_MCP_KEEP_CONNECTED` | No | Force keep the connection alive | | `--token ` | `UNITY_MCP_TOKEN` | No | Authentication token | | `--auth