Unity MCP Setup: Connect Claude Code or Cursor to the Unity Editor via the AI Assistant Package

Unity MCP setup through the AI Assistant package lets an external coding agent such as Claude Code or Cursor work inside the Unity Editor. According to Unity's get-started page, the process is: confirm the Unity bridge is running, configure your client, approve the connection in Unity, then test it. This guide takes those steps in order and adds what the docs spread across sections: a prerequisites checklist, a table of relay paths for each platform, and a failure checklist.

One caveat first. The page this guide is based on is for package version 2.7.0-pre.3, which is a pre-release. Menu names, tool names and settings may change before a stable release, so check the current docs if a menu doesn't match.

What is Unity MCP, and who is it for?

The get-started doc describes Unity MCP as a way for external AI clients to control the Unity Editor through the Model Context Protocol (MCP). Unity runs a bridge inside the editor. A small relay program connects your AI client to that bridge.

Based on the docs, it fits solo developers who already do most of their coding in an external agent and want that agent to read the console, inspect scenes or edit GameObjects without copying and pasting. If you only use the built-in Assistant chat window, it adds little, because that path already connects through Unity's AI Gateway.

For how the same idea works in another engine, see our godot-ai MCP server walkthrough.

What do you need before you start?

The get-started page lists these requirements:

• Unity 6 (6000.0) or later. Older editor versions are not covered.
• The com.unity.ai.assistant package installed in your project.
• An MCP-compatible client. The doc names Claude Code, Cursor, Windsurf and Claude Desktop.

The get-started page does not cover pricing, Unity account tiers or AI credit requirements. Check the wider AI Assistant package docs for those before you plan a workflow around this feature.

A practical addition that the doc does not mention: put the project under version control and commit before you connect an agent. That gives you an easy way to undo anything the agent changes in a scene.

Step 1: How do you confirm the Unity bridge is running?

1. Open your project in Unity 6.
2. Go to Edit > Project Settings > AI > Unity MCP Server.
3. Check the Unity Bridge status. According to the doc, it should show Running in green, and it starts on its own when the editor loads.
4. If it shows Stopped, select Start.

The doc also says Unity installs a relay binary to ~/.unity/relay/ on startup. AI clients launch this relay to reach the editor. You need its exact path for manual configuration in the next step.

Step 2: How do you configure Claude Code or Cursor?

The docs offer two routes.

Automatic route

1. On the same Unity MCP Server settings page, expand Integrations.
2. Select your client.
3. Select Configure.

This writes the client configuration for you. Per the docs, it is the shorter path, and it avoids the path mistakes covered below.

Manual route

If you prefer to edit the configuration yourself, or your client isn't in the Integrations list, add an mcpServers entry named unity-mcp. The doc shows the same JSON for Claude Code and Cursor. In Cursor, it goes under Cursor Settings > MCP. Here is the doc's macOS Apple Silicon example, with yourname standing in for your user folder:

{
  "mcpServers": {
    "unity-mcp": {
      "command": "/Users/yourname/.unity/relay/relay_mac_arm64.app/Contents/MacOS/relay_mac_arm64",
      "args": ["--mcp"]
    }
  }
}

The doc gives two rules for this entry:

• Use a full absolute path. Some clients may not expand the tilde (~), so ~/.unity/relay/... can fail even though it works in a terminal.
• Keep the --mcp argument. It switches the relay into MCP server mode.

Relay paths by platform

The doc's JSON example uses only the macOS ARM path, so Windows, Intel Mac and Linux users have to swap in their own. All the binaries sit under .unity/relay in your home folder:

In the config file, replace ~ or %USERPROFILE% with the real path to your home folder. On Windows, JSON syntax also requires each backslash to be doubled, for example C:\\Users\\yourname\\.unity\\relay\\relay_win.exe.

Step 3: How do you approve the connection in Unity?

The docs say that a client connecting for the first time triggers a Pending Connection message in Unity. To approve it:

1. Go back to Edit > Project Settings > AI > Unity MCP Server.
2. Under Pending Connections, review the client's details.
3. Select Accept or Deny.

The client can't call any tools until you accept it. According to the doc, clients you have already approved reconnect automatically, and connections from Assistant through the AI Gateway are approved automatically.

This approval step is the main security gate. Once you accept, an external agent can act on your open project. Two habits follow from that. Read the client details before you accept, and deny anything you don't recognize. Commit your work before you let an agent edit scenes. For keeping an agent's standing instructions tidy once it has this kind of access, see our note on Claude Code's /doctor prompt audit.

Step 4: How do you know it worked?

The doc gives two signs of a working connection:

• The client appears under Connected Clients on the Unity MCP Server page.
• The client lists Unity tools, such as Unity_ManageScene and Unity_ManageGameObject.

For a first test, the doc suggests asking the client to read the Unity console and summarize warnings or errors. The client may use the Unity_ReadConsole tool to do this. A prompt along these lines works:

Read the Unity console and summarize any warnings or errors, grouped by type.

A read-only test like this is a sensible first step because it proves the connection works without changing anything. Save prompts that edit scenes or GameObjects until you've seen the console test succeed and have a fresh commit.

How do you target one Unity editor when several are open?

By default, the doc says, the relay connects to the first editor instance it finds. That's fine with one project open. With two or more, the agent could attach to the wrong one.

The doc lists two ways to choose an editor:

• Command-line arguments: --project-path <path> or --instance-id <pid>
• Environment variables: UNITY_PROJECT_PATH or UNITY_INSTANCE_ID

If both are set, the command-line argument takes precedence.

Using arguments:

{
  "mcpServers": {
    "unity-mcp": {
      "command": "/Users/yourname/.unity/relay/relay_mac_arm64.app/Contents/MacOS/relay_mac_arm64",
      "args": ["--mcp", "--project-path", "/Users/yourname/Projects/MyGame"]
    }
  }
}

Using an env block:

{
  "mcpServers": {
    "unity-mcp": {
      "command": "/Users/yourname/.unity/relay/relay_mac_arm64.app/Contents/MacOS/relay_mac_arm64",
      "args": ["--mcp"],
      "env": {
        "UNITY_PROJECT_PATH": "/Users/yourname/Projects/MyGame"
      }
    }
  }
}

A project path is easier to manage than an instance ID. An instance ID is a process ID, so it is likely to change each time the editor restarts.

What if it doesn't connect? A failure checklist

The table below maps common symptoms to the documented step most likely to fix them. It is built from the get-started steps and does not replace Unity's own troubleshooting guide.

For bridge problems this table doesn't cover, the get-started page links to Unity's Troubleshoot Unity MCP bridge issues page. Start there.

The get-started page also links to a guide on registering custom MCP tools. That's the next step if you want the agent to run studio-specific editor actions beyond the built-in tools. If you're putting together a broader toolkit for agents, our look at the Awesome Gamedev Agent Skills pack covers a different approach to adding engine knowledge.

Verdict: is Unity MCP setup worth it?

Based on the documentation, setup is short: check the bridge, configure the client, approve the connection, test. The Integrations > Configure button handles most of the manual JSON. Manual setup mostly comes down to getting the absolute relay path right for your platform.

The caveats are real. The docs are for a pre-release version (2.7.0-pre.3), so steps may change. Only Unity 6 and later is supported. And once you accept a connection, an outside agent has real access to your editor, which is why the approval step and version control matter.

If you already work in Claude Code or Cursor on a Unity 6 project, this looks worth the few minutes it takes. If you're on an older Unity version or happy with the built-in Assistant chat, you can wait for a stable release. For related coverage, see our Unity guides and coding agents pages.