https://github.com/CoderGamester/mcp-unity
MCP Unity Server to integrate Unity Editor game engine with different AI Model clients (e.g. Claude Desktop, Windsurf, Cursor)
https://github.com/CoderGamester/mcp-unity
claude copilot cursor mcp mcp-server typescript unity unity-package windsurf
Last synced: 9 months ago
JSON representation
MCP Unity Server to integrate Unity Editor game engine with different AI Model clients (e.g. Claude Desktop, Windsurf, Cursor)
- Host: GitHub
- URL: https://github.com/CoderGamester/mcp-unity
- Owner: CoderGamester
- License: mit
- Created: 2025-03-13T20:41:25.000Z (9 months ago)
- Default Branch: main
- Last Pushed: 2025-03-21T00:39:31.000Z (9 months ago)
- Last Synced: 2025-03-21T01:28:49.253Z (9 months ago)
- Topics: claude, copilot, cursor, mcp, mcp-server, typescript, unity, unity-package, windsurf
- Language: C#
- Homepage:
- Size: 156 KB
- Stars: 77
- Watchers: 4
- Forks: 6
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
- awesome-mcp-servers - CoderGamester/mcp-unity - A Model Context Protocol (MCP) server designed for Unity3d Game Engine integration, allowing seamless AI-assisted development and tooling within Unity projects. ([Read more](/details/codergamestermcp-unity.md)) `unity3d` `game-development` `ai-integration` `open-source` (Development Tools MCP Servers)
- awesome-mcp-servers - CoderGamester/mcp-unity - Unity3dゲームエンジン統合によるゲーム開発用MCPサーバー (サーバー実装 / 🎮 <a name="gaming"></a> ゲーミング)
- awesome-mcp-zh - CoderGamester/mcp-unity
- awesome-mcp-servers - CoderGamester/mcp-unity - Unity3dゲームエンジン統合によるゲーム開発用MCPサーバー (サーバー実装 / 🎮 <a name="gaming"></a> ゲーミング)
- awesome-mcp-servers - Unity3d Game Engine - MCP Server to control and interact with Unity3d Game Engine for game development (Community Servers)
- Awesome-MCP-Servers-directory - Unity3d Game Engine - MCP Server to control and interact with Unity3d Game Engine for game development (Gaming)
- metorial-index - Unity Game Engine - Enhances the Unity Editor by integrating MCP clients, streamlining the development workflow with various tools and data sources. (Gaming and Game Development)
- awesome-mcp-servers - UnityEngine - Unity3d Game Engine integration for game development (🎮 <a name="gaming"></a>Gaming)
- awesome-mcp-servers - CoderGamester/mcp-unity - MCP Server for Unity3d Game Engine integration for game development (Legend / 🎮 <a name="gaming"></a>Gaming)
- awesome-mcp-servers - **mcp-unity** - Model Context Protocol (MCP) plugin to connect with Unity Editor — designed for OpenAI, Gemini, Claude, Deepseek and Grok interoperability `http` `git` `github` `c#` `ai` `git clone https://github.com/CoderGamester/mcp-unity` (📦 Other)
- awesome-mcp-list - CoderGamester/mcp-unity - unity?style=social)](https://github.com/CoderGamester/mcp-unity): Integrates with the Unity3D Game Engine via MCP. (Uncategorized / Uncategorized)
- awesome-mcp-servers - MCP Unity - MCP Server to integrate Unity Editor game engine with different AI Model clients (e.g. Claude Desktop, Windsurf, Cursor) (Table of Contents / Gaming)
- best-of-mcp-servers - GitHub - 11% open · ⏱️ 03.11.2025) (Gaming)
README
# MCP Unity [](https://www.linkedin.com/in/miguel-tomas/)
[](https://modelcontextprotocol.io/introduction)
[](https://smithery.ai/server/@CoderGamester/mcp-unity)
[](https://unity.com/releases/editor/archive)
[](https://nodejs.org/en/download/)
[](https://www.typescriptlang.org/)
[](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API)
[](https://github.com/CoderGamester/mcp-unity/commits/main)
[](https://github.com/CoderGamester/mcp-unity/stargazers)
[](https://github.com/CoderGamester/mcp-unity/network/members)
[](https://opensource.org/licenses/MIT)
```
,/(/. *(/,
*/(((((/. *((((((*.
.*((((((((((/. *((((((((((/.
./((((((((((((((/ *((((((((((((((/,
,/(((((((((((((/*. */(((((((((((((/*.
,%%#((/((((((* ,/(((((/(#&@@(
,%%##%%##((((((/*. ,/((((/(#&@@@@@@(
,%%######%%##((/(((/*. .*/(((//(%@@@@@@@@@@@(
,%%####%#(%%#%%##((/((((((((//#&@@@@@@&@@@@@@@@(
,%%####%( /#%#%%%##(//(#@@@@@@@%, #@@@@@@@(
,%%####%( *#%###%@@@@@@( #@@@@@@@(
,%%####%( #%#%@@@@, #@@@@@@@(
,%%##%%%( #%#%@@@@, #@@@@@@@(
,%%%#* #%#%@@@@, *%@@@(
., ,/##*. #%#%@@@@, ./&@#* *`
,/#%#####%%#/, #%#%@@@@, ,/&@@@@@@@@@&\.
`*#########%%%%###%@@@@@@@@@@@@@@@@@@&*´
`*%%###########%@@@@@@@@@@@@@@&*´
`*%%%######%@@@@@@@@@@&*´
`*#%%##%@@@@@&*´
`*%#%@&*´
███╗ ███╗ ██████╗██████╗ ██╗ ██╗███╗ ██╗██╗████████╗██╗ ██╗
████╗ ████║██╔════╝██╔══██╗ ██║ ██║████╗ ██║██║╚══██╔══╝╚██╗ ██╔╝
██╔████╔██║██║ ██████╔╝ ██║ ██║██╔██╗ ██║██║ ██║ ╚████╔╝
██║╚██╔╝██║██║ ██╔═══╝ ██║ ██║██║╚██╗██║██║ ██║ ╚██╔╝
██║ ╚═╝ ██║╚██████╗██║ ╚██████╔╝██║ ╚████║██║ ██║ ██║
╚═╝ ╚═╝ ╚═════╝╚═╝ ╚═════╝ ╚═╝ ╚═══╝╚═╝ ╚═╝ ╚═╝
```
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
- 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
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"
### Installing 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:
```bash
node --version
npm --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:
```bash
brew install node@18
```
5. Verify the installation by opening Terminal and running:
```bash
node --version
npm --version
```
### Installing via Smithery
To install MCP Unity via [Smithery](https://smithery.ai/server/@CoderGamester/mcp-unity):
```
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)
### 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)
```json
{
"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
1. Navigate to this `mcp-unity` package directory in your device with the terminal.
```bash
cd ABSOLUTE/PATH/TO/mcp-unity
```
2. Run the server using Node.js:
```bash
node Server/build/index.js
```
### 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
## 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: Change the system environment variable UNITY_PORT in the terminal
1. Set the UNITY_PORT environment variable in the terminal
- Powershell
```powershell
$env:UNITY_PORT = "8090"
```
- Command Prompt/Terminal
```cmd
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
## 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:
1. Navigate to the Server directory:
```bash
cd ABSOLUTE/PATH/TO/mcp-unity/Server
```
2. Install dependencies:
```bash
npm install
```
3. Build the server:
```bash
npm run build
```
### Debugging
1. Debug the server with [@modelcontextprotocol/inspector](https://github.com/modelcontextprotocol/inspector):
```bash
npx @modelcontextprotocol/inspector node build/index.js
```
2. Enable logging on your terminal or into a log.txt file:
- Powershell
```powershell
$env:LOGGING = "true"
$env:LOGGING_FILE = "true"
```
- Command Prompt/Terminal
```cmd
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](https://github.com/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
### 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
## 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](https://www.conventionalcommits.org/en/v1.0.0/) format.
## License
This project is under MIT license