Unity3d Game Engine

What is MCP Unity?

MCP Unity is a powerful bridge that connects your Unity Editor environment to AI assistants LLM tools using the Model Context Protocol (MCP). It allows external AI (like LLM-based coding assistants) to control and query the Unity Editor itself to manipulate scenes, assets, and project settings. It runs a WebSocket server inside Unity and a Node.js server (acting as a WebSocket client to Unity) that implements the MCP, enabling AI assistants to send commands to Unity and receive information back.

How to use MCP Unity?

To use MCP Unity, you need Unity 2022.3 or later, Node.js 18 or later, and npm 9 or later. The installation involves three steps:

1. Install Node.js: Download and install Node.js from its official website.
2. Install Unity MCP Server package: Add the package to your Unity project via the Unity Package Manager using the Git URL https://github.com/CoderGamester/mcp-unity.git.
3. Configure AI LLM Client: Configure your AI LLM client (e.g., Claude Desktop, Cursor, Windsurf) either through the Unity Editor (Tools > MCP Unity > Server Window > Configure) or manually by adding the MCP server configuration to your AI client's configuration file.

After installation, open the Unity Editor, navigate to Tools > MCP Unity > Server Window, and click "Start Server". Then, open your AI Coding IDE and start executing Unity tools.

Key Features of MCP Unity

• IDE Integration - Package Cache Access: Automatically integrates with VSCode-like IDEs by adding the Unity Library/PackedCache folder to your workspace, improving code intelligence, autocompletion, and helping AI coding assistants understand project dependencies.
• MCP Server Tools: Provides a set of tools for manipulating and querying Unity scenes and GameObjects via MCP, including:
  • execute_menu_item: Executes Unity menu items.
  • select_gameobject: Selects game objects in the Unity hierarchy.
  • update_gameobject: Updates or creates GameObjects and their core properties.
  • update_component: Updates component fields on a GameObject 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 Unity scene.
• MCP Server Resources: Offers resources to retrieve information from Unity, such as:
  • unity://menu-items: Retrieves a list of all available menu items.
  • unity://scenes-hierarchy: Retrieves a list of all game objects in the current scene hierarchy.
  • unity://gameobject/{id}: Retrieves detailed information about a specific GameObject.
  • unity://logs: Retrieves a list of all logs from the Unity console.
  • unity://packages: Retrieves information about installed and available packages.
  • unity://assets: Retrieves information about assets in the Unity Asset Database.
  • unity://tests/{testMode}: Retrieves information about tests in the Unity Test Runner.
• Configurable WebSocket Port and Timeout: Allows users to change the default WebSocket port and timeout settings.
• Remote MCP Bridge Connections: Supports allowing MCP bridge connections from other machines.

Use Cases of MCP Unity

• Accelerated Development: Automate repetitive tasks, generate boilerplate code, and manage assets using AI prompts.
• Enhanced Productivity: Interact with Unity Editor features without manually clicking through menus or writing scripts.
• Improved Accessibility: Enables users less familiar with Unity Editor or C# scripting to contribute to projects through AI guidance.
• Seamless Integration: Works with various AI assistants and IDEs that support MCP.
• Extensibility: Allows defining new tools and resources to expose more project-specific or Unity functionality to AI.
• Collaborative Potential: Facilitates AI assistance in tasks traditionally done by team members or helps onboard new developers.

Frequently Asked Questions about MCP Unity

• What is MCP Unity? A bridge connecting Unity Editor to AI assistants LLM tools using the Model Context Protocol (MCP).
• Why use MCP Unity? For accelerated development, enhanced productivity, improved accessibility, seamless integration, extensibility, and collaborative potential.
• How does MCP Unity compare with the upcoming Unity 6.2 AI features? MCP Unity focuses on Editor automation and interaction, allowing external AI to control and query the Unity Editor. Unity 6.2 AI aims at in-Editor content creation and running AI model inference within games. They are complementary.
• What MCP hosts and IDEs currently support MCP Unity? Windsurf, Cursor, GitHub Copilot, and Claude Desktop.
• Can I extend MCP Unity with custom tools for my project? Yes, by creating new C# classes and defining corresponding TypeScript tool handlers.
• Is MCP Unity free to use? Yes, it is an open-source project under the MIT License.
• Why am I unable to connect to MCP Unity? Ensure the WebSocket server is running, send a console log message from the MCP client to force reconnection, or change the port number.
• Why won't the MCP Unity server start? Check Unity Console for errors, ensure Node.js is installed, and verify dependencies.
• Why do I get a connection failed error when running Play Mode tests? This 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".

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

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"

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"

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

[!IMPORTANT] Project Path Cannot Contain Spaces

It is crucial that the file path to your Unity project does not contain any spaces. If your project path includes spaces, the MCP Client (e.g., Cursor, Claude, Windsurf) will fail to connect to the MCP Unity server.

Examples:

• ✅ Works: C:\Users\YourUser\Documents\UnityProjects\MyAwesomeGame
• ❌ Fails: C:\Users\Your User\Documents\Unity Projects\My Awesome Game

Please ensure your project is located in a path without spaces before proceeding with the installation.

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:

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
   

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
   

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

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

4. Confirm the configuration installation with the given popup

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

