MCP Unity

Installation

Installing this MCP Unity Server is a multi-step process:

Step 1: Install Node.js

To run MCP Unity server, you'll need to have Node.js 18 or later installed on your computer:

Step 2: Install Unity MCP Server package via Unity Package Manager

1. Open the Unity Package Manager (Window > Package Manager)
2. Click the "+" button in the top-left corner
3. Select "Add package from git URL..."
4. Enter: https://github.com/CoderGamester/mcp-unity.git
5. Click "Add"

Step 3: Configure AI LLM Client

{
   "mcpServers": {
       "mcp-unity": {
          "command": "node",
          "args": [
             "ABSOLUTE/PATH/TO/mcp-unity/Server~/build/index.js"
          ]
       }
   }
}

{
   "mcpServers": {
       "mcp-unity": {
          "command": "node",
          "args": [
             "${workspaceFolder}/Library/PackageCache/com.gamelovers.mcp-unity@<hash>/Server~/build/index.js"
          ]
       }
   }
}

[mcp_servers.mcp-unity]
command = "node"
args = ["ABSOLUTE/PATH/TO/mcp-unity/Server~/build/index.js"]

{
   "mcpServers": {
       "mcp-unity": {
          "command": "node",
          "args": [
             "Library/PackageCache/com.gamelovers.mcp-unity@<hash>/Server~/build/index.js"
          ]
       }
   }
}

{
   "mcpServers": {
       "mcp-unity": {
          "command": "node",
          "args": [
             "Library/PackageCache/com.gamelovers.mcp-unity@<hash>/Server~/build/index.js"
          ]
       }
   }
}

[mcp_servers.mcp-unity]
command = "node"
args = ["Library/PackageCache/com.gamelovers.mcp-unity@<hash>/Server~/build/index.js"]

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "mcp-unity": {
      "type": "local",
      "enabled": true,
      "command": ["node", "Library/PackageCache/com.gamelovers.mcp-unity@<hash>/Server~/build/index.js"],
      "environment": {}
    }
  }
}

