MCP Unity Editor (Game Engine)

1# MCP Unity Editor (Game Engine)
2 
3[![](https://badge.mcpx.dev?status=on 'MCP Enabled')](https://modelcontextprotocol.io/introduction)
4[![](https://img.shields.io/badge/Unity-000000?style=flat&logo=unity&logoColor=white 'Unity')](https://unity.com/releases/editor/archive)
5[![](https://img.shields.io/badge/Node.js-339933?style=flat&logo=nodedotjs&logoColor=white 'Node.js')](https://nodejs.org/en/download/)
6[![](https://img.shields.io/github/stars/CoderGamester/mcp-unity 'Stars')](https://github.com/CoderGamester/mcp-unity/stargazers)
7[![](https://img.shields.io/github/last-commit/CoderGamester/mcp-unity 'Last Commit')](https://github.com/CoderGamester/mcp-unity/commits/main)
8[![](https://img.shields.io/badge/License-MIT-red.svg 'MIT License')](https://opensource.org/licenses/MIT)
9 
10| [🇺🇸English](README.md) | [🇨🇳简体中文](README_zh-CN.md) | [🇯🇵日本語](README-ja.md) |
11|----------------------|---------------------------------|----------------------|
12 
13```        
14                              ,/(/.   *(/,                                  
15                          */(((((/.   *((((((*.                             
16                     .*((((((((((/.   *((((((((((/.                         
17                 ./((((((((((((((/    *((((((((((((((/,                     
18             ,/(((((((((((((/*.           */(((((((((((((/*.                
19            ,%%#((/((((((*                    ,/(((((/(#&@@(                
20            ,%%##%%##((((((/*.             ,/((((/(#&@@@@@@(                
21            ,%%######%%##((/(((/*.    .*/(((//(%@@@@@@@@@@@(                
22            ,%%####%#(%%#%%##((/((((((((//#&@@@@@@&@@@@@@@@(                
23            ,%%####%(    /#%#%%%##(//(#@@@@@@@%,   #@@@@@@@(                
24            ,%%####%(        *#%###%@@@@@@(        #@@@@@@@(                
25            ,%%####%(           #%#%@@@@,          #@@@@@@@(                
26            ,%%##%%%(           #%#%@@@@,          #@@@@@@@(                
27            ,%%%#*              #%#%@@@@,             *%@@@(                
28            .,      ,/##*.      #%#%@@@@,     ./&@#*      *`                
29                ,/#%#####%%#/,  #%#%@@@@, ,/&@@@@@@@@@&\.                    
30                 `*#########%%%%###%@@@@@@@@@@@@@@@@@@&*´                   
31                    `*%%###########%@@@@@@@@@@@@@@&*´                        
32                        `*%%%######%@@@@@@@@@@&*´                            
33                            `*#%%##%@@@@@&*´                                 
34                               `*%#%@&*´                                     
35                                                       
36     ███╗   ███╗ ██████╗██████╗         ██╗   ██╗███╗   ██╗██╗████████╗██╗   ██╗
37     ████╗ ████║██╔════╝██╔══██╗        ██║   ██║████╗  ██║██║╚══██╔══╝╚██╗ ██╔╝
38     ██╔████╔██║██║     ██████╔╝        ██║   ██║██╔██╗ ██║██║   ██║    ╚████╔╝ 
39     ██║╚██╔╝██║██║     ██╔═══╝         ██║   ██║██║╚██╗██║██║   ██║     ╚██╔╝  
40     ██║ ╚═╝ ██║╚██████╗██║             ╚██████╔╝██║ ╚████║██║   ██║      ██║   
41     ╚═╝     ╚═╝ ╚═════╝╚═╝              ╚═════╝ ╚═╝  ╚═══╝╚═╝   ╚═╝      ╚═╝   
42```       
43 
44MCP 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 Cursor, Windsurf, Claude Code, Codex CLI, GitHub Copilot, and Google Antigravity to execute operations within the Unity Editor.
45 
46## Features
47 
48### IDE Integration - Package Cache Access
49 
50MCP Unity provides automatic integration with VSCode-like IDEs (Visual Studio Code, Cursor, Windsurf, Google Antigravity) by adding the Unity `Library/PackedCache` folder to your workspace. This feature:
51 
52- Improves code intelligence for Unity packages
53- Enables better autocompletion and type information for Unity packages
54- Helps AI coding assistants understand your project's dependencies
55 
56### MCP Server Tools
57 
58The following tools are available for manipulating and querying Unity scenes and GameObjects via MCP:
59 
60- `execute_menu_item`: Executes Unity menu items (functions tagged with the MenuItem attribute)
61  > **Example prompt:** "Execute the menu item 'GameObject/Create Empty' to create a new empty GameObject"
62 
63- `select_gameobject`: Selects game objects in the Unity hierarchy by path or instance ID
64  > **Example prompt:** "Select the Main Camera object in my scene"
65 
66- `update_gameobject`: Updates a GameObject's core properties (name, tag, layer, active/static state), or creates the GameObject if it does not exist
67  > **Example prompt:** "Set the Player object's tag to 'Enemy' and make it inactive"
68 
69- `update_component`: Updates component fields on a GameObject or adds it to the GameObject if it does not contain the component
70  > **Example prompt:** "Add a Rigidbody component to the Player object and set its mass to 5"
71 
72- `add_package`: Installs new packages in the Unity Package Manager
73  > **Example prompt:** "Add the TextMeshPro package to my project"
74 
75- `run_tests`: Runs tests using the Unity Test Runner
76  > **Example prompt:** "Run all the EditMode tests in my project"
77 
78- `send_console_log`: Send a console log to Unity
79  > **Example prompt:** "Send a console log to Unity Editor"
80 
81- `add_asset_to_scene`: Adds an asset from the AssetDatabase to the Unity scene
82  > **Example prompt:** "Add the Player prefab from my project to the current scene"
83 
84- `create_prefab`: Creates a prefab with optional MonoBehaviour script and serialized field values
85  > **Example prompt:** "Create a prefab named 'Player' from the 'PlayerController' script"
86 
87- `create_scene`: Creates a new scene and saves it to the specified path
88  > **Example prompt:** "Create a new scene called 'Level1' in the Scenes folder"
89 
90- `load_scene`: Loads a scene by path or name, with optional additive loading
91  > **Example prompt:** "Load the MainMenu scene"
92 
93- `delete_scene`: Deletes a scene by path or name and removes it from Build Settings
94  > **Example prompt:** "Delete the old TestScene from my project"
95 
96- `get_gameobject`: Gets detailed information about a specific GameObject including all components
97  > **Example prompt:** "Get the details of the Player GameObject"
98 
99- `get_console_logs`: Retrieves logs from the Unity console with pagination support
100  > **Example prompt:** "Show me the last 20 error logs from the Unity console"
101 
102- `recompile_scripts`: Recompiles all scripts in the Unity project
103  > **Example prompt:** "Recompile scripts in my Unity project"
104 
105- `save_scene`: Saves the current active scene, with optional Save As to a new path
106  > **Example prompt:** "Save the current scene" or "Save the scene as 'Assets/Scenes/Level2.unity'"
107 
108- `get_scene_info`: Gets information about the active scene including name, path, dirty state, and all loaded scenes
109  > **Example prompt:** "What scenes are currently loaded in my project?"
110 
111- `unload_scene`: Unloads a scene from the hierarchy (does not delete the scene asset)
112  > **Example prompt:** "Unload the UI scene from the hierarchy"
113 
114- `duplicate_gameobject`: Duplicates a GameObject in the scene with optional renaming and reparenting
115  > **Example prompt:** "Duplicate the Enemy prefab 5 times and rename them Enemy_1 through Enemy_5"
116 
117- `delete_gameobject`: Deletes a GameObject from the scene
118  > **Example prompt:** "Delete the old Player object from the scene"
119 
120- `reparent_gameobject`: Changes the parent of a GameObject in the hierarchy
121  > **Example prompt:** "Move the HealthBar object to be a child of the UI Canvas"
122 
123- `move_gameobject`: Moves a GameObject to a new position (local or world space)
124  > **Example prompt:** "Move the Player object to position (10, 0, 5) in world space"
125 
126- `rotate_gameobject`: Rotates a GameObject to a new rotation (local or world space, Euler angles or quaternion)
127  > **Example prompt:** "Rotate the Camera 45 degrees on the Y axis"
128 
129- `scale_gameobject`: Scales a GameObject to a new local scale
130  > **Example prompt:** "Scale the Enemy object to twice its size"
131 
132- `set_transform`: Sets position, rotation, and scale of a GameObject in a single operation
133  > **Example prompt:** "Set the Cube's position to (0, 5, 0), rotation to (0, 90, 0), and scale to (2, 2, 2)"
134 
135- `create_material`: Creates a new material with specified shader and saves it to the project
136  > **Example prompt:** "Create a red material called 'EnemyMaterial' using the URP Lit shader"
137 
138- `assign_material`: Assigns a material to a GameObject's Renderer component
139  > **Example prompt:** "Assign the 'EnemyMaterial' to the Enemy GameObject"
140 
141- `modify_material`: Modifies properties of an existing material (colors, floats, textures)
142  > **Example prompt:** "Change the color of 'EnemyMaterial' to blue and set metallic to 0.8"
143 
144- `get_material_info`: Gets detailed information about a material including shader and all properties
145  > **Example prompt:** "Show me all the properties of the 'PlayerMaterial'"
146 
147- `batch_execute`: Executes multiple tool operations in a single batch request, reducing round-trips and enabling atomic operations with optional rollback on failure
148  > **Example prompt:** "Create 10 empty GameObjects named Enemy_1 through Enemy_10 in a single batch operation"
149 
150### MCP Server Resources
151 
152- `unity://menu-items`: Retrieves a list of all available menu items in the Unity Editor to facilitate `execute_menu_item` tool
153  > **Example prompt:** "Show me all available menu items related to GameObject creation"
154 
155- `unity://scenes-hierarchy`: Retrieves a list of all game objects in the current Unity scene hierarchy
156  > **Example prompt:** "Show me the current scenes hierarchy structure"
157 
158- `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
159  > **Example prompt:** "Get me detailed information about the Player GameObject"
160 
161- `unity://logs`: Retrieves a list of all logs from the Unity console
162  > **Example prompt:** "Show me the recent error messages from the Unity console"
163 
164- `unity://packages`: Retrieves information about installed and available packages from the Unity Package Manager
165  > **Example prompt:** "List all the packages currently installed in my Unity project"
166 
167- `unity://assets`: Retrieves information about assets in the Unity Asset Database
168  > **Example prompt:** "Find all texture assets in my project"
169 
170- `unity://tests/{testMode}`: Retrieves information about tests in the Unity Test Runner
171  > **Example prompt:** "List all available tests in my Unity project"
172 
173## Requirements
174- Unity 6 or later - to [install the server](#install-server)
175- Node.js 18 or later - to [start the server](#start-server)
176- npm 9 or later - to [debug the server](#debug-server)
177 
178> [!NOTE]
179> **Project Paths with Spaces**
180>
181> MCP Unity supports project paths containing spaces. However, if you experience connection issues, try moving your project to a path without spaces as a troubleshooting step.
182>
183> **Examples:**
184> -   ✅ **Recommended:** `C:\Users\YourUser\Documents\UnityProjects\MyAwesomeGame`
185> -   ✅ **Supported:** `C:\Users\Your User\Documents\Unity Projects\My Awesome Game`
186 
187## <a name="install-server"></a>Installation
188 
189Installing this MCP Unity Server is a multi-step process:
190 
191### Step 1: Install Node.js 
192> To run MCP Unity server, you'll need to have Node.js 18 or later installed on your computer:
193 
194![node](docs/node.jpg)
195 
196<details>
197<summary><span style="font-size: 1.1em; font-weight: bold;">Windows</span></summary>
198 
1991. Visit the [Node.js download page](https://nodejs.org/en/download/)
2002. Download the Windows Installer (.msi) for the LTS version (recommended)
2013. Run the installer and follow the installation wizard
2024. Verify the installation by opening PowerShell and running:
203   ```bash
204   node --version
205   ```
206</details>
207 
208<details>
209<summary><span style="font-size: 1.1em; font-weight: bold;">macOS</span></summary>
210 
2111. Visit the [Node.js download page](https://nodejs.org/en/download/)
2122. Download the macOS Installer (.pkg) for the LTS version (recommended)
2133. Run the installer and follow the installation wizard
2144. Alternatively, if you have Homebrew installed, you can run:
215   ```bash
216   brew install node@18
217   ```
2185. Verify the installation by opening Terminal and running:
219   ```bash
220   node --version
221   ```
222</details>
223 
224### Step 2: Install Unity MCP Server package via Unity Package Manager
2251. Open the Unity Package Manager (Window > Package Manager)
2262. Click the "+" button in the top-left corner
2273. Select "Add package from git URL..."
2284. Enter: `https://github.com/CoderGamester/mcp-unity.git`
2295. Click "Add"
230 
231![package manager](https://github.com/user-attachments/assets/a72bfca4-ae52-48e7-a876-e99c701b0497)
232 
233### Step 3: Configure AI LLM Client
234 
235<details open>
236<summary><span style="font-size: 1.1em; font-weight: bold;">Option 1: Configure using Unity Editor</span></summary>
237 
2381. Open the Unity Editor
2392. Navigate to Tools > MCP Unity > Server Window
2403. Click on the "Configure" button for your AI LLM client as shown in the image below
241 
242![image](docs/configure.jpg)
243 
2444. Confirm the configuration installation with the given popup
245 
246![image](https://github.com/user-attachments/assets/b1f05d33-3694-4256-a57b-8556005021ba)
247 
248</details>
249 
250<details>
251<summary><span style="font-size: 1.1em; font-weight: bold;">Option 2: Configure Manually</span></summary>
252 
253Open the MCP configuration file of your AI client and add the MCP Unity server configuration:
254 
255> 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).
256 
257**For JSON-based clients** (Cursor, Windsurf, Claude Code, GitHub Copilot, etc.):
258 
259```json
260{
261   "mcpServers": {
262       "mcp-unity": {
263          "command": "node",
264          "args": [
265             "ABSOLUTE/PATH/TO/mcp-unity/Server~/build/index.js"
266          ]
267       }
268   }
269}
270```
271 
272**For Codex CLI** (`~/.codex/config.toml`):
273 
274```toml
275[mcp_servers.mcp-unity]
276command = "node"
277args = ["ABSOLUTE/PATH/TO/mcp-unity/Server~/build/index.js"]
278```
279 
280</details>
281 
282## <a name="start-server"></a>Start Unity Editor MCP Server
2831. Open the Unity Editor
2842. Navigate to Tools > MCP Unity > Server Window
2853. Click "Start Server" to start the WebSocket server
2864. Open your AI Coding IDE (e.g. Cursor, Windsurf, Claude Code, Codex CLI, GitHub Copilot, Google Antigravity, etc.) and start executing Unity tools
287   
288![connect](https://github.com/user-attachments/assets/2e266a8b-8ba3-4902-b585-b220b11ab9a2)
289 
290> When the AI client connects to the WebSocket server, it will automatically show in the green box in the window
291 
292## Optional: Set WebSocket Port
293By default, the WebSocket server runs on port '8090'. You can change this port in two ways:
294 
2951. Open the Unity Editor
2962. Navigate to Tools > MCP Unity > Server Window
2973. Change the "WebSocket Port" value to your desired port number
2984. Unity will setup the system environment variable UNITY_PORT to the new port number
2995. Restart the Node.js server
3006. Click again on "Start Server" to reconnect the Unity Editor web socket to the Node.js MCP Server
301 
302## Optional: Set Timeout
303 
304By default, the timeout between the MCP server and the WebSocket is 10 seconds.
305You can change depending on the OS you are using:
306 
3071. Open the Unity Editor
3082. Navigate to Tools > MCP Unity > Server Window
3093. Change the "Request Timeout (seconds)" value to your desired timeout seconds
3104. Unity will setup the system environment variable UNITY_REQUEST_TIMEOUT to the new timeout value
3115. Restart the Node.js server
3126. Click again on "Start Server" to reconnect the Unity Editor web socket to the Node.js MCP Server
313 
314> [!TIP]  
315> The timeout between your AI Coding IDE (e.g., Claude Desktop, Cursor IDE, Windsurf IDE) and the MCP Server depends on the IDE.
316 
317## Optional: Allow Remote MCP Bridge Connections
318 
319By default, the WebSocket server binds to 'localhost'. To allow MCP bridge connections from other machines:
320 
3211. Open the Unity Editor
3222. Navigate to Tools > MCP Unity > Server Window
3233. Enable the "Allow Remote Connections" checkbox
3244. Unity will bind the WebSocket server to '0.0.0.0' (all interfaces)
3255. Restart the Node.js server to apply the new host configuration
3266. 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`
327 
328## <a name="debug-server"></a>Debugging the Server
329 
330<details>
331<summary><span style="font-size: 1.1em; font-weight: bold;">Building the Node.js Server</span></summary>
332 
333The MCP Unity server is built using Node.js . It requires to compile the TypeScript code to JavaScript in the `build` directory.
334In case of issues, you can force install it in by:
335 
3361. Open the Unity Editor
3372. Navigate to Tools > MCP Unity > Server Window
3383. Click on "Force Install Server" button
339 
340![install](docs/install.jpg)
341 
342If you want to build it manually, you can follow these steps:
343 
3441. Open a terminal/PowerShell/Command Prompt
345 
3462. Navigate to the Server directory:
347   ```bash
348   cd ABSOLUTE/PATH/TO/mcp-unity/Server~
349   ```
350 
3513. Install dependencies:
352   ```bash
353   npm install
354   ```
355 
3564. Build the server:
357   ```bash
358   npm run build
359   ```
360 
3615. Run the server:
362   ```bash
363   node build/index.js
364   ```
365 
366</details>
367   
368<details>
369<summary><span style="font-size: 1.1em; font-weight: bold;">Debugging with MCP Inspector</span></summary>
370 
371Debug the server with [@modelcontextprotocol/inspector](https://github.com/modelcontextprotocol/inspector):
372   - Powershell
373   ```powershell
374   npx @modelcontextprotocol/inspector node Server~/build/index.js
375   ```
376   - Command Prompt/Terminal
377   ```cmd
378   npx @modelcontextprotocol/inspector node Server~/build/index.js
379   ```
380 
381Don't forget to shutdown the server with `Ctrl + C` before closing the terminal or debugging it with the [MCP Inspector](https://github.com/modelcontextprotocol/inspector).
382 
383</details>
384 
385<details>
386<summary><span style="font-size: 1.1em; font-weight: bold;">Enable Console Logs</span></summary>
387 
3881. Enable logging on your terminal or into a log.txt file:
389   - Powershell
390   ```powershell
391   $env:LOGGING = "true"
392   $env:LOGGING_FILE = "true"
393   ```
394   - Command Prompt/Terminal
395   ```cmd
396   set LOGGING=true
397   set LOGGING_FILE=true
398   ```
399 
400</details>
401 
402## Frequently Asked Questions
403 
404<details>
405<summary><span style="font-size: 1.1em; font-weight: bold;">What is MCP Unity?</span></summary>
406 
407MCP Unity is a powerful bridge that connects your Unity Editor environment to AI assistants LLM tools using the Model Context Protocol (MCP).
408 
409In essence, MCP Unity:
410-   Exposes Unity Editor functionalities (like creating objects, modifying components, running tests, etc.) as "tools" and "resources" that an AI can understand and use.
411-   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.
412-   Enables you to use natural language prompts with your AI assistant to perform complex tasks within your Unity project, significantly speeding up development workflows.
413 
414</details>
415 
416<details>
417<summary><span style="font-size: 1.1em; font-weight: bold;">Why use MCP Unity?</span></summary>
418 
419MCP Unity offers several compelling advantages for developers, artists, and project managers:
420 
421-   **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.
422-   **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.
423-   **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.
424-   **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.
425-   **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.
426-   **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.
427 
428</details>
429 
430<details>
431<summary><span style="font-size: 1.1em; font-weight: bold;">How does MCP Unity compare with the upcoming Unity 6.2 AI features?</span></summary>
432 
433Unity 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:
434 
435-   **Focus:**
436    -   **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.
437    -   **Unity 6.2 AI:**
438        -   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.
439        -   A fine-tuned model to ask any question about Unity's documentation and API structure, with customized examples more accurate to Unity's environment.
440        -   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.
441 
442-   **Use Cases:**
443    -   **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."
444    -   **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."
445 
446-   **Complementary, Not Mutually Exclusive:**
447    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.
448 
449</details>
450 
451<details>
452<summary><span style="font-size: 1.1em; font-weight: bold;">What MCP hosts and IDEs currently support MCP Unity?</span></summary>
453 
454MCP 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:
455-  Cursor
456-  Windsurf
457-  Claude Desktop
458-  Claude Code
459-  Codex CLI
460-  GitHub Copilot
461-  Google Antigravity
462 
463</details>
464 
465<details>
466<summary><span style="font-size: 1.1em; font-weight: bold;">Can I extend MCP Unity with custom tools for my project?</span></summary>
467 
468Yes, absolutely! One of the significant benefits of the MCP Unity architecture is its extensibility.
469-   **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.
470-   **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.
471 
472This allows you to tailor the AI's capabilities to the specific needs and workflows of your game or application.
473 
474</details>
475 
476<details>
477<summary><span style="font-size: 1.1em; font-weight: bold;">Is MCP Unity free to use?</span></summary>
478 
479Yes, 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.
480 
481</details>
482 
483<details>
484<summary><span style="font-size: 1.1em; font-weight: bold;">Why am I unable to connect to MCP Unity?</span></summary>
485 
486- Ensure the WebSocket server is running (check the Server Window in Unity)
487- Send a console log message from MCP client to force a reconnection between MCP client and Unity server
488- Change the port number in the Unity Editor MCP Server window. (Tools > MCP Unity > Server Window)
489 
490</details>
491 
492<details>
493<summary><span style="font-size: 1.1em; font-weight: bold;">Why won't the MCP Unity server start?</span></summary>
494 
495- Check the Unity Console for error messages
496- Ensure Node.js is properly installed and accessible in your PATH
497- Verify that all dependencies are installed in the Server directory
498 
499</details>
500 
501<details>
502<summary><span style="font-size: 1.1em; font-weight: bold;">Why do I get a connection failed error when running Play Mode tests?</span></summary>
503 
504The `run_tests` tool returns the following response:
505```
506Error:
507Connection failed: Unknown error
508```
509 
510This 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"**.
511 
512</details>
513 
514## Troubleshooting: WSL2 (Windows 11) networking
515 
516When running the MCP (Node.js) server inside WSL2 while Unity runs on Windows 11, connecting to `ws://localhost:8090/McpUnity` may fail with `ECONNREFUSED`.
517 
518Cause: WSL2 and Windows have separate network namespaces — `localhost` inside WSL2 does not point to the Windows host. By default, Unity listens on `localhost:8090`.
519 
520### Solution 1 — Enable WSL2 Mirrored mode networking (preferred)
521- Windows 11: Settings → System → For developers → WSL → Enable “Mirrored mode networking”.
522- Or via `.wslconfig` (then run `wsl --shutdown` and reopen WSL):
523 
524```ini
525[wsl2]
526networkingMode=mirrored
527```
528 
529After enabling, `localhost` is shared between Windows and WSL2, so the default config (`localhost:8090`) works.
530 
531### Solution 2 — Point the Node client to the Windows host
532Set in your WSL shell before starting the MCP client:
533 
534```bash
535# Use the Windows host IP detected from resolv.conf
536export UNITY_HOST=$(grep -m1 nameserver /etc/resolv.conf | awk '{print $2}')
537```
538 
539With this, `Server~/src/unity/mcpUnity.ts` will connect to `ws://$UNITY_HOST:8090/McpUnity` instead of `localhost` (it reads `UNITY_HOST`, and may also honor a `Host` in `ProjectSettings/McpUnitySettings.json` if present).
540 
541### Solution 3 — Allow remote connections from Unity
542- Unity: Tools → MCP Unity → Server Window → enable “Allow Remote Connections” (Unity binds to `0.0.0.0`).
543- Ensure Windows Firewall allows inbound TCP on your configured port (default 8090).
544- From WSL2, connect to the Windows host IP (see Solution 2) or to `localhost` if mirrored mode is enabled.
545 
546> [!NOTE]
547> Default port is `8090`. You can change it in the Unity Server Window (Tools → MCP Unity → Server Window). The value maps to `McpUnitySettings` and is persisted in `ProjectSettings/McpUnitySettings.json`.
548 
549#### Validate connectivity
550 
551```bash
552npm i -g wscat
553# After enabling mirrored networking
554wscat -c ws://localhost:8090/McpUnity
555# Or using the Windows host IP
556wscat -c ws://$UNITY_HOST:8090/McpUnity
557```
558 
559## Running Tests
560 
561### C# Tests (Unity)
562Run tests using Unity's Test Runner:
5631. Open Unity Editor
5642. Navigate to Window > General > Test Runner
5653. Select "EditMode" tab
5664. Click "Run All" to execute all tests
567 
568### TypeScript Tests (Server)
569Run tests using Jest:
570```bash
571cd Server~
572npm test
573```
574 
575To run tests in watch mode:
576```bash
577npm run test:watch
578```
579 
580## Support & Feedback
581 
582If you have any questions or need support, please open an [issue](https://github.com/CoderGamester/mcp-unity/issues) on this repository or alternative you can reach out on:
583- Linkedin: [![](https://img.shields.io/badge/LinkedIn-0077B5?style=flat&logo=linkedin&logoColor=white 'LinkedIn')](https://www.linkedin.com/in/miguel-tomas/)
584- Discord: gamester7178
585- Email: game.gamester@gmail.com
586 
587## Contributing
588 
589Contributions are welcome! Please feel free to submit a Pull Request or open an Issue with your request.
590 
591**Commit your changes** following the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) format.
592 
593## License
594 
595This project is under [MIT License](LICENSE.md)
596 
597## Acknowledgements
598 
599- [Model Context Protocol](https://modelcontextprotocol.io)
600- [Unity Technologies](https://unity.com)
601- [Node.js](https://nodejs.org)
602- [WebSocket-Sharp](https://github.com/sta/websocket-sharp)
603