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

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 in the CoplayDev/unity-mcp repository, you can install it using either uv or pip.

Clone the repository and navigate to the Server directory:

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

Install dependencies using uv (recommended):

uv sync --locked

Or using pip:

pip install -r requirements.txt

Generate the default configuration by running the server once:

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

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 for material operations—and returns either a SuccessResponse or ErrorResponse object defined in 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 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, 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 will log warnings about missing server files. Ensure the Server Source Override points to the absolute path of the Server folder containing pyproject.toml, not the repository root.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}