1. Open the Unity Editor
2. Navigate to Tools > MCP Unity > Server Window
3. Click "Start Server" to start the WebSocket server
4. 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:

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

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:

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 will setup the system environment variable UNITY_REQUEST_TIMEOUT to the new timeout value
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

[!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: 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

Debugging the Server

The MCP Unity server is built using Node.js . It requires to compile the TypeScript code to JavaScript in the build directory. In case of issues, you can force install it in by:

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

If you want to build it manually, you can follow these steps:

1. Open a terminal/PowerShell/Command Prompt

2. Navigate to the Server directory:

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

3. Install dependencies:

   npm install
   

4. Build the server:

   npm run build
   

5. Run the server:

   node build/index.js
   

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.

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
   

Frequently Asked Questions

MCP Unity is a powerful bridge that connects your Unity Editor environment to AI assistants LLM tools using the Model Context Protocol (MCP).

In essence, MCP Unity:

• Exposes Unity Editor functionalities (like creating objects, modifying components, running tests, etc.) as "tools" and "resources" that an AI can understand and use.
• Runs a WebSocket server inside Unity and a Node.js server (acting as a WebSocket client to Unity) that implements the MCP. This allows AI assistants to send commands to Unity and receive information back.
• Enables you to use natural language prompts with your AI assistant to perform complex tasks within your Unity project, significantly speeding up development workflows.

MCP Unity offers several compelling advantages for developers, artists, and project managers:

• Accelerated Development: Automate repetitive tasks, generate boilerplate code, and manage assets using AI prompts. This frees up your time to focus on creative and complex problem-solving.
• Enhanced Productivity: Interact with Unity Editor features without needing to manually click through menus or write scripts for simple operations. Your AI assistant becomes a direct extension of your capabilities within Unity.
• Improved Accessibility: Allows users who are less familiar with the deep intricacies of the Unity Editor or C# scripting to still make meaningful contributions and modifications to a project through AI guidance.
• Seamless Integration: Designed to work with various AI assistants and IDEs that support MCP, providing a consistent way to leverage AI across your development toolkit.
• Extensibility: The protocol and the toolset can be expanded. You can define new tools and resources to expose more of your project-specific or Unity's functionality to AI.
• Collaborative Potential: Facilitates a new way of collaborating where AI can assist in tasks traditionally done by team members, or help in onboarding new developers by guiding them through project structures and operations.

Unity 6.2 is set to introduce new built-in AI tools, including the previous Unity Muse (for generative AI capabilities like texture and animation generation) and Unity Sentis (for running neural networks in Unity runtime). As Unity 6.2 is not yet fully released, this comparison is based on publicly available information and anticipated functionalities:

• Focus:

  • MCP Unity: Primarily focuses on Editor automation and interaction. It allows external AI (like LLM-based coding assistants) to control and query the Unity Editor itself to manipulate scenes, assets, and project settings. It's about augmenting the developer's workflow within the Editor.
  • Unity 6.2 AI:
    • Aims at in-Editor content creation (generating textures, sprites, animations, behaviors, scripts) and AI-powered assistance for common tasks, directly integrated into the Unity Editor interface.
    • A fine-tuned model to ask any question about Unity's documentation and API structure, with customized examples more accurate to Unity's environment.
    • Adds the functionality to run AI model inference, allowing developers to deploy and run pre-trained neural networks within your game or application for features like NPC behavior, image recognition, etc.

• Use Cases:

  • MCP Unity: "Create a new 3D object, name it 'Player', add a Rigidbody, and set its mass to 10." "Run all Play Mode tests." "Ask to fix the error on the console log." "Execute the custom menu item 'Prepare build for iOS' and fix any errors that may occur."
  • Unity 6.2 AI: "Generate a sci-fi texture for this material." "Update all trees position in the scene to be placed inside of terrain zones tagged with 'forest'." "Create a walking animation for this character." "Generate 2D sprites to complete the character." "Ask details about the error on the console log."

• Complementary, Not Mutually Exclusive: MCP Unity and Unity's native AI tools can be seen as complementary. You might use MCP Unity with your AI coding assistant to set up a scene or batch-modify assets, and then use Unity AI tools to generate a specific texture, or to create animations, or 2D sprites for one of those assets. MCP Unity provides a flexible, protocol-based way to interact with the Editor, which can be powerful for developers who want to integrate with a broader range of external AI services or build custom automation workflows.

MCP Unity is designed to work with any AI assistant or development environment that can act as an MCP client. The ecosystem is growing, but current known integrations or compatible platforms include:

• Windsurf
• Cursor
• GitHub Copilot
• Claude Desktop

Yes, absolutely! One of the significant benefits of the MCP Unity architecture is its extensibility.

• In Unity (C#): You can create new C# classes that inherit from McpToolBase (or a similar base for resources) to expose custom Unity Editor functionality. These tools would then be registered in McpUnityServer.cs. For example, you could write a tool to automate a specific asset import pipeline unique to your project.
• In Node.js Server (TypeScript): You would then define the corresponding TypeScript tool handler in the Server/src/tools/ directory, including its Zod schema for inputs/outputs, and register it in Server/src/index.ts. This Node.js part will forward the request to your new C# tool in Unity.

This allows you to tailor the AI's capabilities to the specific needs and workflows of your game or application.

Yes, MCP Unity is an open-source project distributed under the MIT License. You are free to use, modify, and distribute it according to the license terms.

• 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)

• 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

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