Unity MCP — CLI

                                

中文 | 日本語 | Español

Cross-platform CLI tool for Unity MCP — create projects, install plugins, configure MCP tools, and launch Unity with active MCP connections. All from a single command line.

• ✅ Create projects — scaffold new Unity projects via Unity Editor
• ✅ Install editors — install any Unity Editor version from the command line
• ✅ Install plugin — add Unity-MCP plugin to manifest.json with all required scoped registries
• ✅ Remove plugin — remove Unity-MCP plugin from manifest.json
• ✅ Configure — enable/disable MCP tools, prompts, and resources
• ✅ Status check — see Unity process, local server, and cloud server connection status at a glance
• ✅ Run tools — execute MCP tools directly from the command line
• ✅ Setup MCP — write AI agent MCP config files for any of 14 supported agents
• ✅ Setup skills — generate skill files for AI agents via the MCP server
• ✅ Wait for ready — poll until Unity Editor and MCP server are connected and accepting tool calls
• ✅ Open & Connect — launch Unity with optional MCP environment variables for automated server connection
• ✅ Cross-platform — Windows, macOS, and Linux
• ✅ CI-friendly — auto-detects non-interactive terminals and disables spinners/colors
• ✅ Verbose mode — use --verbose on any command for detailed diagnostic output
• ✅ Version-aware — never downgrades plugin versions, resolves latest from OpenUPM

Quick Start

Install globally and run:

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

npx unity-mcp-cli install-plugin /path/to/unity/project

Requirements: Node.js ^20.19.0 || >=22.12.0. Unity Hub is installed automatically if not found.

Contents

• Quick Start
• Contents
• Commands
  • configure
  • create-project
  • install-plugin
  • install-unity
  • open
  • run-tool
  • wait-for-ready
  • setup-mcp
  • setup-skills
  • remove-plugin
  • status
  • Global Options
• Full Automation Example
• How It Works
  • Deterministic Port
  • Plugin Installation
  • Configuration File
  • Unity Hub Integration

Commands

configure

Configure MCP tools, prompts, and resources in UserSettings/AI-Game-Developer-Config.json.

unity-mcp-cli configure ./MyGame --list

Example — enable specific tools and disable all prompts:

unity-mcp-cli configure ./MyGame \
  --enable-tools gameobject-create,gameobject-find \
  --disable-all-prompts

Example — enable everything:

unity-mcp-cli configure ./MyGame \
  --enable-all-tools \
  --enable-all-prompts \
  --enable-all-resources

create-project

Create a new Unity project using the Unity Editor.

unity-mcp-cli create-project /path/to/new/project

Example — create a project with a specific editor version:

unity-mcp-cli create-project ./MyGame --unity 2022.3.62f1

install-plugin

Install the Unity-MCP plugin into a Unity project's Packages/manifest.json.

unity-mcp-cli install-plugin ./MyGame

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:

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.

install-unity

Install a Unity Editor version via Unity Hub CLI.

unity-mcp-cli install-unity 6000.3.1f1

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:

unity-mcp-cli install-unity --path ./MyGame

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.

unity-mcp-cli open ./MyGame

The editor process is spawned in detached mode — the CLI returns immediately.

Example — open with MCP connection:

unity-mcp-cli open ./MyGame \
  --url http://localhost:8080 \
  --keep-connected

Example — open without MCP connection (simple open):

unity-mcp-cli open ./MyGame --no-connect

Example — open with authentication and specific tools:

unity-mcp-cli open ./MyGame \
  --url http://my-server:8080 \
  --token my-secret-token \
  --auth required \
  --tools gameobject-create,gameobject-find

run-tool

Execute an MCP tool directly via the HTTP API. The server URL and authorization token are automatically resolved from the project's config file (UserSettings/AI-Game-Developer-Config.json), based on the current connection mode (Custom or Cloud).

unity-mcp-cli run-tool gameobject-create ./MyGame --input '{"name":"Cube"}'

URL resolution priority:

1. --url → use directly
2. Config file → host (Custom mode) or hardcoded cloud endpoint (Cloud mode)
3. Deterministic port from project path

Authorization is read automatically from the project config (token in Custom mode, cloudToken in Cloud mode). Use --token to override the config-derived token explicitly.

Example — call a tool (URL and auth from config):

unity-mcp-cli run-tool gameobject-find ./MyGame --input '{"query":"Player"}'

Example — explicit URL override:

unity-mcp-cli run-tool scene-save --url http://localhost:8080

Example — pipe raw JSON output:

unity-mcp-cli run-tool assets-list ./MyGame --raw | jq '.results'

wait-for-ready

Wait until Unity Editor and MCP server are connected and ready to accept tool calls. Polls the server at a configurable interval until it responds successfully or the timeout is reached. Useful for automation scripts and AI agent orchestration where open launches Unity but the agent needs to know when it can start calling tools.

