License

Skip to content

You signed in with another tab or window. Reload
to refresh your session. You signed out in another tab or window. Reload
to refresh your session. You switched accounts on another tab or window. Reload
to refresh your session. Dismiss alert

CoderGamester / mcp-unity Public

• Notifications
  You must be signed in to change notification settings

• Fork 22

• Star 153

MCP Unity Server to integrate Unity Editor game engine with different AI Model clients (e.g. Claude Desktop, Windsurf, Cursor)

License

MIT license

153 stars
22 forks
Branches
Tags
Activity

Star

Notifications
You must be signed in to change notification settings

CoderGamester/mcp-unity

main

2 Branches
0 Tags

Go to file

Code

Folders and files

| Name | | Name | Last commit message | Last commit date |
| --- | --- | --- | --- |
| Latest commit
-------------


CoderGamester

added Newtonsoft dependency to the package configuration

Mar 28, 2025

403d1c0
 · Mar 28, 2025

History
-------

28 Commits

| | |
| Editor | | Editor | added Newtonsoft dependency to the package configuration | Mar 28, 2025 |
| Server | | Server | Update readme with better visually understandable instructions | Mar 27, 2025 |
| .gitignore | | .gitignore | Finally fixed connection issues that were dependent on the service in… | Mar 23, 2025 |
| .windsurfrules | | .windsurfrules | added Newtonsoft dependency to the package configuration | Mar 28, 2025 |
| Editor.meta | | Editor.meta | docs: update README with new client configurations and build instruct… | Mar 13, 2025 |
| LICENSE.md | | LICENSE.md | separate license from Readme | Mar 18, 2025 |
| LICENSE.md.meta | | LICENSE.md.meta | separate license from Readme | Mar 18, 2025 |
| README.md | | README.md | added Newtonsoft dependency to the package configuration | Mar 28, 2025 |
| README.md.meta | | README.md.meta | docs: update README with new client configurations and build instruct… | Mar 13, 2025 |
| Server.meta | | Server.meta | docs: update README with new client configurations and build instruct… | Mar 13, 2025 |
| package.json | | package.json | added Newtonsoft dependency to the package configuration | Mar 28, 2025 |
| package.json.meta | | package.json.meta | docs: update README with new client configurations and build instruct… | Mar 13, 2025 |
| View all files | | |

Repository files navigation

MCP Unity

                              ,/(/.   *(/,                                  
                          */(((((/.   *((((((*.                             
                     .*((((((((((/.   *((((((((((/.                         
                 ./((((((((((((((/    *((((((((((((((/,                     
             ,/(((((((((((((/*.           */(((((((((((((/*.                
            ,%%#((/((((((*                    ,/(((((/(#&@@(                
            ,%%##%%##((((((/*.             ,/((((/(#&@@@@@@(                
            ,%%######%%##((/(((/*.    .*/(((//(%@@@@@@@@@@@(                
            ,%%####%#(%%#%%##((/((((((((//#&@@@@@@&@@@@@@@@(                
            ,%%####%(    /#%#%%%##(//(#@@@@@@@%,   #@@@@@@@(                
            ,%%####%(        *#%###%@@@@@@(        #@@@@@@@(                
            ,%%####%(           #%#%@@@@,          #@@@@@@@(                
            ,%%##%%%(           #%#%@@@@,          #@@@@@@@(                
            ,%%%#*              #%#%@@@@,             *%@@@(                
            .,      ,/##*.      #%#%@@@@,     ./&@#*      *`                
                ,/#%#####%%#/,  #%#%@@@@, ,/&@@@@@@@@@&\.                    
                 `*#########%%%%###%@@@@@@@@@@@@@@@@@@&*´                   
                    `*%%###########%@@@@@@@@@@@@@@&*´                        
                        `*%%%######%@@@@@@@@@@&*´                            
                            `*#%%##%@@@@@&*´                                 
                               `*%#%@&*´

     ███╗   ███╗ ██████╗██████╗         ██╗   ██╗███╗   ██╗██╗████████╗██╗   ██╗
     ████╗ ████║██╔════╝██╔══██╗        ██║   ██║████╗  ██║██║╚══██╔══╝╚██╗ ██╔╝
     ██╔████╔██║██║     ██████╔╝        ██║   ██║██╔██╗ ██║██║   ██║    ╚████╔╝ 
     ██║╚██╔╝██║██║     ██╔═══╝         ██║   ██║██║╚██╗██║██║   ██║     ╚██╔╝  
     ██║ ╚═╝ ██║╚██████╗██║             ╚██████╔╝██║ ╚████║██║   ██║      ██║   
     ╚═╝     ╚═╝ ╚═════╝╚═╝              ╚═════╝ ╚═╝  ╚═══╝╚═╝   ╚═╝      ╚═╝

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

MCP Unity currently provides the following tools:

• execute_menu_item: Executes Unity menu items (functions tagged with the MenuItem attribute)
• select_object: Selects game objects in the Unity hierarchy
• package_manager: Installs, removes, and updates packages in the Unity Package Manager
• run_tests: Runs tests using the Unity Test Runner
• notify_message: Displays messages in the Unity Editor

MCP Unity 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_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

• Unity 2022.3 or later - to install the server

• Node.js 18 or later - to start the server

• npm 9 or later - to debug the server

Installation

Installing this MCP Unity Server is a multi-step process:

Step 1: 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 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

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:

   shell node --version npm --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:

   shell brew install node@18

5. Verify the installation by opening Terminal and running:

   shell node --version npm --version

Step 3: Configure AI LLM Client

Option 1: Configure using Unity Editor

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

The right configuration can be accessed in the Unity Editor MCP Server window (Tools > MCP Unity > Server Window)

Option 2: Configure via Smithery

To install MCP Unity via Smithery
:

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.

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

Start Unity Editor MCP Server

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

Configure the WebSocket Port

By default, the WebSocket server runs on port 8080. 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

   powershell $env:UNITY_PORT = "8090"

   • Command Prompt/Terminal

   batchfile 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:

   shell cd ABSOLUTE/PATH/TO/mcp-unity/Server

2. Install dependencies:

   shell npm install

3. Build the server:

   shell npm run build

4. Run the server:

   shell node build/index.js

Debugging with MCP Inspector

Debug the server with @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
.

Enable Console Logs

1. Enable logging on your terminal or into a log.txt file:

   • Powershell

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

   • Command Prompt/Terminal

   batchfile 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

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

About

MCP Unity Server to integrate Unity Editor game engine with different AI Model clients (e.g. Claude Desktop, Windsurf, Cursor)

Topics

typescript
unity
mcp
cursor
copilot
claude
windsurf
unity-package
mcp-server

Resources

Readme

License

MIT license

Activity

Stars

153 stars

Watchers

6 watching

Forks

22 forks

Report repository

Releases

No releases published

Packages 0

No packages published

Contributors 3

• 
  CoderGamester Miguel Tomas

• 
  smithery-ai[bot]

• 
  punkpeye Frank Fiegel

Languages

• C# 57.3%

• TypeScript 21.7%

• JavaScript 20.7%

• Dockerfile 0.3%

You can’t perform that action at this time.