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
• ✅ Run tools — execute MCP tools directly from the command line
• ✅ 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

Run any command instantly with npx — no installation required:

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

Or install globally:

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

Requirements: Node.js >= 18. Unity Hub is installed automatically if not found.

Contents

• Quick Start
• Commands
  • configure — Configure MCP tools, prompts, and resources
  • create-project — Create a new Unity project
  • install-plugin — Install Unity-MCP plugin into a project
  • install-unity — Install Unity Editor via Unity Hub
  • open — Open a Unity project in the Editor
  • remove-plugin — Remove Unity-MCP plugin from a project
  • run-tool — Execute an MCP tool via the HTTP API
• Global Options
• Full Automation Example
• How It Works

Commands

configure

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

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

Example — enable specific tools and disable all prompts:

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

Example — enable everything:

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

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

Example — create a project with a specific editor version:

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

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

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

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

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

npx unity-mcp-cli open ./MyGame

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

Example — open with MCP connection:

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

Example — open without MCP connection (simple open):

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

Example — open with authentication and specific tools:

npx 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).

npx 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 cloudServerUrl (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):

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

Example — explicit URL override:

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

Example — pipe raw JSON output:

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

remove-plugin

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

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

Global Options

These options are available on all commands:

Example — run any command with verbose output:

npx 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
npx unity-mcp-cli create-project ./MyAIGame --unity 6000.3.1f1

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

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

# 4. Open the project with MCP connection
npx 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.