📌Overview

Purpose: MCP Unity facilitates interaction between AI assistants and Unity projects by utilizing the Model Context Protocol.

Overview: MCP Unity is a package developed for the Unity Editor, allowing seamless communication between AI agents and Unity environments. It connects Unity to a Node.js server implementing the MCP protocol, enabling AI assistants to perform various operations directly within the Unity Editor.

Key Features:

execute_menu_item: Executes Unity menu items tagged with the MenuItem attribute, allowing AI to manipulate the editor.
select_object: Selects specified game objects within the Unity hierarchy, enabling targeted actions by AI agents.
package_manager: Manages Unity packages, including installation, removal, and updates, streamlining development workflows.
run_tests: Integrates with the Unity Test Runner to execute tests, improving testing efficiency for development.
notify_message: Displays customizable messages in the Unity Editor, enhancing communication and feedback during AI operations.

MCP Unity Editor (Game Engine)

MCP Unity is an implementation of the Model Context Protocol for Unity Editor, allowing AI assistants to interact with your Unity projects. This package provides a bridge between Unity and a Node.js server that implements the MCP protocol, enabling AI agents like Claude, Windsurf, and Cursor to execute operations within the Unity Editor.

Features

IDE Integration - Package Cache Access

MCP Unity provides automatic integration with VSCode-like IDEs (Visual Studio Code, Cursor, Windsurf) by adding the Unity Library/PackedCache folder to your workspace. This feature:

Improves code intelligence for Unity packages
Enables better autocompletion and type information for Unity packages
Helps AI coding assistants understand your project's dependencies

MCP Server Tools

execute_menu_item: Executes Unity menu items (functions tagged with the MenuItem attribute)
Example: "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: "Select the Main Camera object in my scene"
update_component: Updates component fields on a GameObject or adds it if missing
Example: "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: "Add the TextMeshPro package to my project"
run_tests: Runs tests using the Unity Test Runner
Example: "Run all the EditMode tests in my project"
notify_message: Displays messages in the Unity Editor
Example: "Send a notification to Unity that the task has been completed"
add_asset_to_scene: Adds an asset from the AssetDatabase to the Unity scene
Example: "Add the Player prefab from my project to the current scene"

MCP Server Resources

unity://menu-items: Retrieves a list of all available menu items in the Unity Editor
Example: "Show me all available menu items related to GameObject creation"
unity://hierarchy: Retrieves a list of all game objects in the Unity hierarchy
Example: "Show me the current scene hierarchy structure"
unity://gameobject/{id}: Retrieves detailed information about a specific GameObject by instance ID or object path, including components and serialized properties
Example: "Get me detailed information about the Player GameObject"
unity://logs: Retrieves a list of all logs from the Unity console
Example: "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: "List all the packages currently installed in my Unity project"
unity://assets: Retrieves information about assets in the Unity Asset Database
Example: "Find all texture assets in my project"
unity://tests/{testMode}: Retrieves information about tests in the Unity Test Runner
Example: "List all available tests in my Unity project"

Requirements

Unity 2022.3 or later
Node.js 18 or later
npm 9 or later

Installation

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 need Node.js 18 or later:

Visit the Node.js download page
Download and install the LTS version suitable for your OS
Verify installation by running:
```
node --version
```

Step 3: Configure AI LLM Client

Option 1: Configure using Unity Editor

Open the Unity Editor
Navigate to Tools > MCP Unity > Server Window
Click "Configure" for your AI LLM client
Confirm the configuration installation popup

Option 2: Configure Manually

Open the MCP configuration file of your AI client and copy the following:

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

Replace ABSOLUTE/PATH/TO with the absolute path to your MCP Unity installation.

Starting the Unity Editor MCP Server

Open the Unity Editor
Navigate to Tools > MCP Unity > Server Window
Click "Start Server" to start the WebSocket server
Open your AI Coding IDE (e.g., Claude Desktop, Cursor IDE, Windsurf IDE) and start using Unity tools

When the AI client connects, it appears in the green box in the Server Window.

Optional: Set WebSocket Port

Default WebSocket server port is 8090. You can change this via:

Option 1: Using Unity Editor

Open the Unity Editor
Navigate to Tools > MCP Unity > Server Window
Change the "WebSocket Port" value
Restart the Node.js server and click "Start Server" again

Option 2: Using the terminal

Powershell:
```
$env:UNITY_PORT = "8090"
```
Command Prompt/Terminal:
```
set UNITY_PORT=8090
```

Restart Node.js server and start again.

Debugging the Server

Building the Node.js Server

Navigate to the Server directory:
```
cd ABSOLUTE/PATH/TO/mcp-unity/Server
```
Install dependencies:
```
npm install
```
Build the server:
```
npm run build
```
Run the server:
```
node build/index.js
```

Debugging with MCP Inspector

Run with inspector:

Powershell:

npx @modelcontextprotocol/inspector node Server/build/index.js

Command Prompt/Terminal:

npx @modelcontextprotocol/inspector node Server/build/index.js

Remember to stop the server with Ctrl + C when done.

Enable Console Logs

Powershell:

$env:LOGGING = "true"
$env:LOGGING_FILE = "true"

Command Prompt/Terminal:
```
set LOGGING=true
set LOGGING_FILE=true
```

Troubleshooting

Connection Issues
- Ensure WebSocket server is running
- Check firewall restrictions
- Confirm port number (default 8090)
- Change port in Unity Editor Server Window if necessary
Server Not Starting
- Check Unity Console for errors
- Verify Node.js installation and PATH
- Check dependencies installed in Server directory
Menu Items Not Executing
- Verify menu item path is correct (case-sensitive)
- Check if confirmation is required
- Ensure menu item is available in the current context

Support & Feedback

If you need support, please open an issue on this repository:
https://github.com/CoderGamester/mcp-unity/issues

Alternatively, reach out via:

Linkedin: https://www.linkedin.com/in/miguel-tomas/
Discord: gamester7178
Email: game.gamester@gmail.com

Contributing

Contributions are welcome! Submit Pull Requests or open Issues.
Follow Conventional Commits format for commits.

License

This project is under the MIT License.

mcp-unity