中文 | 日本語 | 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.

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

Quick Start

Install globally and run:

npm install -g unity-mcp-cli
unity-mcp-cli install-plugin /path/to/unity/project

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
• Commands
  • configure
  • create-project
  • install-plugin
  • install-unity
  • open
  • run-tool
  • setup-mcp
  • setup-skills
  • remove-plugin
  • 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

| Option | Required | Description | |---|---|---| | [path] | Yes | Path to the Unity project (positional or --path) | | --list | No | List current configuration and exit | | --enable-tools <names> | No | Enable specific tools (comma-separated) | | --disable-tools <names> | No | Disable specific tools (comma-separated) | | --enable-all-tools | No | Enable all tools | | --disable-all-tools | No | Disable all tools | | --enable-prompts <names> | No | Enable specific prompts (comma-separated) | | --disable-prompts <names> | No | Disable specific prompts (comma-separated) | | --enable-all-prompts | No | Enable all prompts | | --disable-all-prompts | No | Disable all prompts | | --enable-resources <names> | No | Enable specific resources (comma-separated) | | --disable-resources <names> | 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:

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

| Option | Required | Description | |---|---|---| | [path] | Yes | Path where the project will be created (positional or --path) | | --unity <version> | No | Unity Editor version to use (defaults to highest installed) |

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

| Option | Required | Description | |---|---|---| | [path] | Yes | Path to the Unity project (positional or --path) | | --plugin-version <version> | No | Plugin version to install (defaults to latest from OpenUPM) |

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

| Argument / Option | Required | Description | |---|---|---| | [version] | No | Unity Editor version to install (e.g. 6000.3.1f1) | | --path <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:

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

| Option | Env Variable | Required | Description | |---|---|---|---| | [path] | — | Yes | Path to the Unity project (positional or --path) | | --unity <version> | — | No | Specific Unity Editor version to use (defaults to version from project settings, falls back to highest installed) | | --no-connect | — | No | Open without MCP connection environment variables | | --url <url> | UNITY_MCP_HOST | No | MCP server URL to connect to | | --keep-connected | UNITY_MCP_KEEP_CONNECTED | No | Force keep the connection alive | | --token <token> | UNITY_MCP_TOKEN | No | Authentication token | | --auth <option> | UNITY_MCP_AUTH_OPTION | No | Auth mode: none or required | | --tools <names> | UNITY_MCP_TOOLS | No | Comma-separated list of tools to enable | | --transport <method> | UNITY_MCP_TRANSPORT | No | Transport method: streamableHttp or stdio | | --start-server <value> | UNITY_MCP_START_SERVER | No | Set to true or false to control MCP server auto-start |

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"}'

| Option | Required | Description | |---|---|---| | <tool-name> | Yes | Name of the MCP tool to execute | | [path] | No | Unity project path (positional or --path) — used to read config and detect port | | --url <url> | No | Direct server URL override (bypasses config) | | --token <token> | No | Bearer token override (bypasses config) | | --input <json> | No | JSON string of tool arguments (defaults to {}) | | --input-file <file> | No | Read JSON arguments from a file | | --raw | No | Output raw JSON (no formatting, no spinner) | | --timeout <ms> | No | Request timeout in milliseconds (default: 60000) |

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'

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

| Option | Required | Description | |---|---|---| | [agent-id] | Yes | Agent to configure (use --list to see all) | | [path] | No | Unity project path (defaults to cwd) | | --transport <transport> | No | Transport method: stdio or http (default: http) | | --url <url> | No | Server URL override (for http transport) | | --token <token> | No | Auth token override | | --list | No | List all available agent IDs |

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

| Option | Required | Description | |---|---|---| | [agent-id] | Yes | Agent to generate skills for (use --list to see all) | | [path] | No | Unity project path (defaults to cwd) | | --url <url> | No | Server URL override | | --token <token> | No | Auth token override | | --list | No | List all agents with skills support status | | --timeout <ms> | No | Request timeout in milliseconds (default: 60000) |

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

| Option | Required | Description | |---|---|---| | [path] | Yes | Path to the Unity project (positional or --path) |

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.

Global Options

These options are available on all commands:

| Option | Description | |---|---| | -v, --verbose | Enable verbose diagnostic output for troubleshooting | | --version | Display CLI version | | --help | Display help for the command |

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. Configure Claude Code MCP integration
unity-mcp-cli setup-mcp claude-code ./MyAIGame

# 5. Open the project with MCP connection
unity-mcp-cli open ./MyAIGame \
  --url http://localhost:8080 \
  --keep-connected

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.