MCP Unity

4 forks

61 stars

Free

What is mcp-unity

mcp-unity is a server implementation created by CoderGamester that brings the power of the Model Context Protocol (MCP) to the Unity Editor. This tool serves as a bridge between Unity projects and AI assistants, allowing these assistants to interact with and perform operations within the Unity environment. By utilizing the MCP framework, mcp-unity facilitates seamless communication between the Unity Editor and a Node.js server, enabling AI agents like Claude, Windsurf, and Cursor to execute tasks and gather information from Unity projects efficiently.

How to Use mcp-unity

To start using mcp-unity, ensure you have Unity 2022.3 or later, Node.js 18 or higher, and npm 9 or later installed on your system. Follow these steps to set up and run mcp-unity:

Install the Unity MCP Server Package: Use the Unity Package Manager to add the mcp-unity package by entering the package URL.
Set Up Node.js: Ensure Node.js is installed and accessible from your terminal. You can verify this by checking the versions using node --version and npm --version.
Configure the Server:
- Use the Unity Editor to open the MCP Server window (Tools > MCP Unity > Server Window).
- Configure your AI client by specifying the command to start the server and setting the appropriate environment variables.
Run the Server:
- Navigate to the mcp-unity package directory and start the server using Node.js.
- In the Unity Editor, initiate the server via the MCP Server Window to start the WebSocket server.

Key Features of mcp-unity

mcp-unity offers several powerful features designed to enhance the interaction between AI assistants and Unity projects:

Execute Menu Items: This feature allows AI agents to trigger Unity menu items, which are functions annotated with the MenuItem attribute, directly from the server.
Retrieve Menu Items List: AI systems can obtain a comprehensive list of all available menu items in the Unity Editor, facilitating the use of the execute_menu_item tool.
Access Game Object Hierarchy: The server can provide a detailed list of all game objects within the Unity hierarchy, enabling AI agents to understand and manipulate the scene structure.
Fetch Console Logs: AI assistants can retrieve logs from the Unity console, providing insights into runtime behavior and assisting in debugging and validation tasks.

These features make mcp-unity an indispensable tool for developers looking to integrate AI capabilities into their Unity projects, enabling a new level of interactivity and automation. The server's compatibility with widely used technologies like Node.js, TypeScript, and WebSocket ensures a robust and flexible development environment.

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

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) 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

Requirements

Unity 2022.3 or later
Node.js 18 or later (for running the server)
npm 9 or later (for building the server)

Installation

Installing the 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: `
Click "Add" package manager

Installing Node.js

To run MCP Unity server, you'll need to have Node.js 18 or later installed on your computer:

Windows

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

node --version
npm --version

macOS

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

brew install node@18

Verify the installation by opening Terminal and running:

node --version
npm --version

Installing via

To install MCP Unity via :

Currently not available

Configure MCP Server

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) MCP configuration

Configure your AI client

To configure Cursor IDE:

Add the following configuration to your Cursor MCP Configure settings:

Name: MCP Unity
Type: commmand
Command: env UNITY_PORT=8090 node ABSOLUTE/PATH/TO/mcp-unity/Server/build/index.js

To configure Claude Desktop:

Open the MCP configuration file (claude_desktop_config.json) in Claude Desktop Developer in (File > Settings > Developer > Edit Config) To configure Windsurf IDE:
Open the MCP configuration file (mcp_config.json) in Windsurf IDE in (Windsurf Settings > Advanced Settings > General > Add Sever)

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

Running the Server

You need to run the MCP Unity server for this to work, in the following ways:

Start Node.js Server

Navigate to this mcp-unity package directory in your device with the terminal.

cd ABSOLUTE/PATH/TO/mcp-unity

Run the server using Node.js:

node Server/build/index.js

Start Unity Editor MCP Server

Open the Unity Editor
Navigate to Tools > MCP Unity > Server Window
Click "Start Server" to start the WebSocket server connect

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

Open the Unity Editor
Navigate to Tools > MCP Unity > Server Window
Change the "WebSocket Port" value to your desired port number
Unity will setup the system environment variable UNITY_PORT to the new port number
Restart the Node.js server
Click again on "Start Server" to reconnect the Unity Editor web socket to the Node.js MCP Server

Option 2: Change the system environment variable UNITY_PORT in the terminal

Set the UNITY_PORT environment variable in the terminal

Powershell

$env:UNITY_PORT = "8090"

Command Prompt/Terminal

set UNITY_PORT=8090

Restart the Node.js server
Click again on "Start Server" to reconnect the Unity Editor web socket to the Node.js MCP Server

Building and Debugging the Server

The MCP Unity server is built using Node.js and TypeScript. It requires to compile the TypeScript code to JavaScript in the build directory. To build the server, open a terminal and:

Navigate to the Server directory:

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

Install dependencies:

npm install

Build the server:

npm run build

Debugging

Debug the server with @modelcontextprotocol/inspector:

npx @modelcontextprotocol/inspector node build/index.js

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

Don't forget to shutdown the server with Ctrl + C before closing the terminal or debugging it with the @modelcontextprotocol/inspector.

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

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

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

How to Use

To use the mcp-unity, follow these steps:

Visit https://github.com/CoderGamester/mcp-unityhttps://github.com/CoderG...
Follow the setup instructions to create an account (if required)
Connect the MCP server to your Claude Desktop application
Start using mcp-unity capabilities within your Claude conversations

Additional Information

Created

March 13, 2025

Company

CoderGamester

Related MCP Servers

Start building your own MCP Server

Interested in creating your own MCP Server? Check out the official documentation and resources.

Learn More