Unity MCP server

The Unity MCP Package enables seamless communication between Unity and Large Language Models (LLMs) like Claude Desktop via the Model Context Protocol (MCP). This server acts as a bridge, allowing Unity to send commands to and receive responses from MCP-compliant tools, empowering developers to automate workflows, manipulate assets, and control the Unity Editor programmatically.

Overview

The Unity MCP Server provides a bidirectional communication channel between Unity (via C#) and a Python server, enabling:

• Asset Management: Create, import, and manipulate Unity assets programmatically.
• Scene Control: Manage scenes, objects, and their properties.
• Material Editing: Modify materials and their properties.
• Script Integration: View, create, and update Unity scripts.
• Editor Automation: Control Unity Editor functions like undo, redo, play, and build.

Installation

Prerequisites

• Unity 2020.3 LTS or newer (⚠️ only works in URP projects currently)
• Python 3.7 or newer
• uv package manager

If you're on Mac, please install uv as

brew install uv

On Windows

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

and then add to your PATH:

set Path=%USERPROFILE%\.local\bin;%Path%

On Linux

curl -LsSf https://astral.sh/uv/install.sh | sh

Otherwise, installation instructions are on their website: Install uv

⚠️ Do not proceed before installing UV

Unity Package Installation

1. Add the Unity Package

   • Open Unity Package Manager (Window > Package Manager)
   • Click the + button and select Add package from git URL
   • Enter: https://github.com/justinpbarnett/unity-mcp.git

2. Set Up Python Environment

   • Navigate to the Python directory in your project:
     • If installed as a package: Library/PackageCache/com.justinpbarnett.unity-mcp/Python
     • If installed locally: Assets/unity-mcp/Python
   • Install dependencies:

     uv venv
     uv pip install -e .
     

MCP Client Integration

1. Open the Unity MCP window (Window > Unity MCP)
2. Click the "Auto Configure" button for your desired MCP client
3. Status indicator should show green and a "Configured" message

Alternatively, manually configure your MCP client:

1. Open the Unity MCP window (Window > Unity MCP)
2. Click the "Manually Configure" button for your desired MCP client
3. Copy the JSON code below to the config file

{
  "mcpServers": {
    "unityMCP": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/your/unity-mcp/Python",
        "run",
        "server.py"
      ]
    }
  }
}

Replace /path/to/your/unity-mcp/Python with the actual path to the Unity MCP Python directory.

⚠️ Only run one instance of the MCP server (either on Cursor or Claude Desktop), not both

4. Start Claude Desktop or Cursor
   • Launch your preferred tool
   • The Unity MCP Server will automatically start and connect

Usage

Once configured, you can use the MCP Client to interact with Unity directly through their chat interface.

Features

• Bidirectional Communication: Seamlessly send and receive data between Unity and LLMs.
• Asset Management: Import assets, instantiate prefabs, and create new prefabs programmatically.
• Scene Control: Open, save, and modify scenes, plus create and manipulate game objects.
• Material Editing: Apply and modify materials with ease.
• Script Integration: Create, view, and update C# scripts within Unity.
• Editor Automation: Automate Unity Editor tasks like building projects or entering play mode.

Troubleshooting

Encountering issues? Here are some common fixes:

• Unity Bridge Not Running

  • Ensure the Unity Editor is open and the MCP window is active. Restart Unity if needed.

• Python Server Not Connected

  • Verify the Python server is running (python server.py in the Python directory).
  • Check config.json for correct port settings (default: unity_port: 6400, mcp_port: 6500).
  • Ensure uv and dependencies are installed correctly.

• Configuration Issues with Claude Desktop or Cursor

  • Confirm the paths and settings in the configuration dialog match your tool's installation.

How to add this MCP server to Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > MCP and click "Add new global MCP server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "cursor-rules-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "cursor-rules-mcp"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explictly ask the agent to use the tool by mentioning the tool name and describing what the function does.