# How to Set Up Unity MCP for a New Project: Complete Setup Guide

> Easily set up Unity MCP for your new project with this complete guide. Connect AI assistants to Unity using a Python server and C# bridge. Follow our step-by-step instructions for a seamless integration.

- Repository: [Coplay/unity-mcp](https://github.com/CoplayDev/unity-mcp)
- Tags: getting-started
- Published: 2026-07-07

---

**Unity MCP connects AI assistants to the Unity Editor through a Python server and C# package bridge, requiring installation of the server dependencies, importing the MCPForUnity package via Git URL, and configuring the Server Source Override in the MCP Setup window.**

Unity MCP (Model Context Protocol) is an open-source integration that allows large language models to control the Unity Editor through a standardized protocol. This guide covers how to set up Unity MCP for a new project using the CoplayDev/unity-mcp repository, walking through the Python server installation, Unity package configuration, and bridge initialization.

## Prerequisites

Before installing Unity MCP, ensure your environment meets these requirements:

- **Python 3.10+** installed locally
- **Unity 2021 LTS** or newer (the package supports all recent LTS releases)
- **uv** (recommended) or **pip** for Python dependency management
- Git installed for cloning the repository

## Step 1: Install the Python Server

The Python server acts as the bridge between your AI assistant and the Unity Editor. According to the [`Server/README.md`](https://github.com/CoplayDev/unity-mcp/blob/main/Server/README.md) in the CoplayDev/unity-mcp repository, you can install it using either `uv` or `pip`.

Clone the repository and navigate to the Server directory:

```bash
git clone https://github.com/CoplayDev/unity-mcp.git
cd unity-mcp/Server

```

Install dependencies using `uv` (recommended):

```bash
uv sync --locked

```

Or using pip:

```bash
pip install -r requirements.txt

```

Generate the default configuration by running the server once:

```bash
python -m mcpforunityserver

```

This starts the HTTP bridge on port **8443** and creates the initial configuration files required for the Unity connection.

## Step 2: Import the Unity Package

With the server prepared, add the `MCPForUnity` package to your Unity project using the Package Manager. As defined in [`MCPForUnity/package.json`](https://github.com/CoplayDev/unity-mcp/blob/main/MCPForUnity/package.json), this package supports Unity 2021 and newer.

Open your Unity project and navigate to **Window → Package Manager**. Click the **+** button and select **Add package from git URL**, then enter:

```

https://github.com/CoplayDev/unity-mcp.git?path=MCPForUnity#beta

```

Unity downloads the `MCPForUnity` folder as a local package. The `beta` branch contains the latest stable implementation of the Model Context Protocol integration.

## Step 3: Configure the Bridge

After importing the package, open the setup wizard to configure the connection between Unity and your local server. In Unity's menu bar, select **MCP → Setup**.

This opens the [`MCPSetupWindow.cs`](https://github.com/CoplayDev/unity-mcp/blob/main/MCPSetupWindow.cs) interface, which manages two critical settings:

1. **Server Source Override** – Set this to the absolute path of the cloned `Server` folder on your disk (e.g., `/home/user/unity-mcp/Server` or `C:\Projects\unity-mcp\Server`)
2. **Dev Mode** – Enable this to force HTTP/WebSocket communication instead of the legacy stdio bridge, ensuring a more robust connection for multi-assistant scenarios

The Dev Mode flag disables the single-client stdio bridge and forces a fresh install of the bridge each time Unity starts, which is essential for development workflows where the server code changes frequently.

## Step 4: Verify the Connection

Once settings are saved, verify the bridge is active through the **MCP → Status** panel. This interface, implemented in [`MCPForUnity/Editor/Services/HttpAutoStartHandler.cs`](https://github.com/CoplayDev/unity-mcp/blob/main/MCPForUnity/Editor/Services/HttpAutoStartHandler.cs), displays the current connection state.

If the server is running, the panel shows **Connected** with a client ID. If the server isn't running, the panel provides a **Start Server** button that automatically launches the Python process using the configured Server Source Override path.

## Using MCP Tools in Your Project

With the bridge established, invoke MCP tools from editor scripts using the `CommandRegistry` class. The registry auto-discovers all methods decorated with the `[McpForUnityTool]` attribute through reflection.

Example invocation from an editor script:

```csharp
using UnityEditor;
using Newtonsoft.Json.Linq;
using MCPForUnity.Editor.Helpers;

public class ToolExample {
    [MenuItem("MCP/Create Material")]
    static async void CreateMaterial() {
        var parameters = new JObject { 
            ["action"] = "create", 
            ["name"] = "NewMaterial" 
        };
        var response = await CommandRegistry.InvokeCommandAsync(
            "manage_material", 
            parameters
        );
        Debug.Log($"Result: {response}");
    }
}

```

The `CommandRegistry.InvokeCommandAsync` method routes requests to the appropriate tool handler—such as [`ManageMaterial.cs`](https://github.com/CoplayDev/unity-mcp/blob/main/ManageMaterial.cs) for material operations—and returns either a `SuccessResponse` or `ErrorResponse` object defined in [`MCPForUnity/Editor/Helpers/Response.cs`](https://github.com/CoplayDev/unity-mcp/blob/main/MCPForUnity/Editor/Helpers/Response.cs).

## Summary

- **Unity MCP** requires both a Python server and Unity package working together via HTTP/WebSocket
- Install the server using `uv sync` or `pip install -r requirements.txt` in the `Server` directory
- Import the package via Git URL: `https://github.com/CoplayDev/unity-mcp.git?path=MCPForUnity#beta`
- Configure the **Server Source Override** in **MCP → Setup** to point to your local server code
- Enable **Dev Mode** to use the HTTP bridge instead of the legacy stdio implementation
- Verify connection through the **MCP → Status** panel before invoking tools via `CommandRegistry.InvokeCommandAsync`

## Frequently Asked Questions

### What Unity versions are compatible with Unity MCP?

Unity MCP supports **Unity 2021 LTS and newer**, as specified in the [`MCPForUnity/package.json`](https://github.com/CoplayDev/unity-mcp/blob/main/MCPForUnity/package.json) manifest. The package uses modern Unity Editor APIs and the Package Manager's Git URL feature, which requires Unity 2020.3 or later, though the maintainers officially support 2021+ for stability.

### Can I run the Python server on a different machine than the Unity Editor?

Yes. The HTTP/WebSocket architecture allows the Python server to run on a remote machine, Docker container, or different network host while the Unity Editor remains local. Simply configure the **Server Source Override** to point to the network-accessible server address, or manually start the server with `python -m mcpforunityserver` on the remote host and ensure port **8443** is accessible.

### What is Dev Mode and when should I use it?

**Dev Mode** disabled the legacy "single-client" stdio bridge and forces the Unity Editor to use the HTTP/WebSocket communication path. According to the implementation in [`MCPSetupWindow.cs`](https://github.com/CoplayDev/unity-mcp/blob/main/MCPSetupWindow.cs), you should enable Dev Mode when developing or debugging the server code, as it ensures a fresh bridge installation on each Unity startup and supports multi-assistant scenarios where multiple AI clients might connect simultaneously.

### How do I troubleshoot connection failures between Unity and the server?

First, verify the Python server is actually running by checking `localhost:8443` in a browser or checking the terminal output. In Unity, open **MCP → Status** to see specific error messages—if the server path is incorrect, the [`BridgeControlService.cs`](https://github.com/CoplayDev/unity-mcp/blob/main/BridgeControlService.cs) will log warnings about missing server files. Ensure the **Server Source Override** points to the absolute path of the `Server` folder containing [`pyproject.toml`](https://github.com/CoplayDev/unity-mcp/blob/main/pyproject.toml), not the repository root.