Navigation
MCP Unity: AI Integration & Smarter Workflows - MCP Implementation

MCP Unity: AI Integration & Smarter Workflows

MCP Unity empowers developers to seamlessly integrate Unity Editor with AI clients like Claude, Windsurf, and Cursor, accelerating innovation and smarter workflows.

Developer Tools
4.6(110 reviews)
165 saves
77 comments

Ranked in the top 3% of all AI tools in its category

About MCP Unity

What is MCP Unity: AI Integration & Smarter Workflows?

MCP Unity is a bridge between the Unity Editor and AI assistants like Claude, Windsurf, and Cursor. It implements the Model Context Protocol (MCP), enabling AI agents to execute commands directly within Unity projects. By integrating a Node.js server with Unity, developers can automate tasks such as package management, test execution, and asset manipulation through AI-driven workflows.

How to Use MCP Unity: AI Integration & Smarter Workflows?

To leverage MCP Unity:

  1. Install the Unity package via the Package Manager.
  2. Set up a Node.js server to handle MCP protocol requests.
  3. Configure your AI tool (e.g., Windsurf) to connect to the server using specified ports.
  4. Start the WebSocket server within Unity and initiate AI-driven operations.

Ensure port configurations match across Unity’s Server Window and Node.js environment variables.

MCP Unity Features

Key Features of MCP Unity: AI Integration & Smarter Workflows?

  • Automated Task Execution: Execute Unity menu commands (e.g., Build Settings) programmatically.
  • Package Management: Install, update, or remove packages via AI-driven workflows.
  • Test Orchestration: Run and analyze test suites directly from AI interfaces.
  • Asset Interaction: Select objects, modify scenes, and manage assets through API calls.
  • Custom Port Configuration: Adjust WebSocket ports to avoid conflicts with existing services.

Use Cases of MCP Unity: AI Integration & Smarter Workflows?

Developers use MCP Unity to:

  • Automate repetitive tasks like scene setup or dependency checks.
  • Streamline CI/CD pipelines with AI-assisted build and test workflows.
  • Enable collaborative environments where AI tools suggest or execute fixes based on project context.
  • Debug complex scenarios by triggering Unity-specific operations remotely.

MCP Unity FAQ

FAQ from MCP Unity: AI Integration & Smarter Workflows?

Q: Why isn’t my AI tool connecting to the Unity server?

A: Verify the WebSocket port in Unity’s Server Window matches the Node.js environment variable (UNITY_PORT). Check firewall settings and ensure Node.js is running.

Q: My custom menu command isn’t executing. What should I check?

A: Confirm the command’s path exactly matches Unity’s menu structure (case-sensitive). Ensure the command doesn’t require user confirmation or a specific editor context.

Q: Can I use MCP Unity with multiple AI platforms simultaneously?

A: Yes, configure separate server instances or adjust port assignments to handle concurrent AI tool connections.

Q: How do I troubleshoot server crashes?

A: Enable logging via environment variables (LOGGING=true) and review logs for errors. Use the MCP Inspector tool for deeper debugging insights.

Content

MCP Unity

smithery badge

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

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 Claude, Windsurf, and Cursor to execute operations within the Unity Editor.

Features

MCP Unity currently provides the following tools:

  • execute_menu_item : Executes Unity menu items (functions tagged with the MenuItem attribute)
  • select_object : Selects game objects in the Unity hierarchy
  • package_manager : Installs, removes, and updates packages in the Unity Package Manager
  • run_tests : Runs tests using the Unity Test Runner
  • notify_message : Displays messages in the Unity Editor

MCP Unity currently provides the following resources:

  • get_menu_items : Retrieves a list of all available menu items in the Unity Editor to facilitate execute_menu_item tool
  • get_hierarchy : Retrieves a list of all game objects in the Unity hierarchy
  • get_console_logs : Retrieves a list of all logs from the Unity console
  • get_packages : Retrieves information about installed and available packages from the Unity Package Manager
  • get_assets : Retrieves information about assets in the Unity Asset Database
  • get_tests : Retrieves information about tests in the Unity Test Runner

Requirements

  • Unity 2022.3 or later
  • Node.js 18 or later (for running the server)
  • npm 9 or later (for building the server)

Installation

Installing the 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"

package manager

Installing Node.js

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

