Skip to content
Back to search

mcp-unity

Model Context Protocol (MCP) plugin to connect with Unity Editor — designed for Cursor, Claude Code, Codex, Windsurf and other IDEs

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/codergamester--mcp-unity/badge.svg)](/listings/codergamester--mcp-unity)

HTML

<a href="/listings/codergamester--mcp-unity"><img src="/api/listings/codergamester--mcp-unity/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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:

<details> <summary><span style="font-size: 1.1em; font-weight: bold;">Windows</span></summary>

1. Visit the [Node.js download page](https://nodejs.org/en/download/) 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

</details>

<details> <summary><span style="font-size: 1.1em; font-weight: bold;">macOS</span></summary>

1. Visit the [Node.js download page](https://nodejs.org/en/download/) 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

</details>

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

<details open> <summary><span style="font-size: 1.1em; font-weight: bold;">Option 1: Configure using Unity Editor</span></summary>

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

> **Global vs. Project configuration:** > - **Configure \[Client\]** — writes to your global user config file (e.g. `~/.claude.json`). Uses an absolute path. Applies to all projects on your machine. Best for personal, single-developer setups. > - **Configure \[Client\] (Project)** — writes to a `.mcp.json` file (or equivalent) in the Unity project root. Uses a relative path, so it works across machines. Intended to be committed to git and shared with the team. Best for collaborative projects or when you want the config to travel with the project. > > If in doubt, prefer the **(Project)** variant — the relative path is more portable and won't break if you move your project folder.

4. Confirm the configuration installation with the given popup

</details>

<details> <summary><span style="font-size: 1.1em; font-weight: bold;">Option 2: Configure Manually</span></summary>

Open the MCP configuration file of your AI client and add the MCP Unity server configuration:

> 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). > > For configs that live inside the Unity project tree and get committed to git (e.g. `<project>/.vscode/mcp.json`, `<project>/opencode.json`, `<project>/.cursor/mcp.json`, `<project>/.mcp.json`, `<project>/.codex/config.toml`), prefer a project-relative path so the same file works across machines. Toggle **"Use relative path"** in the Server Window to switch the copy-paste snippet between absolute and project-relative forms. The **Configure GitHub Copilot**, **Configure OpenCode**, **Configure Cursor (Project)**, **Configure Claude Code (Project)**, and **Configure Codex CLI (Project)** buttons already emit relative paths automatically. > > Project-local buttons (Cursor / Claude Code / Codex CLI) write the MCP server entry into the Unity project directory instead of your global user config, so other (non-Unity) projects don't see MCP connection-failure warnings. For **Codex CLI (Project)** specifically, you must approve the project trust prompt the first time you run `codex` from the project root, otherwise Codex ignores `<project>/.codex/config.toml`.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 754 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # MCP Unity Editor (Game Engine)
  2. [![](https://badge.mcpx.dev?status=on 'MCP Enabled')](https://modelcontextprotocol.io/introduction)
  3. [![](https://img.shields.io/badge/Unity-000000?style=flat&logo=unity&logoColor=white 'Unity')](https://unity.com/releases/editor/archive)
  4. [![](https://img.shields.io/badge/Node.js-339933?style=flat&logo=nodedotjs&logoColor=white 'Node.js')](https://nodejs.org/en/download/)
  5. [![](https://img.shields.io/github/stars/CoderGamester/mcp-unity 'Stars')](https://github.com/CoderGamester/mcp-unity/stargazers)
  6. [![](https://img.shields.io/github/last-commit/CoderGamester/mcp-unity 'Last Commit')](https://github.com/CoderGamester/mcp-unity/commits/main)
  7. [![](https://img.shields.io/badge/License-MIT-red.svg 'MIT License')](https://opensource.org/licenses/MIT)
  8. | [🇺🇸English](README.md) | [🇨🇳简体中文](README_zh-CN.md) | [🇯🇵日本語](README-ja.md) |
  9. |----------------------|---------------------------------|----------------------|
  10. ```
  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. 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 Cursor, Windsurf, Claude Code, Codex CLI, GitHub Copilot, Google Antigravity, and OpenCode to execute operations within the Unity Editor.
  40. ## Features
  41. ### IDE Integration - Package Cache Access
  42. MCP 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:
  43. - Improves code intelligence for Unity packages
  44. - Enables better autocompletion and type information for Unity packages
  45. - Helps AI coding assistants understand your project's dependencies
  46. ### MCP Server Tools
  47. The following tools are available for manipulating and querying Unity scenes and GameObjects via MCP:
  48. - `execute_menu_item`: Executes Unity menu items (functions tagged with the MenuItem attribute)
  49. > **Example prompt:** "Execute the menu item 'GameObject/Create Empty' to create a new empty GameObject"
  50. - `select_gameobject`: Selects game objects in the Unity hierarchy by path or instance ID
  51. > **Example prompt:** "Select the Main Camera object in my scene"
  52. - `update_gameobject`: Updates a GameObject's core properties (name, tag, layer, active/static state), or creates the GameObject if it does not exist
  53. > **Example prompt:** "Set the Player object's tag to 'Enemy' and make it inactive"
  54. - `update_component`: Updates component fields on a GameObject or adds it to the GameObject if it does not contain the component
  55. > **Example prompt:** "Add a Rigidbody component to the Player object and set its mass to 5"
  56. - `add_package`: Installs new packages in the Unity Package Manager
  57. > **Example prompt:** "Add the TextMeshPro package to my project"
  58. - `run_tests`: Runs tests using the Unity Test Runner
  59. > **Example prompt:** "Run all the EditMode tests in my project"
  60. - `send_console_log`: Send a console log to Unity
  61. > **Example prompt:** "Send a console log to Unity Editor"
  62. - `add_asset_to_scene`: Adds an asset from the AssetDatabase to the Unity scene
  63. > **Example prompt:** "Add the Player prefab from my project to the current scene"
  64. - `create_prefab`: Creates a prefab with optional MonoBehaviour script and serialized field values
  65. > **Example prompt:** "Create a prefab named 'Player' from the 'PlayerController' script"
  66. - `create_scene`: Creates a new scene and saves it to the specified path
  67. > **Example prompt:** "Create a new scene called 'Level1' in the Scenes folder"
  68. - `load_scene`: Loads a scene by path or name, with optional additive loading
  69. > **Example prompt:** "Load the MainMenu scene"
  70. - `delete_scene`: Deletes a scene by path or name and removes it from Build Settings
  71. > **Example prompt:** "Delete the old TestScene from my project"
  72. - `get_gameobject`: Gets detailed information about a specific GameObject including all components
  73. > **Example prompt:** "Get the details of the Player GameObject"
  74. - `get_console_logs`: Retrieves logs from the Unity console with pagination support
  75. > **Example prompt:** "Show me the last 20 error logs from the Unity console"
  76. - `recompile_scripts`: Recompiles all scripts in the Unity project
  77. > **Example prompt:** "Recompile scripts in my Unity project"
  78. - `save_scene`: Saves the current active scene, with optional Save As to a new path
  79. > **Example prompt:** "Save the current scene" or "Save the scene as 'Assets/Scenes/Level2.unity'"
  80. - `get_scene_info`: Gets information about the active scene including name, path, dirty state, and all loaded scenes
  81. > **Example prompt:** "What scenes are currently loaded in my project?"
  82. - `unload_scene`: Unloads a scene from the hierarchy (does not delete the scene asset)
  83. > **Example prompt:** "Unload the UI scene from the hierarchy"
  84. - `duplicate_gameobject`: Duplicates a GameObject in the scene with optional renaming and reparenting
  85. > **Example prompt:** "Duplicate the Enemy prefab 5 times and rename them Enemy_1 through Enemy_5"
  86. - `delete_gameobject`: Deletes a GameObject from the scene
  87. > **Example prompt:** "Delete the old Player object from the scene"
  88. - `reparent_gameobject`: Changes the parent of a GameObject in the hierarchy
  89. > **Example prompt:** "Move the HealthBar object to be a child of the UI Canvas"
  90. - `move_gameobject`: Moves a GameObject to a new position (local or world space)
  91. > **Example prompt:** "Move the Player object to position (10, 0, 5) in world space"
  92. - `rotate_gameobject`: Rotates a GameObject to a new rotation (local or world space, Euler angles or quaternion)
  93. > **Example prompt:** "Rotate the Camera 45 degrees on the Y axis"
  94. - `scale_gameobject`: Scales a GameObject to a new local scale
  95. > **Example prompt:** "Scale the Enemy object to twice its size"
  96. - `set_transform`: Sets position, rotation, and scale of a GameObject in a single operation
  97. > **Example prompt:** "Set the Cube's position to (0, 5, 0), rotation to (0, 90, 0), and scale to (2, 2, 2)"
  98. - `create_material`: Creates a new material with specified shader and saves it to the project
  99. > **Example prompt:** "Create a red material called 'EnemyMaterial' using the URP Lit shader"
  100. - `assign_material`: Assigns a material to a GameObject's Renderer component
  101. > **Example prompt:** "Assign the 'EnemyMaterial' to the Enemy GameObject"
  102. - `modify_material`: Modifies properties of an existing material (colors, floats, textures)
  103. > **Example prompt:** "Change the color of 'EnemyMaterial' to blue and set metallic to 0.8"
  104. - `get_material_info`: Gets detailed information about a material including shader and all properties
  105. > **Example prompt:** "Show me all the properties of the 'PlayerMaterial'"
  106. - `batch_execute`: Executes multiple tool operations in a single batch request, reducing round-trips and enabling atomic operations with optional rollback on failure
  107. > **Example prompt:** "Create 10 empty GameObjects named Enemy_1 through Enemy_10 in a single batch operation"
  108. ### MCP App tools
  109. - `show_unity_dashboard`: Opens the Unity dashboard MCP App in VS Code (requires VS Code 1.109+)
  110. > **Example prompt:** "Open the Unity dashboard app"
  111. - `get_play_mode_status`: Gets Unity play mode status (isPlaying, isPaused)
  112. > **Example prompt:** "Is Unity in play mode?"
  113. - `set_play_mode_status`: Controls Unity play mode with actions: 'play' (start or unpause), 'pause' (toggle pause), 'stop' (exit play mode), 'step' (advance one frame)
  114. > **Example prompt:** "Start Unity play mode" or "Pause the game" or "Step forward one frame"
  115. ### MCP Server Resources
  116. - `unity://menu-items`: Retrieves a list of all available menu items in the Unity Editor to facilitate `execute_menu_item` tool
  117. > **Example prompt:** "Show me all available menu items related to GameObject creation"
  118. - `unity://scenes-hierarchy`: Retrieves a list of all game objects in the current Unity scene hierarchy
  119. > **Example prompt:** "Show me the current scenes hierarchy structure"
  120. - `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
  121. > **Example prompt:** "Get me detailed information about the Player GameObject"
  122. - `unity://logs`: Retrieves a list of all logs from the Unity console
  123. > **Example prompt:** "Show me the recent error messages from the Unity console"
  124. - `unity://packages`: Retrieves information about installed and available packages from the Unity Package Manager
  125. > **Example prompt:** "List all the packages currently installed in my Unity project"
  126. - `unity://assets`: Retrieves information about assets in the Unity Asset Database
  127. > **Example prompt:** "Find all texture assets in my project"
  128. - `unity://tests/{testMode}`: Retrieves information about tests in the Unity Test Runner
  129. > **Example prompt:** "List all available tests in my Unity project"
  130. - `ui://unity-dashboard`: Unity dashboard MCP App UI
  131. > **Example prompt:** "Open the Unity dashboard app"
  132. ### MCP Server Prompts
  133. Prompts are pre-configured templates that provide guided workflows for common Unity tasks. They help AI assistants understand the proper sequence of operations and available tools for specific scenarios.
  134. - `unity_dashboard`: Opens the Unity dashboard MCP app with contextual information about its features
  135. > **Usage:** In your AI assistant, use the prompt "unity_dashboard" to get guided access to the Unity dashboard
  136. - `gameobject_handling_strategy`: Provides a structured workflow for working with GameObjects, including which tools and resources to use
  137. > **Usage:** In your AI assistant, use the prompt "gameobject_handling_strategy" with a GameObject ID, name, or path to get step-by-step guidance
  138. ## Requirements
  139. - Unity 6 or later - to [install the server](#install-server)
  140. - Node.js 18 or later - to [start the server](#start-server)
  141. - npm 9 or later - to [debug the server](#debug-server)
  142. > [!NOTE]
  143. > **Project Paths with Spaces**
  144. >
  145. > 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.
  146. >
  147. > **Examples:**
  148. > - ✅ **Recommended:** `C:\Users\YourUser\Documents\UnityProjects\MyAwesomeGame`
  149. > - ✅ **Supported:** `C:\Users\Your User\Documents\Unity Projects\My Awesome Game`
  150. ## <a name="install-server"></a>Installation
  151. Installing this MCP Unity Server is a multi-step process:
  152. ### Step 1: Install Node.js
  153. > To run MCP Unity server, you'll need to have Node.js 18 or later installed on your computer:
  154. ![node](docs/node.jpg)
  155. <details>
  156. <summary><span style="font-size: 1.1em; font-weight: bold;">Windows</span></summary>
  157. 1. Visit the [Node.js download page](https://nodejs.org/en/download/)
  158. 2. Download the Windows Installer (.msi) for the LTS version (recommended)
  159. 3. Run the installer and follow the installation wizard
  160. 4. Verify the installation by opening PowerShell and running:
  161. ```bash
  162. node --version
  163. ```
  164. </details>
  165. <details>
  166. <summary><span style="font-size: 1.1em; font-weight: bold;">macOS</span></summary>
  167. 1. Visit the [Node.js download page](https://nodejs.org/en/download/)
  168. 2. Download the macOS Installer (.pkg) for the LTS version (recommended)
  169. 3. Run the installer and follow the installation wizard
  170. 4. Alternatively, if you have Homebrew installed, you can run:
  171. ```bash
  172. brew install node@18
  173. ```
  174. 5. Verify the installation by opening Terminal and running:
  175. ```bash
  176. node --version
  177. ```
  178. </details>
  179. ### Step 2: Install Unity MCP Server package via Unity Package Manager
  180. 1. Open the Unity Package Manager (Window > Package Manager)
  181. 2. Click the "+" button in the top-left corner
  182. 3. Select "Add package from git URL..."
  183. 4. Enter: `https://github.com/CoderGamester/mcp-unity.git`
  184. 5. Click "Add"
  185. ![package manager](https://github.com/user-attachments/assets/a72bfca4-ae52-48e7-a876-e99c701b0497)
  186. ### Step 3: Configure AI LLM Client
  187. <details open>
  188. <summary><span style="font-size: 1.1em; font-weight: bold;">Option 1: Configure using Unity Editor</span></summary>
  189. 1. Open the Unity Editor
  190. 2. Navigate to Tools > MCP Unity > Server Window
  191. 3. Click on the "Configure" button for your AI LLM client as shown in the image below
  192. ![image](docs/configure.jpg)
  193. > **Global vs. Project configuration:**
  194. > - **Configure \[Client\]** — writes to your global user config file (e.g. `~/.claude.json`). Uses an absolute path. Applies to all projects on your machine. Best for personal, single-developer setups.
  195. > - **Configure \[Client\] (Project)** — writes to a `.mcp.json` file (or equivalent) in the Unity project root. Uses a relative path, so it works across machines. Intended to be committed to git and shared with the team. Best for collaborative projects or when you want the config to travel with the project.
  196. >
  197. > If in doubt, prefer the **(Project)** variant — the relative path is more portable and won't break if you move your project folder.
  198. 4. Confirm the configuration installation with the given popup
  199. ![image](https://github.com/user-attachments/assets/b1f05d33-3694-4256-a57b-8556005021ba)
  200. </details>
  201. <details>
  202. <summary><span style="font-size: 1.1em; font-weight: bold;">Option 2: Configure Manually</span></summary>
  203. Open the MCP configuration file of your AI client and add the MCP Unity server configuration:
  204. > 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).
  205. >
  206. > For configs that live inside the Unity project tree and get committed to git (e.g. `<project>/.vscode/mcp.json`, `<project>/opencode.json`, `<project>/.cursor/mcp.json`, `<project>/.mcp.json`, `<project>/.codex/config.toml`), prefer a project-relative path so the same file works across machines. Toggle **"Use relative path"** in the Server Window to switch the copy-paste snippet between absolute and project-relative forms. The **Configure GitHub Copilot**, **Configure OpenCode**, **Configure Cursor (Project)**, **Configure Claude Code (Project)**, and **Configure Codex CLI (Project)** buttons already emit relative paths automatically.
  207. >
  208. > Project-local buttons (Cursor / Claude Code / Codex CLI) write the MCP server entry into the Unity project directory instead of your global user config, so other (non-Unity) projects don't see MCP connection-failure warnings. For **Codex CLI (Project)** specifically, you must approve the project trust prompt the first time you run `codex` from the project root, otherwise Codex ignores `<project>/.codex/config.toml`.
  209. **For JSON-based clients** (Cursor, Windsurf, Claude Code, GitHub Copilot, etc.):
  210. ```json
  211. {
  212. "mcpServers": {
  213. "mcp-unity": {
  214. "command": "node",
  215. "args": [
  216. "ABSOLUTE/PATH/TO/mcp-unity/Server~/build/index.js"
  217. ]
  218. }
  219. }
  220. }
  221. ```
  222. For workspace-scoped VS Code / GitHub Copilot (`.vscode/mcp.json`), use `${workspaceFolder}` so the path is portable across machines:
  223. ```json
  224. {
  225. "mcpServers": {
  226. "mcp-unity": {
  227. "command": "node",
  228. "args": [
  229. "${workspaceFolder}/Library/PackageCache/com.gamelovers.mcp-unity@<hash>/Server~/build/index.js"
  230. ]
  231. }
  232. }
  233. }
  234. ```
  235. **For Codex CLI** (`~/.codex/config.toml`):
  236. ```toml
  237. [mcp_servers.mcp-unity]
  238. command = "node"
  239. args = ["ABSOLUTE/PATH/TO/mcp-unity/Server~/build/index.js"]
  240. ```
  241. **For Cursor — project-local** (`.cursor/mcp.json` in the Unity project root, project-relative path):
  242. ```json
  243. {
  244. "mcpServers": {
  245. "mcp-unity": {
  246. "command": "node",
  247. "args": [
  248. "Library/PackageCache/com.gamelovers.mcp-unity@<hash>/Server~/build/index.js"
  249. ]
  250. }
  251. }
  252. }
  253. ```
  254. **For Claude Code — project-local** (`.mcp.json` in the Unity project root, project-relative path — Claude Code's team-shared MCP config):
  255. ```json
  256. {
  257. "mcpServers": {
  258. "mcp-unity": {
  259. "command": "node",
  260. "args": [
  261. "Library/PackageCache/com.gamelovers.mcp-unity@<hash>/Server~/build/index.js"
  262. ]
  263. }
  264. }
  265. }
  266. ```
  267. **For Codex CLI — project-local** (`.codex/config.toml` in the Unity project root, project-relative path):
  268. ```toml
  269. [mcp_servers.mcp-unity]
  270. command = "node"
  271. args = ["Library/PackageCache/com.gamelovers.mcp-unity@<hash>/Server~/build/index.js"]
  272. ```
  273. > Codex layers this file over the global `~/.codex/config.toml`, but only when the project is marked trusted. The first time you `cd` into the project and run `codex`, approve the trust prompt — otherwise Codex ignores `.codex/config.toml`.
  274. **For OpenCode** (`opencode.json` in the Unity project root):
  275. ```json
  276. {
  277. "$schema": "https://opencode.ai/config.json",
  278. "mcp": {
  279. "mcp-unity": {
  280. "type": "local",
  281. "enabled": true,
  282. "command": ["node", "Library/PackageCache/com.gamelovers.mcp-unity@<hash>/Server~/build/index.js"],
  283. "environment": {}
  284. }
  285. }
  286. }
  287. ```
  288. > Note: the `@<hash>` segment in the UPM package cache path changes when the package is updated. If you update MCP Unity, re-run the **Configure** button (or update the path manually) so the snippet points at the new cache directory.
  289. </details>
  290. ## <a name="start-server"></a>Start Unity Editor MCP Server
  291. 1. Open the Unity Editor
  292. 2. Navigate to Tools > MCP Unity > Server Window
  293. 3. Click "Start Server" to start the WebSocket server
  294. 4. Open your AI Coding IDE (e.g. Cursor, Windsurf, Claude Code, Codex CLI, GitHub Copilot, Google Antigravity, OpenCode, etc.) and start executing Unity tools
  295. ![connect](https://github.com/user-attachments/assets/2e266a8b-8ba3-4902-b585-b220b11ab9a2)
  296. > When the AI client connects to the WebSocket server, it will automatically show in the green box in the window
  297. ## Optional: Set WebSocket Port
  298. By default, the WebSocket server runs on port '8090'. To change it:
  299. 1. Open the Unity Editor
  300. 2. Navigate to Tools > MCP Unity > Server Window
  301. 3. Change the "Connection Port" value to your desired port number
  302. 4. Unity persists the value in `ProjectSettings/McpUnitySettings.json`
  303. 5. Restart the Node.js server
  304. The Node bridge discovers that project settings file from its installed package path, so it does not depend on the MCP client's working directory. To override it for one Node process, set `UNITY_PORT`, for example: `UNITY_PORT=9001 node build/index.js`.
  305. ## Optional: Set Timeout
  306. By default, the timeout between the MCP server and the WebSocket is 10 seconds.
  307. To change it:
  308. 1. Open the Unity Editor
  309. 2. Navigate to Tools > MCP Unity > Server Window
  310. 3. Change the "Request Timeout (seconds)" value to your desired timeout seconds
  311. 4. Unity persists the value in `ProjectSettings/McpUnitySettings.json`
  312. 5. Restart the Node.js server
  313. To override it for one Node process, set `UNITY_REQUEST_TIMEOUT` (in seconds), for example: `UNITY_REQUEST_TIMEOUT=30 node build/index.js`.
  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. ## Optional: Run a Persistent Headless MCP Host
  317. MCP Unity remains disabled in `-batchmode` by default so CI and cloud builds do not start a bridge or run npm. To run a long-lived headless Editor as an MCP host, opt in before launching Unity by either enabling **Allow Batch Mode Server** in the Server Window or setting `MCP_UNITY_ALLOW_BATCH_MODE=true`:
  318. ```bash
  319. MCP_UNITY_ALLOW_BATCH_MODE=true Unity -batchmode -nographics -projectPath /path/to/project -logFile /path/to/unity.log
  320. ```
  321. The Unity-side WebSocket server starts normally when opted in, but it never runs `npm install` or `npm run build` in batch mode. Ensure the Node bridge is already built and available to the MCP client.
  322. ## Bridge Configuration Resolution
  323. The Node bridge resolves each connection value in this order: its environment variable (`UNITY_PORT`, `UNITY_HOST`, or `UNITY_REQUEST_TIMEOUT`), `MCP_UNITY_SETTINGS_PATH`, the `ProjectSettings/McpUnitySettings.json` file found above the installed package, then a file found above its working directory, and finally the defaults. Generated MCP configurations set `MCP_UNITY_SETTINGS_PATH` and `MCP_UNITY_AUTH_TOKEN_PATH` explicitly. The bridge logs the value source and warns before falling back to defaults.
  324. ## Bridge Security and Package Installation
  325. MCP Unity creates a per-project 256-bit authentication token at `Library/McpUnity/bridge-token`. Token resolution is strict: `MCP_UNITY_AUTH_TOKEN` takes precedence, followed by `MCP_UNITY_AUTH_TOKEN_PATH`, followed by the token beside the discovered Unity project. Explicit missing or malformed values fail without fallback. Generated configurations use the token-file path and never copy the secret into `ProjectSettings`.
  326. The Unity endpoint requires HTTP Basic credentials with username `mcp-unity`, and rejects every WebSocket handshake that supplies an `Origin` header. Direct WebSocket integrations must authenticate and omit `Origin`. Use the Server Window to copy or regenerate the token; after rotation, restart all MCP client processes.
  327. The `add_package` tool is disabled by default because Unity packages can execute Editor code when they compile. Enable **Allow Package Installation** in Tools > MCP Unity > Server Window, or set `AllowPackageInstallation` to `true` in `ProjectSettings/McpUnitySettings.json`, only when package sources and MCP clients are trusted.
  328. Version 1.5.0 intentionally rejects 1.4.x Node bridges. Upgrade both the Unity and Node package components, run the Unity Configure action again if the package-cache path changed, and restart MCP clients.
  329. ## Optional: Allow Remote MCP Bridge Connections
  330. By default, the WebSocket server binds to 'localhost'. To allow MCP bridge connections from other machines:
  331. 1. Open the Unity Editor
  332. 2. Navigate to Tools > MCP Unity > Server Window
  333. 3. Enable the "Allow Remote Connections" checkbox
  334. 4. Unity will bind the WebSocket server to '0.0.0.0' (all interfaces)
  335. 5. Restart the Node.js server to apply the new host configuration
  336. 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`
  337. Remote transport remains unencrypted `ws://`. Authentication prevents unauthorized access but does not hide traffic; restrict remote use to a trusted network, VPN, or SSH tunnel. A remote bridge that cannot read the Unity project token file must receive `MCP_UNITY_AUTH_TOKEN` through a secure secret mechanism.
  338. ## <a name="debug-server"></a>Debugging the Server
  339. <details>
  340. <summary><span style="font-size: 1.1em; font-weight: bold;">Building the Node.js Server</span></summary>
  341. The MCP Unity server is built using Node.js . It requires to compile the TypeScript code to JavaScript in the `build` directory.
  342. In case of issues, you can force install it in by:
  343. 1. Open the Unity Editor
  344. 2. Navigate to Tools > MCP Unity > Server Window
  345. 3. Click on "Force Install Server" button
  346. ![install](docs/install.jpg)
  347. If you want to build it manually, you can follow these steps:
  348. 1. Open a terminal/PowerShell/Command Prompt
  349. 2. Navigate to the Server directory:
  350. ```bash
  351. cd ABSOLUTE/PATH/TO/mcp-unity/Server~
  352. ```
  353. 3. Install dependencies:
  354. ```bash
  355. npm install
  356. ```
  357. 4. Build the server:
  358. ```bash
  359. npm run build
  360. ```
  361. 5. Run the server:
  362. ```bash
  363. node build/index.js
  364. ```
  365. </details>
  366. <details>
  367. <summary><span style="font-size: 1.1em; font-weight: bold;">Debugging with MCP Inspector</span></summary>
  368. Debug the server with [@modelcontextprotocol/inspector](https://github.com/modelcontextprotocol/inspector):
  369. - Powershell
  370. ```powershell
  371. npx @modelcontextprotocol/inspector node Server~/build/index.js
  372. ```
  373. - Command Prompt/Terminal
  374. ```cmd
  375. npx @modelcontextprotocol/inspector node Server~/build/index.js
  376. ```
  377. Don'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).
  378. </details>
  379. <details>
  380. <summary><span style="font-size: 1.1em; font-weight: bold;">Enable Console Logs</span></summary>
  381. 1. Enable logging on your terminal or into a log.txt file:
  382. - Powershell
  383. ```powershell
  384. $env:LOGGING = "true"
  385. $env:LOGGING_FILE = "true"
  386. ```
  387. - Command Prompt/Terminal
  388. ```cmd
  389. set LOGGING=true
  390. set LOGGING_FILE=true
  391. ```
  392. </details>
  393. ## Frequently Asked Questions
  394. <details>
  395. <summary><span style="font-size: 1.1em; font-weight: bold;">What is MCP Unity?</span></summary>
  396. MCP Unity is a powerful bridge that connects your Unity Editor environment to AI assistants LLM tools using the Model Context Protocol (MCP).
  397. In essence, MCP Unity:
  398. - Exposes Unity Editor functionalities (like creating objects, modifying components, running tests, etc.) as "tools" and "resources" that an AI can understand and use.
  399. - 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.
  400. - Enables you to use natural language prompts with your AI assistant to perform complex tasks within your Unity project, significantly speeding up development workflows.
  401. </details>
  402. <details>
  403. <summary><span style="font-size: 1.1em; font-weight: bold;">Why use MCP Unity?</span></summary>
  404. MCP Unity offers several compelling advantages for developers, artists, and project managers:
  405. - **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.
  406. - **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.
  407. - **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.
  408. - **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.
  409. - **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.
  410. - **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.
  411. </details>
  412. <details>
  413. <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>
  414. 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:
  415. - **Focus:**
  416. - **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.
  417. - **Unity 6.2 AI:**
  418. - 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.
  419. - A fine-tuned model to ask any question about Unity's documentation and API structure, with customized examples more accurate to Unity's environment.
  420. - 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.
  421. - **Use Cases:**
  422. - **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."
  423. - **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."
  424. - **Complementary, Not Mutually Exclusive:**
  425. 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.
  426. </details>
  427. <details>
  428. <summary><span style="font-size: 1.1em; font-weight: bold;">What MCP hosts and IDEs currently support MCP Unity?</span></summary>
  429. 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:
  430. - Cursor
  431. - Windsurf
  432. - Claude Desktop
  433. - Claude Code
  434. - Codex CLI
  435. - GitHub Copilot
  436. - Google Antigravity
  437. - OpenCode
  438. </details>
  439. <details>
  440. <summary><span style="font-size: 1.1em; font-weight: bold;">Can I extend MCP Unity with custom tools for my project?</span></summary>
  441. Yes, absolutely! One of the significant benefits of the MCP Unity architecture is its extensibility.
  442. - **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.
  443. - **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.
  444. This allows you to tailor the AI's capabilities to the specific needs and workflows of your game or application.
  445. </details>
  446. <details>
  447. <summary><span style="font-size: 1.1em; font-weight: bold;">Is MCP Unity free to use?</span></summary>
  448. 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.
  449. </details>
  450. <details>
  451. <summary><span style="font-size: 1.1em; font-weight: bold;">Why am I unable to connect to MCP Unity?</span></summary>
  452. - Ensure the WebSocket server is running (check the Server Window in Unity)
  453. - Send a console log message from MCP client to force a reconnection between MCP client and Unity server
  454. - Change the port number in the Unity Editor MCP Server window. (Tools > MCP Unity > Server Window)
  455. </details>
  456. <details>
  457. <summary><span style="font-size: 1.1em; font-weight: bold;">Why won't the MCP Unity server start?</span></summary>
  458. - Check the Unity Console for error messages
  459. - Ensure Node.js is properly installed and accessible in your PATH
  460. - Verify that all dependencies are installed in the Server directory
  461. </details>
  462. <details>
  463. <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>
  464. The `run_tests` tool returns the following response:
  465. ```
  466. Error:
  467. Connection failed: Unknown error
  468. ```
  469. 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"**.
  470. </details>
  471. <details>
  472. <summary><span style="font-size: 1.1em; font-weight: bold;">Why do some clients fail with <code>KeyError: 'position'</code> during tool initialization?</span></summary>
  473. Some MCP clients may fail while parsing tool schemas when they contain local JSON pointer references such as `#/properties/position`.
  474. MCP Unity avoids this by registering transform tool inputs (`set_transform`, `move_gameobject`, `rotate_gameobject`, `scale_gameobject`) with fresh nested vector schemas per field, so the generated schema does not rely on local `#/properties/...` references.
  475. If you still see this error:
  476. - update your MCP client to the latest version,
  477. - rebuild the Node server (`cd Server~ && npm run build`),
  478. - confirm your package version includes this compatibility fix.
  479. </details>
  480. ## Troubleshooting: WSL2 (Windows 11) networking
  481. When running the MCP (Node.js) server inside WSL2 while Unity runs on Windows 11, connecting to `ws://localhost:8090/McpUnity` may fail with `ECONNREFUSED`.
  482. Cause: WSL2 and Windows have separate network namespaces — `localhost` inside WSL2 does not point to the Windows host. By default, Unity listens on `localhost:8090`.
  483. ### Solution 1 — Enable WSL2 Mirrored mode networking (preferred)
  484. - Windows 11: Settings → System → For developers → WSL → Enable “Mirrored mode networking”.
  485. - Or via `.wslconfig` (then run `wsl --shutdown` and reopen WSL):
  486. ```ini
  487. [wsl2]
  488. networkingMode=mirrored
  489. ```
  490. After enabling, `localhost` is shared between Windows and WSL2, so the default config (`localhost:8090`) works.
  491. ### Solution 2 — Point the Node client to the Windows host
  492. Set in your WSL shell before starting the MCP client:
  493. ```bash
  494. # Use the Windows host IP detected from resolv.conf
  495. export UNITY_HOST=$(grep -m1 nameserver /etc/resolv.conf | awk '{print $2}')
  496. ```
  497. With 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).
  498. ### Solution 3 — Allow remote connections from Unity
  499. - Unity: Tools → MCP Unity → Server Window → enable “Allow Remote Connections” (Unity binds to `0.0.0.0`).
  500. - Ensure Windows Firewall allows inbound TCP on your configured port (default 8090).
  501. - From WSL2, connect to the Windows host IP (see Solution 2) or to `localhost` if mirrored mode is enabled.
  502. > [!NOTE]
  503. > 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`.
  504. #### Validate connectivity
  505. ```bash
  506. npm i -g wscat
  507. # After enabling mirrored networking
  508. wscat -c ws://localhost:8090/McpUnity
  509. # Or using the Windows host IP
  510. wscat -c ws://$UNITY_HOST:8090/McpUnity
  511. ```
  512. ## Running Tests
  513. ### C# Tests (Unity)
  514. Run tests using Unity's Test Runner:
  515. 1. Open Unity Editor
  516. 2. Navigate to Window > General > Test Runner
  517. 3. Select "EditMode" tab
  518. 4. Click "Run All" to execute all tests
  519. ### TypeScript Tests (Server)
  520. Run tests using Jest:
  521. ```bash
  522. cd Server~
  523. npm test
  524. ```
  525. To run tests in watch mode:
  526. ```bash
  527. npm run test:watch
  528. ```
  529. ## Support & Feedback
  530. If 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:
  531. - Linkedin: [![](https://img.shields.io/badge/LinkedIn-0077B5?style=flat&logo=linkedin&logoColor=white 'LinkedIn')](https://www.linkedin.com/in/miguel-tomas/)
  532. - Discord: gamester7178
  533. - Email: game.gamester@gmail.com
  534. ## Contributing
  535. Contributions are welcome! Please feel free to submit a Pull Request or open an Issue with your request.
  536. **Commit your changes** following the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) format.
  537. ## License
  538. This project is under [MIT License](LICENSE.md)
  539. ## Acknowledgements
  540. - [Model Context Protocol](https://modelcontextprotocol.io)
  541. - [Unity Technologies](https://unity.com)
  542. - [Node.js](https://nodejs.org)
  543. - [WebSocket-Sharp](https://github.com/sta/websocket-sharp)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.