Mcp Unity

MCP Unity Editor (Game Engine)

[](https://modelcontextprotocol.io/introduction) [](https://unity.com/releases/editor/archive) [](https://nodejs.org/en/download/) [](https://github.com/CoderGamester/mcp-unity/stargazers) [](https://github.com/CoderGamester/mcp-unity/commits/main) [](https://opensource.org/licenses/MIT)

| [🇺🇸English](README.md) | [🇨🇳简体中文](README_zh-CN.md) | [🇯🇵日本語](README-ja.md) | |----------------------|---------------------------------|----------------------|

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

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.

Features

IDE Integration - Package Cache Access

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:

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

• create_prefab: Creates a prefab with optional MonoBehaviour script and serialized field values

> Example prompt: "Create a prefab named 'Player' from the 'PlayerController' script"

• create_scene: Creates a new scene and saves it to the specified path

> Example prompt: "Create a new scene called 'Level1' in the Scenes folder"

• load_scene: Loads a scene by path or name, with optional additive loading

> Example prompt: "Load the MainMenu scene"

• delete_scene: Deletes a scene by path or name and removes it from Build Settings

> Example prompt: "Delete the old TestScene from my project"

• get_gameobject: Gets detailed information about a specific GameObject including all components

> Example prompt: "Get the details of the Player GameObject"

• get_console_logs: Retrieves logs from the Unity console with pagination support

> Example prompt: "Show me the last 20 error logs from the Unity console"

• recompile_scripts: Recompiles all scripts in the Unity project

> Example prompt: "Recompile scripts in my Unity project"

• save_scene: Saves the current active scene, with optional Save As to a new path

> Example prompt: "Save the current scene" or "Save the scene as 'Assets/Scenes/Level2.unity'"

• get_scene_info: Gets information about the active scene including name, path, dirty state, and all loaded scenes

> Example prompt: "What scenes are currently loaded in my project?"

• unload_scene: Unloads a scene from the hierarchy (does not delete the scene asset)

> Example prompt: "Unload the UI scene from the hierarchy"

• duplicate_gameobject: Duplicates a GameObject in the scene with optional renaming and reparenting

> Example prompt: "Duplicate the Enemy prefab 5 times and rename them Enemy1 through Enemy5"

• delete_gameobject: Deletes a GameObject from the scene

> Example prompt: "Delete the old Player object from the scene"

• reparent_gameobject: Changes the parent of a GameObject in the hierarchy

> Example prompt: "Move the HealthBar object to be a child of the UI Canvas"

• move_gameobject: Moves a GameObject to a new position (local or world space)

> Example prompt: "Move the Player object to position (10, 0, 5) in world space"

• rotate_gameobject: Rotates a GameObject to a new rotation (local or world space, Euler angles or quaternion)

> Example prompt: "Rotate the Camera 45 degrees on the Y axis"

• scale_gameobject: Scales a GameObject to a new local scale

> Example prompt: "Scale the Enemy object to twice its size"

• set_transform: Sets position, rotation, and scale of a GameObject in a single operation

> Example prompt: "Set the Cube's position to (0, 5, 0), rotation to (0, 90, 0), and scale to (2, 2, 2)"

• create_material: Creates a new material with specified shader and saves it to the project

> Example prompt: "Create a red material called 'EnemyMaterial' using the URP Lit shader"

• assign_material: Assigns a material to a GameObject's Renderer component

> Example prompt: "Assign the 'EnemyMaterial' to the Enemy GameObject"

• modify_material: Modifies properties of an existing material (colors, floats, textures)

> Example prompt: "Change the color of 'EnemyMaterial' to blue and set metallic to 0.8"

• get_material_info: Gets detailed information about a material including shader and all properties

> Example prompt: "Show me all the properties of the 'PlayerMaterial'"

• batch_execute: Executes multiple tool operations in a single batch request, reducing round-trips and enabling atomic operations with optional rollback on failure

> Example prompt: "Create 10 empty GameObjects named Enemy1 through Enemy10 in a single batch operation"

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 6 or later - to [install the server](#install-server)
• Node.js 18 or later - to [start the server](#start-server)
• npm 9 or later - to [debug the server](#debug-server)

> [!NOTE] > Project Paths with Spaces > > 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. > > Examples: > - ✅ Recommended: C:\Users\YourUser\Documents\UnityProjects\MyAwesomeGame > - ✅ Supported: C:\Users\Your User\Documents\Unity Projects\My Awesome Game

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:

Windows

1. Visit the Node.js download page
2. Download the Windows Installer (.msi) for the LTS version (recommended)
3. Run the installer and follow the installation wizard
4. Verify the installation by opening PowerShell and running:

``bash node --version ``

macOS

1. Visit the Node.js download page
2. Download the macOS Installer (.pkg) for the LTS version (recommended)
3. Run the installer and follow the installation wizard
4. Alternatively, if you have Homebrew installed, you can run:

``bash brew install node@18 ``

1. Verify the installation by opening Terminal and running:

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

Option 1: Configure using Unity Editor

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.

1. Confirm the configuration installation with the given popup

Option 2: Configure Manually

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. /.vscode/mcp.json, /opencode.json, /.cursor/mcp.json, /.mcp.json, /.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 /.codex/config.toml.

For JSON-based clients (Cursor, Windsurf, Claude Code, GitHub Copilot, etc.):

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

For workspace-scoped VS Code / GitHub Copilot (.vscode/mcp.json), use ${workspaceFolder} so the path is portable across machines:

{
   "mcpServers": {
       "mcp-unity": {
          "command": "node",
          "args": [
             "${workspaceFolder}/Library/PackageCache/com.gamelovers.mcp-unity@/Server~/build/index.js"
          ]
       }
   }
}

For Codex CLI (~/.codex/config.toml):

[mcp_servers.mcp-unity]
command = "node"
args = ["ABSOLUTE/PATH/TO/mcp-unity/Server~/build/index.js"]

For Cursor — project-local (.cursor/mcp.json in the Unity project root, project-relative path):

{
   "mcpServers": {
       "mcp-unity": {
          "command": "node",
          "args": [
             "Library/PackageCache/com.gamelovers.mcp-unity@/Server~/build/index.js"
          ]
       }
   }
}

For Claude Code — project-local (.mcp.json in the Unity project root, project-relative path — Claude Code's team-shared MCP config):

{
   "mcpServers": {
       "mcp-unity": {
          "command": "node",
          "args": [
             "Library/PackageCache/com.gamelovers.mcp-unity@/Server~/build/index.js"
          ]
       }
   }
}

For Codex CLI — project-local (.codex/config.toml in the Unity project root, project-relative path):

[mcp_servers.mcp-unity]
command =

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [CoderGamester](https://github.com/CoderGamester)
- **Source:** [CoderGamester/mcp-unity](https://github.com/CoderGamester/mcp-unity)
- **License:** MIT

Install and usage instructions live in the source repository linked above.