Unity MCP server

The MCP Unity Editor provides a bridge between Unity and AI assistants, allowing them to interact with your Unity projects through the Model Context Protocol. It enables AI agents like Claude, Windsurf, and Cursor to execute operations directly within the Unity Editor.

Installation

Prerequisites

• Unity 2022.3 or later
• Node.js 18 or later
• npm 9 or later

Important: Your Unity project path must not contain spaces. For example, C:\Users\YourUser\Documents\UnityProjects\MyAwesomeGame will work, but C:\Users\Your User\Documents\Unity Projects\My Awesome Game will fail.

Step 1: Install Node.js

Download and install Node.js 18 or later from the Node.js download page.

Verify the installation by opening a terminal and running:

node --version

Step 2: Install Unity MCP Server Package

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

Using Unity Editor

1. Open the Unity Editor
2. Navigate to Tools > MCP Unity > Server Window
3. Click on the "Configure" button for your AI LLM client
4. Confirm the configuration installation in the popup

Starting the 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 (Claude Desktop, Cursor IDE, Windsurf IDE, etc.)

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

Configuration Options

Change WebSocket Port

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

1. Navigate to Tools > MCP Unity > Server Window
2. Change the "WebSocket Port" value
3. Unity will set the system environment variable UNITY_PORT
4. Restart the Node.js server
5. Click "Start Server" again

Set Timeout

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

1. Navigate to Tools > MCP Unity > Server Window
2. Change the "Request Timeout (seconds)" value
3. Unity will set the system environment variable UNITY_REQUEST_TIMEOUT
4. Restart the Node.js server
5. Click "Start Server" again

Available MCP Tools

Core Tools

• execute_menu_item: Executes Unity menu items
• select_gameobject: Selects game objects in the Unity hierarchy
• update_gameobject: Updates a GameObject's properties or creates one
• update_component: Updates component fields or adds components
• 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 to Unity
• add_asset_to_scene: Adds an asset from the AssetDatabase to the scene

Resource Queries

• unity://menu-items: Lists all available menu items
• unity://scenes-hierarchy: Shows all game objects in the current scene
• unity://gameobject/{id}: Gets detailed information about a specific GameObject
• unity://logs: Retrieves logs from the Unity console
• unity://packages: Gets information about installed and available packages
• unity://assets: Retrieves information about assets in the Unity Asset Database
• unity://tests/{testMode}: Gets information about tests in the Unity Test Runner

Debugging the Server

Force Install the Server

1. Navigate to Tools > MCP Unity > Server Window
2. Click on "Force Install Server" button

Debugging with MCP Inspector

Debug using the MCP Inspector with:

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

Enable Console Logs

For PowerShell:

$env:LOGGING = "true"
$env:LOGGING_FILE = "true"

For Command Prompt:

set LOGGING=true
set LOGGING_FILE=true

Troubleshooting

• If unable to connect to MCP Unity, check that the WebSocket server is running and try sending a console log message to force reconnection
• If the server won't start, check the Unity Console for errors and verify Node.js installation
• If you get a "Connection failed: Unknown error" when running Play Mode tests, turn off "Reload Domain" in Edit > Project Settings > Editor > "Enter Play Mode Settings"

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

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

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

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

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

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

3. Restart Claude Desktop for the changes to take effect