MCP Unity

MCP Unity is a Unity Editor extension that implements the Model Context Protocol. It bridges the interaction between AI assistants and Unity projects through a Node.js server, providing functions such as menu execution, object selection, and component update.

Developer tools Games and gamification #Unity Extension #AI Interaction #Protocol Bridging #Editor Tool Local .JavaScript

rating : 5 points

downloads : 478

update time : 2025-04-22

What is MCP Unity?

MCP Unity is a bridge tool that integrates AI assistants into the Unity Editor, allowing AIs such as Claude and Windsurf to directly operate your Unity projects. It implements the MCP protocol through a Node.js server, enabling AI to execute Unity editor menu commands, modify scene objects, run tests, and perform other operations.

How to use MCP Unity?

Just three steps: 1) Install via the Unity Package Manager. 2) Configure the AI client. 3) Start the server, and then you can control the Unity Editor with natural language.

Applicable scenarios

Suitable for Unity development scenarios that require AI-assisted development, automated testing, rapid prototyping, and batch processing of scene objects.

Main Features

Intelligent IDE IntegrationAutomatically add Unity package caches to editors like VSCode to enhance the AI's understanding of project dependencies.

Menu Command ExecutionExecute any Unity Editor menu command with natural language.

Scene Object EditingSelect/modify game objects and their component properties in the scene.

Package ManagementInstall/manage Unity software packages via AI instructions.

Test ExecutionExecute various tests in the Unity Test Runner.

Advantages and Limitations

Advantages

Control the Unity Editor with natural language to improve development efficiency

Seamlessly integrate with mainstream AI assistants (Claude/Windsurf, etc.)

Support full - fledged Unity editing function calls

Automatically sense the project environment

Limitations

Requires a Node.js runtime environment

Some complex operations still require manual confirmation

Does not support Unity versions below 2022 for now

How to Use

Install the Unity Package

Install MCP Unity via the Unity Package Manager. Window > Package Manager > Add package from git URL

Install Node.js

Ensure that Node.js version 18+ is installed.

Configure the AI Client

Select Tools > MCP Unity > Server Window in the Unity Editor for configuration.

Start the Server

Click the Start Server button and wait for the AI client to connect.

Usage Examples

Create a New ObjectCreate a new game object in the scene via an AI instruction.

Batch Modify PropertiesModify the same properties of multiple game objects at once.

Frequently Asked Questions

What if the connection fails?

Why aren't the menu commands executed?

Related Resources

MCP Protocol Official Website

Official documentation for the Model Context Protocol

GitHub Repository

Project source code and issue tracking

Unity Official Documentation

Unity Editor version archive

🚀 Unity MCP Protocol Integration Guide

This guide provides a comprehensive overview of integrating the MCP protocol into a Unity project, including installation, configuration, and troubleshooting steps.

🚀 Quick Start

Obtain the Code

Clone the repository via Git:

git clone https://github.com/CoderGamester/mcp-unity.git
cd mcp-unity

Import the following packages into Assets/Package Manager in Unity:
- Model Context Protocol
- WebSocketSharp

📦 Installation

Project Structure

mcp-unity/
├── Assets/             # Unity project assets
│   ├── Editor/         # MCP editor scripts
│   └── PackageManager/ # Package management configuration files
├── Server/            # Node.js server-side code
│   ├── src/           # Source code folder
│   │   ├── index.ts    # Entry file
│   │   └── server.ts   # Server logic
│   └── build/         # Compilation output directory
├── .env                # Environment variable configuration
└── README.md          # Usage documentation

Run the Project

Quick Startup

Run the Unity editor and ensure the MCP component is enabled.

Start the Node.js server:

cd ABSOLUTE/PATH/TO/mcp-unity/Server
npm install && node build/index.js

📚 Documentation

Configuration Guide

Environment Variable Settings

Create or edit the .env file in the root directory and add the following configuration:

LOGGING=true
LOGGING_FILE=false
PORT=8090

Server Parameters

Pass additional parameters via the command line:

# Set the log level
--logLevel debug

# Enable remote debugging
--enableRemoteDebugging

Runtime Configuration

MCP Protocol Versions

The following protocol versions are supported:

v1.0.0
v1.1.0 (latest)

Network Settings

Set the WebSocket server address:
```
ws://localhost:8090
```
Configure the HTTP interface endpoint:
```
"/api/v1"
```

Debugging Guide

Source Code Debugging

Add breakpoints in the Server/src directory and start the debugger.

Log Output

Enable console logging:

set LOGGING=true & set LOGGING_FILE=false

Troubleshooting

Connection Issues

Confirm that the WebSocket server is running.
Check the firewall settings to ensure the port is open.
Verify the correctness of the connection address and port configuration.

Startup Failures

Check the error messages in the Unity console.
Ensure that Node.js is correctly installed and added to the PATH.
Verify that the dependency package versions meet the requirements.

💻 Usage Examples

Basic Usage

To start using the MCP protocol in your Unity project, follow the installation and configuration steps outlined above.

📄 License

This project is licensed under the MIT Open Source License:

MIT License

Copyright (c) 2023 CoderGamester

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

📚 Appendix

Frequently Asked Questions

How to upgrade the MCP version?
- Select the update option in the Package Manager.
What if the Node.js server fails to start?
- Check if the npm packages are installed successfully.
- Ensure that the Node.js version meets the requirements (>=14.x).
How to disable log output?
- Set LOGGING=false in the .env file.