unity-mcp-cli wait-for-ready ./MyGame

Example — wait with default timeout (120s):

unity-mcp-cli open ./MyGame
unity-mcp-cli wait-for-ready ./MyGame
unity-mcp-cli run-tool tests-run ./MyGame --input '{"testMode":"EditMode"}'

Example — shorter timeout for CI:

unity-mcp-cli wait-for-ready ./MyGame --timeout 60000 --interval 2000

Example — explicit server URL:

unity-mcp-cli wait-for-ready --url http://localhost:8080 --timeout 30000

setup-mcp

Write MCP config files for AI agents, enabling headless/CI setup without the Unity Editor UI. Supports all 14 agents (Claude Code, Cursor, Gemini, Codex, etc.).

unity-mcp-cli setup-mcp claude-code ./MyGame

Example — list all supported agents:

unity-mcp-cli setup-mcp --list

Example — configure Cursor with stdio transport:

unity-mcp-cli setup-mcp cursor ./MyGame --transport stdio

setup-skills

Generate skill files for an AI agent by calling the MCP server's system tool API. Requires Unity Editor to be running with the MCP plugin installed.

unity-mcp-cli setup-skills claude-code ./MyGame

Example — list agents with skills support:

unity-mcp-cli setup-skills --list

remove-plugin

Remove the Unity-MCP plugin from a Unity project's Packages/manifest.json.

unity-mcp-cli remove-plugin ./MyGame

This command:

1. Removes com.ivanmurzak.unity.mcp from dependencies
2. Preserves scoped registries and scopes — other packages may depend on them
3. No-op if the plugin is not installed

After running this command, open the project in Unity Editor to apply the change.

status

Check Unity Editor and MCP server connection status. Shows whether Unity is running, whether the local MCP server is reachable, and whether the config-resolved server (e.g., cloud) is reachable.

unity-mcp-cli status ./MyGame

Example output:

Unity-MCP Status
  Project: /path/to/MyGame
──────────────────────────────────────────────────
Unity Editor Process
✔  Unity is running (PID: 53740)
Local MCP Server
  URL: http://localhost:22958
✖  Not available (connection refused)
Config Server
  URL: https://ai-game.dev/mcp
✔  Connected
──────────────────────────────────────────────────
✔  MCP server is reachable — ready for tool calls

Global Options

These options are available on all commands:

Example — run any command with verbose output:

unity-mcp-cli install-plugin ./MyGame --verbose

Full Automation Example

Set up a complete Unity MCP project from scratch in one script:

# 1. Create a new Unity project
unity-mcp-cli create-project ./MyAIGame --unity 6000.3.1f1

# 2. Install the Unity-MCP plugin
unity-mcp-cli install-plugin ./MyAIGame

# 3. Enable all MCP tools
unity-mcp-cli configure ./MyAIGame --enable-all-tools

# 4. Login to cloud server (authenticates and saves token)
unity-mcp-cli login ./MyAIGame

# 5. Open the project (auto-connects and generates skills for claude-code)
unity-mcp-cli open ./MyAIGame

# 6. Wait for Unity Editor and MCP server to be ready
unity-mcp-cli wait-for-ready ./MyAIGame

# 7. Run tests to verify everything works
unity-mcp-cli run-tool tests-run ./MyAIGame --input '{"testMode":"EditMode"}'

How It Works

Deterministic Port

The CLI generates a deterministic port for each Unity project based on its directory path (SHA256 hash mapped to port range 20000–29999). This matches the port generation in the Unity plugin, ensuring the server and plugin automatically agree on the same port without manual configuration.

Plugin Installation

The install-plugin command modifies Packages/manifest.json directly:

• Adds the OpenUPM scoped registry (package.openupm.com)
• Registers all required scopes (com.ivanmurzak, extensions.unity, org.nuget.*)
• Adds the com.ivanmurzak.unity.mcp dependency with version-aware updates (never downgrades)

Configuration File

The configure command reads and writes UserSettings/AI-Game-Developer-Config.json, which controls:

• Tools — MCP tools available to AI agents
• Prompts — pre-defined prompts injected into LLM conversations
• Resources — read-only data exposed to AI agents
• Connection settings — host URL, auth token, transport method, timeouts

Unity Hub Integration

Commands that manage editors or create projects use the Unity Hub CLI (--headless mode). If Unity Hub is not installed, the CLI downloads and installs it automatically:

• Windows — silent install via UnityHubSetup.exe /S (may require administrator privileges)
• macOS — downloads the DMG, mounts it, and copies Unity Hub.app to /Applications
• Linux — downloads UnityHub.AppImage to ~/Applications/

For the full Unity-MCP project documentation, see the main README.