Windows

  1. Visit the Node.js download page

  2. Download the Windows Installer (.msi) for the LTS version (recommended)

  3. Run the installer and follow the installation wizard

  4. Verify the installation by opening PowerShell and running:

    node --version

npm --version

macOS

  1. Visit the Node.js download page

  2. Download the macOS Installer (.pkg) for the LTS version (recommended)

  3. Run the installer and follow the installation wizard

  4. Alternatively, if you have Homebrew installed, you can run:

    brew install node@18

  5. Verify the installation by opening Terminal and running:

    node --version

npm --version

Installing via Smithery

To install MCP Unity via Smithery:

Currently not available

Configure MCP Server

Replace ABSOLUTE/PATH/TO with the absolute path to your MCP Unity installation.

The right configuration can be accessed in the Unity Editor MCP Server window (Tools > MCP Unity > Server Window)

MCP configuration

Configure your AI client

To configure Cursor IDE:

  • Add the following configuration to your Cursor MCP Configure settings:

    Name: MCP Unity
    Type: commmand
    Command: env UNITY_PORT=8090 node ABSOLUTE/PATH/TO/mcp-unity/Server/build/index.js

To configure Claude Desktop:

  • Open the MCP configuration file (claude_desktop_config.json) in Claude Desktop Developer in (File > Settings > Developer > Edit Config)

To configure Windsurf IDE:

  • Open the MCP configuration file (mcp_config.json) in Windsurf IDE in (Windsurf Settings > Advanced Settings > General > Add Sever)

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

Running the Server

You need to run the MCP Unity server for this to work, in the following ways:

Start Node.js Server

  1. Navigate to this mcp-unity package directory in your device with the terminal.

    cd ABSOLUTE/PATH/TO/mcp-unity

  2. Run the server using Node.js:

    node Server/build/index.js

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

connect

Configure the WebSocket Port

By default, the WebSocket server runs on port 8080. You can change this port in two ways:

Option 1: Using the Unity Editor

  1. Open the Unity Editor
  2. Navigate to Tools > MCP Unity > Server Window
  3. Change the "WebSocket Port" value to your desired port number
  4. Unity will setup the system environment variable UNITY_PORT to the new port number
  5. Restart the Node.js server
  6. Click again on "Start Server" to reconnect the Unity Editor web socket to the Node.js MCP Server

Option 2: Change the system environment variable UNITY_PORT in the terminal

  1. Set the UNITY_PORT environment variable in the terminal
    * Powershell
    $env:UNITY_PORT = "8090"
* Command Prompt/Terminal

    set UNITY_PORT=8090
  1. Restart the Node.js server
  2. Click again on "Start Server" to reconnect the Unity Editor web socket to the Node.js MCP Server

Building and Debugging the Server

The MCP Unity server is built using Node.js and TypeScript. It requires to compile the TypeScript code to JavaScript in the build directory. To build the server, open a terminal and:

  1. Navigate to the Server directory:

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

  2. Install dependencies:

    npm install

  3. Build the server:

    npm run build

Debugging

  1. Debug the server with @modelcontextprotocol/inspector:
* Powershell

    $env:UNITY_PORT=8090; npx @modelcontextprotocol/inspector node Server/build/index.js


* Command Prompt/Terminal

    set UNITY_PORT=8090 && npx @modelcontextprotocol/inspector node Server/build/index.js
  1. Enable logging on your terminal or into a log.txt file:
* Powershell

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


* Command Prompt/Terminal

    set LOGGING=true
set LOGGING_FILE=true

Don't forget to shutdown the server with Ctrl + C before closing the terminal or debugging it with the @modelcontextprotocol/inspector.

Troubleshooting

Connection Issues

  • Ensure the WebSocket server is running (check the Server Window in Unity)
  • Check if there are any firewall restrictions blocking the connection
  • Make sure the port number is correct (default is 8080)
  • Change the port number in the Unity Editor MCP Server window. (Tools > MCP Unity > Server Window)

Server Not Starting

  • Check the Unity Console for error messages
  • Ensure Node.js is properly installed and accessible in your PATH
  • Verify that all dependencies are installed in the Server directory

Menu Items Not Executing

  • Ensure the menu item path is correct (case-sensitive)
  • Check if the menu item requires confirmation
  • Verify that the menu item is available in the current context

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

Related MCP Servers & Clients