Installing Unity MCP

Pick one server — see the comparison if you have not yet. Install that one only. Running both against one project causes conflicting Editor writes.

Option A: the official relay

Requires Unity 6.3 or newer. Verified here on Unity 6000.3.14f1 with com.unity.ai.assistant 2.17.0-pre.1.

1. 1
   Install the AI Assistant package

   In Unity: Window → Package Manager → Unity Registry, search for AI Assistant, install. It appears in your manifest as com.unity.ai.assistant.

2. 2
   Sign in to your Unity account

   The assistant features require it. If the panel shows a sign-in prompt, that step is not optional.

3. 3
   Confirm the relay binary exists

   The package drops a relay into your user folder. If this prints a version, the server half is ready.

   bash Copy

   12345678910

   # Windows
   %USERPROFILE%\.unity\relay\relay_win.exe --version
   
   # macOS / Linux
   ~/.unity/relay/relay --version
   
   # Expected output
   # Unity AI Relay
   # Name: unity-ai-relay
   # Version: 1.0.12-build.97

   10 lines
4. 4
   Add it to your client

   One entry, pointing at that binary with the --mcp flag. Client-specific files are in the next three chapters.

   json Copy

   1234567

   {
     "unity-mcp": {
       "command": "C:\\Users\\you\\.unity\\relay\\relay_win.exe",
       "args": ["--mcp"],
       "env": {}
     }
   }

   7 lines
5. 5
   Leave the Unity Editor open

   The relay talks to a running Editor. With Unity closed, tools fail regardless of how healthy the client looks.

Option B: the community server

Works from Unity 2021 onward. Two halves, and both are required — this is where most failed setups go wrong.

1. 1
   Install uv

   uvx runs the Python server without you managing a virtualenv. Install it once, globally.

   bash Copy

   12345678

   # Windows (PowerShell)
   powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
   
   # macOS / Linux
   curl -LsSf https://astral.sh/uv/install.sh | sh
   
   # Verify
   uvx --version

   8 lines
2. 2
   Install the Unity-side package

   In Unity: Window → Package Manager → + → Add package from git URL, then paste the MCP for Unity repository URL from its README. Do not skip this. Without it the server has nothing to talk to.

3. 3
   Confirm the Unity window appears

   The package adds an MCP window to the Editor menus showing connection status. If that window is missing, the package did not install.

4. 4
   Add the server to your client

   Pin the version so a background update cannot change your tooling mid-project.

   json Copy

   1234567891011

   {
     "unityMCP": {
       "type": "stdio",
       "command": "C:\\Users\\you\\.local\\bin\\uvx.exe",
       "args": [
         "--from", "mcpforunityserver==10.0.0",
         "mcp-for-unity",
         "--transport", "stdio"
       ]
     }
   }

   11 lines
5. 5
   Check the Unity window says connected

   Start your client, then look at the MCP window in Unity. It should report a live connection. This is the check that actually matters.

Verify end to end

A green light in your client only proves the server process started. It says nothing about Unity. Prove the whole chain with a question the model could not possibly answer from training data:

What scene is currently open in my Unity project,
and how many assets are in it?

A real answer naming your actual scene means all three pieces are talking. A generic answer, an apology, or an error means the Unity half is not connected.

When it does not work

What to take away

• Install one server, not both.
• The official relay needs Unity 6.3 and the AI Assistant package.
• The community server needs uv and a Unity-side package.
• Windows JSON paths need double backslashes.
• Verify by asking something only your open project could answer.