GitHub - CoderGamester/mcp-unity: MCP Server to integrate Unity Editor game engine with different AI Model clients (e.g. Claude Desktop, Windsurf, Cursor) (original) (raw)

MCP Unity Editor (Game Engine)

English	🇨🇳简体中文	🇯🇵日本語

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

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

IDE Integration - Package Cache Access

MCP Unity provides automatic integration with VSCode-like IDEs (Visual Studio Code, Cursor, Windsurf) 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

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_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"

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://hierarchy: Retrieves a list of all game objects in the Unity hierarchy

Example prompt: "Show me the current scene 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"

Requirements

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

Installation

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

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

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

Step 2: Install Node.js

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

Windows

Visit the Node.js download page
Download the Windows Installer (.msi) for the LTS version (recommended)
Run the installer and follow the installation wizard
Verify the installation by opening PowerShell and running: macOS
Visit the Node.js download page
Download the macOS Installer (.pkg) for the LTS version (recommended)
Run the installer and follow the installation wizard
Alternatively, if you have Homebrew installed, you can run:
Verify the installation by opening Terminal and running:

Step 3: Configure AI LLM Client

Option 1: Configure using Unity Editor

Open the Unity Editor
Navigate to Tools > MCP Unity > Server Window
Click on the "Configure" button for your AI LLM client as shown in the image below

Confirm the configuration installation with the given popup

Option 2: Configure Manually

Open the MCP configuration file of your AI client (e.g. claude_desktop_config.json in Claude Desktop) and copy the following text:

Replace ABSOLUTE/PATH/TO with the absolute path to your MCP Unity installation or just copy the text from the Unity Editor MCP Server window (Tools > MCP Unity > Server Window).

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

Start Unity Editor MCP Server

Open the Unity Editor
Navigate to Tools > MCP Unity > Server Window
Click "Start Server" to start the WebSocket server
Open Claude Desktop or your AI Coding IDE (e.g. Cursor IDE, Windsurf IDE, 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. You can change this port in two ways:

Option 1: Using the Unity Editor

Open the Unity Editor
Navigate to Tools > MCP Unity > Server Window
Change the "WebSocket Port" value to your desired port number
Unity will setup the system environment variable UNITY_PORT to the new port number
Restart the Node.js server
Click again on "Start Server" to reconnect the Unity Editor web socket to the Node.js MCP Server Option 2: Using the terminal
Set the UNITY_PORT environment variable in the terminal
- Powershell
- Command Prompt/Terminal
Restart the Node.js server
Click again on "Start Server" to reconnect the Unity Editor web socket to the Node.js MCP Server

Optional: Set Timeout

By default, the timeout between the MCP server and the WebSocket is 10 seconds. You can change depending on the OS you are using:

Option 1: Windows OS

Open the Unity Editor
Navigate to Tools > MCP Unity > Server Window
Change the "Request Timeout (seconds)" value to your desired timeout seconds
Unity will setup the system environment variable UNITY_REQUEST_TIMEOUT to the new timeout value
Restart the Node.js server
Click again on "Start Server" to reconnect the Unity Editor web socket to the Node.js MCP Server Option 2: Non-Windows OS

For non-Windows OS, you need to configure two places:

In Editor Process Timeout

Open the Unity Editor
Navigate to Tools > MCP Unity > Server Window
Change the "Request Timeout (seconds)" value to your desired timeout seconds

WebSocket Timeout

Set the UNITY_REQUEST_TIMEOUT environment variable in the terminal
- Powershell
  $env:UNITY_REQUEST_TIMEOUT = "300"
- Command Prompt/Terminal
  set UNITY_REQUEST_TIMEOUT=300
Restart the Node.js server
Click again on "Start Server" to reconnect the Unity Editor web socket to the Node.js MCP Server

Tip

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

Debugging the Server

Building the Node.js Server

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

Navigate to the Server directory:
cd ABSOLUTE/PATH/TO/mcp-unity/Server
Install dependencies:
Build the server:
Run the server: Debugging with MCP Inspector

Debug the server with @modelcontextprotocol/inspector:

Powershell

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

Command Prompt/Terminal

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

Don't forget to shutdown the server with Ctrl + C before closing the terminal or debugging it with the MCP Inspector.

Enable Console Logs

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

Troubleshooting

Connection Issues

Ensure the WebSocket server is running (check the Server Window in Unity)
Send a console log message from MCP client to force a reconnection between MCP client and Unity server
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 Connection failed when running Play Mode tests

The run_tests tool returns the following response:

Error:
Connection failed: Unknown error

This error occurs because the bridge connection is lost when the domain reloads upon switching to Play Mode.
The workaround is to turn off Reload Domain in Edit > Project Settings > Editor > "Enter Play Mode Settings".

Support & Feedback

If you have any questions or need support, please open an issue on this repository.

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