Unity MCP Complex MCP Server

How to use

You run a local MCP Unity server inside the Unity Editor and connect it to an MCP client (such as an AI assistant or IDE) over WebSocket. The client can request actions like selecting GameObjects, updating components, running tests, and executing Unity menu items. Start the server from the Unity Editor, then use your MCP client to send commands. The server exposes a set of tools and resources that your AI can invoke to perform common editor tasks without manual clicks.

How to install

Prerequisites you need before starting:

- Node.js 18 or later

- npm 9 or later

- Unity 2022.3 or later

How to install

Step 1. Install Node.js

How to install

Windows: install Node.js using the Windows Installer for the LTS version, then verify with node --version.

How to install

macOS: install Node.js using the macOS installer for the LTS version, or run brew install node@18 if you have Homebrew, then verify with node --version.

How to install

Step 2. Install the Unity MCP Server package via Unity Package Manager

How to install

- Open Unity

How to install

- Go to Window > Package Manager

How to install

- Click the + button and choose Add package from git URL…

How to install

- Enter: https://github.com/CoderGamester/mcp-unity.git and click Add

How to configure the client

Option 1: Configure using the Unity Editor

How to configure the client

1. Open the Unity Editor

How to configure the client

2. Navigate to Tools > MCP Unity > Server Window

How to configure the client

3. Click the Configure button for your AI LLM client as shown in the interface

How to configure the client

4. Confirm the configuration installation when prompted

How to configure the client

Option 2: Configure Manually

How to configure the client

Open the MCP configuration file for your AI client and paste the following, replacing ABSOLUTE/PATH/TO with your path to the MCP Unity installation.

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

How to start the server

Step 1. Open the Unity Editor

How to start the server

Step 2. Open Tools > MCP Unity > Server Window

How to start the server

Step 3. Click Start Server to start the WebSocket server

How to start the server

Step 4. Open your MCP client and begin issuing Unity editor commands

Optional: Set WebSocket Port

The default WebSocket port is 8090. To change it

Optional: Set WebSocket Port

1. Open Unity Editor

Optional: Set WebSocket Port

2. Go to Tools > MCP Unity > Server Window

Optional: Set WebSocket Port

3. Change the WebSocket Port value

Optional: Set WebSocket Port

4. Restart Node.js server to apply changes

Optional: Set Timeout

You can adjust the request timeout between and the MCP server

Optional: Set Timeout

1. Open Unity Editor

Optional: Set Timeout

2. Go to Tools > MCP Unity > Server Window

Optional: Set Timeout

3. Change the Request Timeout (seconds) value

Optional: Set Timeout

4. Restart the Node.js server

Optional: Enable Remote Connections

To allow remote MCP bridge connections

Optional: Enable Remote Connections

1. Open Unity Editor

Optional: Enable Remote Connections

2. Go to Tools > MCP Unity > Server Window

Optional: Enable Remote Connections

3. Enable the Allow Remote Connections option

Optional: Enable Remote Connections

4. Restart the Node.js server to apply changes

Debugging the Server

Building the Node.js Server

Debugging the Server

The MCP Unity server runs on Node.js and compiles TypeScript to JavaScript in a build directory. If issues arise, force install the server

Debugging the Server

Manual build steps

Debugging the Server

1. Open the Unity Editor
2. Tools > MCP Unity > Server Window
3. Click on "Force Install Server"

Debugging the Server

If you want to build it manually, run these commands from the Server directory

Debugging the Server

cd ABSOLUTE/PATH/TO/mcp-unity/Server~

npm install
npm run build
node build/index.js

Debugging with MCP Inspector

Debug the server with MCP Inspector using either PowerShell or a terminal

Debugging with MCP Inspector

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

Debugging with MCP Inspector

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

Enable Console Logs

Turn on logging in your terminal or log file to diagnose issues

Enable Console Logs

# Powershell
$env:LOGGING = "true"
$env:LOGGING_FILE = "true"
```
```cmd
set LOGGING=true
set LOGGING_FILE=true

Frequently Asked Questions

What is MCP Unity? It bridges your Unity Editor with AI assistants using the Model Context Protocol, exposing editor tasks as tools and resources for AI control.

Frequently Asked Questions

Why am I unable to connect? Ensure the WebSocket server is running, try forcing a reconnection, and verify the port configuration in the Server Window.

Support

If you need help, reach out through the provided channels for guidance and feedback.

Notes

Project path must not contain spaces to avoid MCP client connection issues.

execute_menu_item

Executes Unity menu items (functions tagged with the MenuItem attribute) to perform editor actions like creating objects or triggering menu commands.

select_gameobject

Selects GameObjects in the hierarchy by path or instance ID for further operations.

update_gameobject

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

update_component

Updates or adds a component on a GameObject and sets its fields.

add_package

Installs new packages in the Unity Package Manager.

run_tests

Runs tests using the Unity Test Runner.

send_console_log

Sends a console log message to Unity Editor.

add_asset_to_scene

Adds an asset from the AssetDatabase to the current scene.