,/(/. *(/,
*/(((((/. *((((((*.
.*((((((((((/. *((((((((((/.
./((((((((((((((/ *((((((((((((((/,
,/(((((((((((((/*. */(((((((((((((/*.
,%%#((/((((((* ,/(((((/(#&@@(
,%%##%%##((((((/*. ,/((((/(#&@@@@@@(
,%%######%%##((/(((/*. .*/(((//(%@@@@@@@@@@@(
,%%####%#(%%#%%##((/((((((((//#&@@@@@@&@@@@@@@@(
,%%####%( /#%#%%%##(//(#@@@@@@@%, #@@@@@@@(
,%%####%( *#%###%@@@@@@( #@@@@@@@(
,%%####%( #%#%@@@@, #@@@@@@@(
,%%##%%%( #%#%@@@@, #@@@@@@@(
,%%%#* #%#%@@@@, *%@@@(
., ,/##*. #%#%@@@@, ./&@#* *`
,/#%#####%%#/, #%#%@@@@, ,/&@@@@@@@@@&.
`*#########%%%%###%@@@@@@@@@@@@@@@@@@&*´
`*%%###########%@@@@@@@@@@@@@@&*´
`*%%%######%@@@@@@@@@@&*´
`*#%%##%@@@@@&*´
`*%#%@&*´
███╗ ███╗ ██████╗██████╗ ██╗ ██╗███╗ ██╗██╗████████╗██╗ ██╗
████╗ ████║██╔════╝██╔══██╗ ██║ ██║████╗ ██║██║╚══██╔══╝╚██╗ ██╔╝
██╔████╔██║██║ ██████╔╝ ██║ ██║██╔██╗ ██║██║ ██║ ╚████╔╝
██║╚██╔╝██║██║ ██╔═══╝ ██║ ██║██║╚██╗██║██║ ██║ ╚██╔╝
██║ ╚═╝ ██║╚██████╗██║ ╚██████╔╝██║ ╚████║██║ ██║ ██║
╚═╝ ╚═╝ ╚═════╝╚═╝ ╚═════╝ ╚═╝ ╚═══╝╚═╝ ╚═╝ ╚═╝
MCP Unity is an implementation of the Model Context Protocol for Unity Editor, allowing AI assistants to interact with your Unity projects. This package provides a bridge between Unity and a Node.js server that implements the MCP protocol, enabling AI agents like Claude, Windsurf, and Cursor to execute operations within the Unity Editor.
Features
This MCP currently provides the following tools:
- execute_menu_item: Executes Unity menu items (functions tagged with the MenuItem attribute)
- select_gameobject: Selects game objects in the Unity hierarchy by path or instance ID
- update_component: Updates component fields on a GameObject or adds it to the GameObject if it does not contain the component
- add_package: Installs new packages in the Unity Package Manager
- run_tests: Runs tests using the Unity Test Runner
- notify_message: Displays messages in the Unity Editor
This MCP currently provides the following resources:
- get_menu_items: Retrieves a list of all available menu items in the Unity Editor to facilitate execute_menu_item tool
- get_hierarchy: Retrieves a list of all game objects in the Unity hierarchy
- get_gameobject: Retrieves detailed information about a specific GameObject by instance ID, including all GameObject components with it's serialized properties and fields
- get_console_logs: Retrieves a list of all logs from the Unity console
- get_packages: Retrieves information about installed and available packages from the Unity Package Manager
- get_assets: Retrieves information about assets in the Unity Asset Database
- get_tests: Retrieves information about tests in the Unity Test Runner
Requirements
Installation
Installing this MCP Unity Server is a multi-step process:
Step 1: Install Unity MCP Server package via Unity Package Manager
- Open the Unity Package Manager (Window > Package Manager)
- Click the "+" button in the top-left corner
- Select "Add package from git URL..."
- Enter:
https://github.com/CoderGamester/mcp-unity.git
- Click "Add"
Step 2: Install Node.js
To run MCP Unity server, you'll need to have Node.js 18 or later installed on your computer:
Windows
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
macOS
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
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
4. Confirm the configuration installation with the given popup
Option 2: Configure via Smithery
To install MCP Unity via [Smithery](https://smithery.ai/server/@CoderGamester/mcp-unity):
Currently not available
Option 3: Configure Manually
Open the MCP configuration file of your AI client (e.g. claude_desktop_config.json in Claude Desktop) and copy the following text:
> Replace `ABSOLUTE/PATH/TO` with the absolute path to your MCP Unity installation or just copy the text from the Unity Editor MCP Server window (Tools > MCP Unity > Server Window).
{
"mcpServers": {
"mcp-unity": {
"command": "node",
"args": [
"ABSOLUTE/PATH/TO/mcp-unity/Server/build/index.js"
],
"env": {
"UNITY_PORT": "8090"
}
}
}
}
Start Unity Editor MCP Server
- Open the Unity Editor
- Navigate to Tools > MCP Unity > Server Window
- Click "Start Server" to start the WebSocket server
- Open Claude Desktop or your AI Coding IDE (e.g. Cursor IDE, Windsurf IDE, etc.) and start executing Unity tools
When the AI client connects to the WebSocket server, it will automatically show in the green box in the window
Optional: Set WebSocket Port
By default, the WebSocket server runs on port 8090. You can change this port in two ways:
Option 1: Using the Unity Editor
1. Open the Unity Editor
2. Navigate to Tools > MCP Unity > Server Window
3. Change the "WebSocket Port" value to your desired port number
4. Unity will setup the system environment variable UNITY_PORT to the new port number
5. Restart the Node.js server
6. Click again on "Start Server" to reconnect the Unity Editor web socket to the Node.js MCP Server
Option 2: Using the terminal
1. Set the UNITY_PORT environment variable in the terminal
- Powershell
$env:UNITY_PORT = "8090"
- Command Prompt/Terminal
set UNITY_PORT=8090
2. Restart the Node.js server
3. Click again on "Start Server" to reconnect the Unity Editor web socket to the Node.js MCP Server
Debugging the Server
Building the Node.js Server
The MCP Unity server is built using Node.js . It requires to compile the TypeScript code to JavaScript in the `build` directory.
To build the server, open a terminal and:
1. Navigate to the Server directory:
cd ABSOLUTE/PATH/TO/mcp-unity/Server
2. Install dependencies:
npm install
3. Build the server:
npm run build
4. Run the server:
node build/index.js
Debugging with MCP Inspector
Debug the server with [@modelcontextprotocol/inspector](https://github.com/modelcontextprotocol/inspector):
- Powershell
$env:UNITY_PORT=8090; npx @modelcontextprotocol/inspector node Server/build/index.js
- Command Prompt/Terminal
set UNITY_PORT=8090 && npx @modelcontextprotocol/inspector node Server/build/index.js
Don't forget to shutdown the server with `Ctrl + C` before closing the terminal or debugging it with the [MCP Inspector](https://github.com/modelcontextprotocol/inspector).
Enable Console Logs
1. Enable logging on your terminal or into a log.txt file:
- Powershell
$env:LOGGING = "true"
$env:LOGGING_FILE = "true"
- Command Prompt/Terminal
set LOGGING=true
set LOGGING_FILE=true
Troubleshooting
Connection Issues
- Ensure the WebSocket server is running (check the Server Window in Unity)
- Check if there are any firewall restrictions blocking the connection
- Make sure the port number is correct (default is 8080)
- Change the port number in the Unity Editor MCP Server window. (Tools > MCP Unity > Server Window)
Server Not Starting
- Check the Unity Console for error messages
- Ensure Node.js is properly installed and accessible in your PATH
- Verify that all dependencies are installed in the Server directory
Menu Items Not Executing
- Ensure the menu item path is correct (case-sensitive)
- Check if the menu item requires confirmation
- Verify that the menu item is available in the current context
Support & Feedback
If you have any questions or need support, please open an issue on this repository.
Alternative you can reach out on:
- 
- Discord: gamester7178
Contributing
Contributions are welcome! Please feel free to submit a Pull Request or open an Issue with your request.
Commit your changes following the Conventional Commits format.
License
This project is under MIT License
[
{
"description": "Executes a Unity menu item by path",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"menuPath": {
"description": "The path to the menu item to execute (e.g. "GameObject/Create Empty")",
"type": "string"
}
},
"required": [
"menuPath"
],
"type": "object"
},
"name": "execute_menu_item"
},
{
"description": "Sets the selected object in the Unity editor by path or ID",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"objectPath": {
"description": "The path or ID of the object to select (e.g. "Main Camera" or a Unity object ID)",
"type": "string"
}
},
"required": [
"objectPath"
],
"type": "object"
},
"name": "select_object"
},
{
"description": "Manages packages in the Unity Package Manager",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"branch": {
"description": "The branch to use for GitHub packages (optional)",
"type": "string"
},
"methodSource": {
"description": "The method source to use (registry, github, or disk) to add the package",
"type": "string"
},
"packageName": {
"description": "The package name to add from Unity registry (e.g. com.unity.textmeshpro)",
"type": "string"
},
"path": {
"description": "The path to use (folder path for disk method or subfolder for GitHub)",
"type": "string"
},
"repositoryUrl": {
"description": "The GitHub repository URL (e.g. https://github.com/username/repo.git)",
"type": "string"
},
"version": {
"description": "The version to use for registry packages (optional)",
"type": "string"
}
},
"required": [
"methodSource"
],
"type": "object"
},
"name": "package_manager"
},
{
"description": "Runs Unity's Test Runner tests",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"testFilter": {
"description": "Optional test filter (e.g. specific test name or namespace)",
"type": "string"
},
"testMode": {
"description": "The test mode to run (EditMode, PlayMode, or All)",
"type": "string"
}
},
"type": "object"
},
"name": "run_tests"
},
{
"description": "Sends a message to the Unity console",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"message": {
"description": "The message to display in the Unity console",
"type": "string"
},
"type": {
"description": "The type of message (info, warning, error)",
"type": "string"
}
},
"required": [
"message"
],
"type": "object"
},
"name": "notify_message"
}
]