MCP Unity Editor (Game Engine)

                              ,/(/.   *(/,                                  
                          */(((((/.   *((((((*.                             
                     .*((((((((((/.   *((((((((((/.                         
                 ./((((((((((((((/    *((((((((((((((/,                     

             ,/(((((((((((((/*.           */(((((((((((((/*.                
            ,%%#((/((((((*                    ,/(((((/(#&@@(                
            ,%%##%%##((((((/*.             ,/((((/(#&@@@@@@(                
            ,%%######%%##((/(((/*.    .*/(((//(%@@@@@@@@@@@(                
            ,%%####%#(%%#%%##((/((((((((//#&@@@@@@&@@@@@@@@(                
            ,%%####%(    /#%#%%%##(//(#@@@@@@@%,   #@@@@@@@(                
            ,%%####%(        *#%###%@@@@@@(        #@@@@@@@(                
            ,%%####%(           #%#%@@@@,          #@@@@@@@(                
            ,%%##%%%(           #%#%@@@@,          #@@@@@@@(                
            ,%%%#*              #%#%@@@@,             *%@@@(                
            .,      ,/##*.      #%#%@@@@,     ./&@#*      *`                
                ,/#%#####%%#/,  #%#%@@@@, ,/&@@@@@@@@@&\.                    
                 `*#########%%%%###%@@@@@@@@@@@@@@@@@@&*´                   
                    `*%%###########%@@@@@@@@@@@@@@&*´                        
                        `*%%%######%@@@@@@@@@@&*´                            
                            `*#%%##%@@@@@&*´                                 
                               `*%#%@&*´                                     
                                                       
     ███╗   ███╗ ██████╗██████╗         ██╗   ██╗███╗   ██╗██╗████████╗██╗   ██╗
     ████╗ ████║██╔════╝██╔══██╗        ██║   ██║████╗  ██║██║╚══██╔══╝╚██╗ ██╔╝
     ██╔████╔██║██║     ██████╔╝        ██║   ██║██╔██╗ ██║██║   ██║    ╚████╔╝ 
     ██║╚██╔╝██║██║     ██╔═══╝         ██║   ██║██║╚██╗██║██║   ██║     ╚██╔╝  
     ██║ ╚═╝ ██║╚██████╗██║             ╚██████╔╝██║ ╚████║██║   ██║      ██║   
     ╚═╝     ╚═╝ ╚═════╝╚═╝              ╚═════╝ ╚═╝  ╚═══╝╚═╝   ╚═╝      ╚═╝   

MCP Unity is an implementation of the Model Context Protocol for Unity Editor, allowing AI assistants to interact with your Unity projects. This package provides a bridge between Unity and a Node.js server that implements the MCP protocol, enabling AI agents like Cursor, Windsurf, Claude Code, Codex CLI, GitHub Copilot, Google Antigravity, and OpenCode to execute operations within the Unity Editor.

Features

IDE Integration - Package Cache Access

MCP Unity provides automatic integration with VSCode-like IDEs (Visual Studio Code, Cursor, Windsurf, Google Antigravity) by adding the Unity Library/PackedCache folder to your workspace. This feature:

• Improves code intelligence for Unity packages
• Enables better autocompletion and type information for Unity packages
• Helps AI coding assistants understand your project's dependencies

MCP Server Tools

The following tools are available for manipulating and querying Unity scenes and GameObjects via MCP:

• execute_menu_item: Executes Unity menu items (functions tagged with the MenuItem attribute)

  Example prompt: "Execute the menu item 'GameObject/Create Empty' to create a new empty GameObject"

• select_gameobject: Selects game objects in the Unity hierarchy by path or instance ID

  Example prompt: "Select the Main Camera object in my scene"

• update_gameobject: Updates a GameObject's core properties (name, tag, layer, active/static state), or creates the GameObject if it does not exist

  Example prompt: "Set the Player object's tag to 'Enemy' and make it inactive"

• update_component: Updates component fields on a GameObject or adds it to the GameObject if it does not contain the component

  Example prompt: "Add a Rigidbody component to the Player object and set its mass to 5"

• add_package: Installs new packages in the Unity Package Manager

  Example prompt: "Add the TextMeshPro package to my project"

• run_tests: Runs tests using the Unity Test Runner

  Example prompt: "Run all the EditMode tests in my project"

• send_console_log: Send a console log to Unity

  Example prompt: "Send a console log to Unity Editor"

• add_asset_to_scene: Adds an asset from the AssetDatabase to the Unity scene

  Example prompt: "Add the Player prefab from my project to the current scene"

• create_prefab: Creates a prefab with optional MonoBehaviour script and serialized field values

  Example prompt: "Create a prefab named 'Player' from the 'PlayerController' script"

• create_scene: Creates a new scene and saves it to the specified path

  Example prompt: "Create a new scene called 'Level1' in the Scenes folder"

• load_scene: Loads a scene by path or name, with optional additive loading

  Example prompt: "Load the MainMenu scene"

• delete_scene: Deletes a scene by path or name and removes it from Build Settings

  Example prompt: "Delete the old TestScene from my project"

• get_gameobject: Gets detailed information about a specific GameObject including all components

  Example prompt: "Get the details of the Player GameObject"

• get_console_logs: Retrieves logs from the Unity console with pagination support

  Example prompt: "Show me the last 20 error logs from the Unity console"

• recompile_scripts: Recompiles all scripts in the Unity project

  Example prompt: "Recompile scripts in my Unity project"

• save_scene: Saves the current active scene, with optional Save As to a new path

  Example prompt: "Save the current scene" or "Save the scene as 'Assets/Scenes/Level2.unity'"

• get_scene_info: Gets information about the active scene including name, path, dirty state, and all loaded scenes

  Example prompt: "What scenes are currently loaded in my project?"

• unload_scene: Unloads a scene from the hierarchy (does not delete the scene asset)

  Example prompt: "Unload the UI scene from the hierarchy"

• duplicate_gameobject: Duplicates a GameObject in the scene with optional renaming and reparenting

  Example prompt: "Duplicate the Enemy prefab 5 times and rename them Enemy_1 through Enemy_5"

• delete_gameobject: Deletes a GameObject from the scene

  Example prompt: "Delete the old Player object from the scene"

• reparent_gameobject: Changes the parent of a GameObject in the hierarchy

  Example prompt: "Move the HealthBar object to be a child of the UI Canvas"

• move_gameobject: Moves a GameObject to a new position (local or world space)

  Example prompt: "Move the Player object to position (10, 0, 5) in world space"

• rotate_gameobject: Rotates a GameObject to a new rotation (local or world space, Euler angles or quaternion)

  Example prompt: "Rotate the Camera 45 degrees on the Y axis"

• scale_gameobject: Scales a GameObject to a new local scale

  Example prompt: "Scale the Enemy object to twice its size"

• set_transform: Sets position, rotation, and scale of a GameObject in a single operation

  Example prompt: "Set the Cube's position to (0, 5, 0), rotation to (0, 90, 0), and scale to (2, 2, 2)"

• create_material: Creates a new material with specified shader and saves it to the project

  Example prompt: "Create a red material called 'EnemyMaterial' using the URP Lit shader"

• assign_material: Assigns a material to a GameObject's Renderer component

  Example prompt: "Assign the 'EnemyMaterial' to the Enemy GameObject"

• modify_material: Modifies properties of an existing material (colors, floats, textures)

  Example prompt: "Change the color of 'EnemyMaterial' to blue and set metallic to 0.8"

• get_material_info: Gets detailed information about a material including shader and all properties

  Example prompt: "Show me all the properties of the 'PlayerMaterial'"

• batch_execute: Executes multiple tool operations in a single batch request, reducing round-trips and enabling atomic operations with optional rollback on failure

  Example prompt: "Create 10 empty GameObjects named Enemy_1 through Enemy_10 in a single batch operation"

MCP App tools

• show_unity_dashboard: Opens the Unity dashboard MCP App in VS Code (requires VS Code 1.109+)

  Example prompt: "Open the Unity dashboard app"

• get_play_mode_status: Gets Unity play mode status (isPlaying, isPaused)

  Example prompt: "Is Unity in play mode?"

• set_play_mode_status: Controls Unity play mode with actions: 'play' (start or unpause), 'pause' (toggle pause), 'stop' (exit play mode), 'step' (advance one frame)

  Example prompt: "Start Unity play mode" or "Pause the game" or "Step forward one frame"

MCP Server Resources

• unity://menu-items: Retrieves a list of all available menu items in the Unity Editor to facilitate execute_menu_item tool

  Example prompt: "Show me all available menu items related to GameObject creation"

• unity://scenes-hierarchy: Retrieves a list of all game objects in the current Unity scene hierarchy

  Example prompt: "Show me the current scenes hierarchy structure"

• unity://gameobject/{id}: Retrieves detailed information about a specific GameObject by instance ID or object path in the scene hierarchy, including all GameObject components with it's serialized properties and fields

  Example prompt: "Get me detailed information about the Player GameObject"

• unity://logs: Retrieves a list of all logs from the Unity console

  Example prompt: "Show me the recent error messages from the Unity console"

• unity://packages: Retrieves information about installed and available packages from the Unity Package Manager

  Example prompt: "List all the packages currently installed in my Unity project"

• unity://assets: Retrieves information about assets in the Unity Asset Database

  Example prompt: "Find all texture assets in my project"

• unity://tests/{testMode}: Retrieves information about tests in the Unity Test Runner

  Example prompt: "List all available tests in my Unity project"

• ui://unity-dashboard: Unity dashboard MCP App UI

  Example prompt: "Open the Unity dashboard app"

MCP Server Prompts

Prompts are pre-configured templates that provide guided workflows for common Unity tasks. They help AI assistants understand the proper sequence of operations and available tools for specific scenarios.

• unity_dashboard: Opens the Unity dashboard MCP app with contextual information about its features

  Usage: In your AI assistant, use the prompt "unity_dashboard" to get guided access to the Unity dashboard

• gameobject_handling_strategy: Provides a structured workflow for working with GameObjects, including which tools and resources to use

  Usage: In your AI assistant, use the prompt "gameobject_handling_strategy" with a GameObject ID, name, or path to get step-by-step guidance

Requirements

• Unity 6 or later - to install the server
• Node.js 18 or later - to start the server
• npm 9 or later - to debug the server

Note: Project Paths with Spaces

MCP Unity supports project paths containing spaces. However, if you experience connection issues, try moving your project to a path without spaces as a troubleshooting step.

Examples:

• ✅ Recommended: C:\Users\YourUser\Documents\UnityProjects\MyAwesomeGame
• ✅ Supported: C:\Users\Your User\Documents\Unity Projects\My Awesome Game

Installation

Installing this MCP Unity Server is a multi-step process:

Step 1: Install Node.js

To run MCP Unity server, you'll need to have Node.js 18 or later installed on your computer:

Step 2: Install Unity MCP Server package via Unity Package Manager

1. Open the Unity Package Manager (Window > Package Manager)
2. Click the "+" button in the top-left corner
3. Select "Add package from git URL..."
4. Enter: https://github.com/CoderGamester/mcp-unity.git
5. Click "Add"

Step 3: Configure AI LLM Client

{
   "mcpServers": {
       "mcp-unity": {
          "command": "node",
          "args": [
             "ABSOLUTE/PATH/TO/mcp-unity/Server~/build/index.js"
          ]
       }
   }
}

{
   "mcpServers": {
       "mcp-unity": {
          "command": "node",
          "args": [
             "${workspaceFolder}/Library/PackageCache/com.gamelovers.mcp-unity@<hash>/Server~/build/index.js"
          ]
       }
   }
}

[mcp_servers.mcp-unity]
command = "node"
args = ["ABSOLUTE/PATH/TO/mcp-unity/Server~/build/index.js"]

{
   "mcpServers": {
       "mcp-unity": {
          "command": "node",
          "args": [
             "Library/PackageCache/com.gamelovers.mcp-unity@<hash>/Server~/build/index.js"
          ]
       }
   }
}

{
   "mcpServers": {
       "mcp-unity": {
          "command": "node",
          "args": [
             "Library/PackageCache/com.gamelovers.mcp-unity@<hash>/Server~/build/index.js"
          ]
       }
   }
}

[mcp_servers.mcp-unity]
command = "node"
args = ["Library/PackageCache/com.gamelovers.mcp-unity@<hash>/Server~/build/index.js"]

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "mcp-unity": {
      "type": "local",
      "enabled": true,
      "command": ["node", "Library/PackageCache/com.gamelovers.mcp-unity@<hash>/Server~/build/index.js"],
      "environment": {}
    }
  }
}

Start Unity Editor MCP Server

1. Open the Unity Editor
2. Navigate to Tools > MCP Unity > Server Window
3. Click "Start Server" to start the WebSocket server
4. Open your AI Coding IDE (e.g. Cursor, Windsurf, Claude Code, Codex CLI, GitHub Copilot, Google Antigravity, OpenCode, etc.) and start executing Unity tools

When the AI client connects to the WebSocket server, it will automatically show in the green box in the window

Optional: Set WebSocket Port

By default, the WebSocket server runs on port '8090'. To change it:

1. Open the Unity Editor
2. Navigate to Tools > MCP Unity > Server Window
3. Change the "Connection Port" value to your desired port number
4. Unity persists the value in ProjectSettings/McpUnitySettings.json
5. Restart the Node.js server

The Node bridge discovers that project settings file from its installed package path, so it does not depend on the MCP client's working directory. To override it for one Node process, set UNITY_PORT, for example: UNITY_PORT=9001 node build/index.js.

Optional: Set Timeout

By default, the timeout between the MCP server and the WebSocket is 10 seconds. To change it:

1. Open the Unity Editor
2. Navigate to Tools > MCP Unity > Server Window
3. Change the "Request Timeout (seconds)" value to your desired timeout seconds
4. Unity persists the value in ProjectSettings/McpUnitySettings.json
5. Restart the Node.js server

To override it for one Node process, set UNITY_REQUEST_TIMEOUT (in seconds), for example: UNITY_REQUEST_TIMEOUT=30 node build/index.js.

Tip:
The timeout between your AI Coding IDE (e.g., Claude Desktop, Cursor IDE, Windsurf IDE) and the MCP Server depends on the IDE.

Optional: Run a Persistent Headless MCP Host

MCP Unity remains disabled in -batchmode by default so CI and cloud builds do not start a bridge or run npm. To run a long-lived headless Editor as an MCP host, opt in before launching Unity by either enabling Allow Batch Mode Server in the Server Window or setting MCP_UNITY_ALLOW_BATCH_MODE=true:

MCP_UNITY_ALLOW_BATCH_MODE=true Unity -batchmode -nographics -projectPath /path/to/project -logFile /path/to/unity.log

The Unity-side WebSocket server starts normally when opted in, but it never runs npm install or npm run build in batch mode. Ensure the Node bridge is already built and available to the MCP client.

Bridge Configuration Resolution

The Node bridge resolves each connection value in this order: its environment variable (UNITY_PORT, UNITY_HOST, or UNITY_REQUEST_TIMEOUT), MCP_UNITY_SETTINGS_PATH, the ProjectSettings/McpUnitySettings.json file found above the installed package, then a file found above its working directory, and finally the defaults. Generated MCP configurations set MCP_UNITY_SETTINGS_PATH and MCP_UNITY_AUTH_TOKEN_PATH explicitly. The bridge logs the value source and warns before falling back to defaults.

Bridge Security and Package Installation

MCP Unity creates a per-project 256-bit authentication token at Library/McpUnity/bridge-token. Token resolution is strict: MCP_UNITY_AUTH_TOKEN takes precedence, followed by MCP_UNITY_AUTH_TOKEN_PATH, followed by the token beside the discovered Unity project. Explicit missing or malformed values fail without fallback. Generated configurations use the token-file path and never copy the secret into ProjectSettings.

The Unity endpoint requires HTTP Basic credentials with username mcp-unity, and rejects every WebSocket handshake that supplies an Origin header. Direct WebSocket integrations must authenticate and omit Origin. Use the Server Window to copy or regenerate the token; after rotation, restart all MCP client processes.

The add_package tool is disabled by default because Unity packages can execute Editor code when they compile. Enable Allow Package Installation in Tools > MCP Unity > Server Window, or set AllowPackageInstallation to true in ProjectSettings/McpUnitySettings.json, only when package sources and MCP clients are trusted.

Version 1.5.0 intentionally rejects 1.4.x Node bridges. Upgrade both the Unity and Node package components, run the Unity Configure action again if the package-cache path changed, and restart MCP clients.

Optional: Allow Remote MCP Bridge Connections

By default, the WebSocket server binds to 'localhost'. To allow MCP bridge connections from other machines:

1. Open the Unity Editor
2. Navigate to Tools > MCP Unity > Server Window
3. Enable the "Allow Remote Connections" checkbox
4. Unity will bind the WebSocket server to '0.0.0.0' (all interfaces)
5. Restart the Node.js server to apply the new host configuration
6. Set the environment variable UNITY_HOST to your Unity machine's IP address when running the MCP bridge remotely: UNITY_HOST=192.168.1.100 node server.js

Remote transport remains unencrypted ws://. Authentication prevents unauthorized access but does not hide traffic; restrict remote use to a trusted network, VPN, or SSH tunnel. A remote bridge that cannot read the Unity project token file must receive MCP_UNITY_AUTH_TOKEN through a secure secret mechanism.

Debugging the Server

npx @modelcontextprotocol/inspector node Server~/build/index.js

npx @modelcontextprotocol/inspector node Server~/build/index.js

Frequently Asked Questions

Error:
Connection failed: Unknown error

Troubleshooting: WSL2 (Windows 11) networking

When running the MCP (Node.js) server inside WSL2 while Unity runs on Windows 11, connecting to ws://localhost:8090/McpUnity may fail with ECONNREFUSED.

Cause: WSL2 and Windows have separate network namespaces — localhost inside WSL2 does not point to the Windows host. By default, Unity listens on localhost:8090.

Solution 1 — Enable WSL2 Mirrored mode networking (preferred)

• Windows 11: Settings → System → For developers → WSL → Enable “Mirrored mode networking”.
• Or via .wslconfig (then run wsl --shutdown and reopen WSL):

[wsl2]
networkingMode=mirrored

After enabling, localhost is shared between Windows and WSL2, so the default config (localhost:8090) works.

Solution 2 — Point the Node client to the Windows host

Set in your WSL shell before starting the MCP client:

# Use the Windows host IP detected from resolv.conf
export UNITY_HOST=$(grep -m1 nameserver /etc/resolv.conf | awk '{print $2}')

With this, Server~/src/unity/mcpUnity.ts will connect to ws://$UNITY_HOST:8090/McpUnity instead of localhost (it reads UNITY_HOST, and may also honor a Host in ProjectSettings/McpUnitySettings.json if present).

Solution 3 — Allow remote connections from Unity

• Unity: Tools → MCP Unity → Server Window → enable “Allow Remote Connections” (Unity binds to 0.0.0.0).
• Ensure Windows Firewall allows inbound TCP on your configured port (default 8090).
• From WSL2, connect to the Windows host IP (see Solution 2) or to localhost if mirrored mode is enabled.

Note: Default port is 8090. You can change it in the Unity Server Window (Tools → MCP Unity → Server Window). The value maps to McpUnitySettings and is persisted in ProjectSettings/McpUnitySettings.json.

Validate connectivity

npm i -g wscat
# After enabling mirrored networking
wscat -c ws://localhost:8090/McpUnity
# Or using the Windows host IP
wscat -c ws://$UNITY_HOST:8090/McpUnity

Running Tests

C# Tests (Unity)

Run tests using Unity's Test Runner:

1. Open Unity Editor
2. Navigate to Window > General > Test Runner
3. Select "EditMode" tab
4. Click "Run All" to execute all tests

TypeScript Tests (Server)

Run tests using Jest:

cd Server~
npm test

To run tests in watch mode:

npm run test:watch

Support & Feedback

If you have any questions or need support, please open an issue on this repository or alternative you can reach out on:

• Linkedin:
• Discord: gamester7178
• Email: game.gamester@gmail.com

Contributing

Contributions are welcome! Please feel free to submit a Pull Request or open an Issue with your request.

Commit your changes following the Conventional Commits format.

License

This project is under MIT License

Acknowledgements

• Model Context Protocol
• Unity Technologies
• Node.js
• WebSocket-Sharp