Unity MCP setup guide: let Claude Code drive the Editor and check screenshots with Unity CLI or MCP for Unity

Translated from the original Traditional Chinese version.

Summary

The MCP server built into Unity’s AI Assistant package is deprecated, and Unity now points to the free Unity CLI instead. Claude Code can run terminal commands, so it can drive the Editor with Unity CLI commands. Clients that can only call MCP tools connect to the MCP server built into Unity CLI, and projects on a version older than Unity 6 can use the community MCP for Unity package. All three setups let an agent build a scene, write a script, and capture the Game view to check the result.

Table of contents

Unity’s AI Assistant package includes an MCP (Model Context Protocol) server. It lets an AI agent such as Claude Code work inside a running Unity Editor, where the agent can build a scene, change components, enter Play Mode, and take a screenshot to check the result. On November 6, 2026, Unity marked this MCP server as deprecated and replaced it with Unity CLI. Unity CLI is free and does not need a Unity AI subscription. MCP for Unity, a separate package maintained by the community, is not affected.

After I installed Unity’s official plugin for Claude Code, I described what I wanted in plain language: an orange cat that spins. Claude Code then created a scene in the open Unity Editor, built the cat from primitive shapes, wrote a rotation script, entered Play Mode, took a screenshot, and looked at it to confirm the cat was on screen before it reported back. The Editor stays open the whole time, so every object Claude Code creates shows up in the Hierarchy and you can take over at any point.

I tested on Windows 11 with Unity 6000.6.9f1, Unity CLI 1.0.0, MCP for Unity 10.3.0, and Claude Code 2.1.309 running the Sonnet model.

Choose a setup

Pick the setup that matches your situation:

Situation What to do
Claude Code is already connected to the AI Assistant package’s MCP Remove the old entry and switch to Unity CLI
Your agent can run terminal commands, for example Claude Code Use unity command
Your client can only call MCP tools and cannot run terminal commands Use unity mcp
Your project is still on Unity 2021.3 or 2022.3 Unity CLI needs Unity 6.0 or later to drive the Editor, so use MCP for Unity

All three setups end at a package inside the Unity Editor: the Pipeline package for Unity CLI, or MCP for Unity’s own package. They differ in which program the agent’s requests pass through:

Connection paths for the three setups: unity command and unity mcp go through Unity CLI to the Pipeline package, MCP for Unity goes through its Python server to its own package, and the deprecated relay_win.exe goes to the AI Assistant package

Remove the AI Assistant package’s MCP entry

If you used the AI Assistant package’s MCP, Claude Code’s MCP list has an entry that runs relay_win.exe --mcp. The name in Unity’s documentation is unity-mcp. Run claude mcp list in your project folder to find the entry, then remove it by name:

1claude mcp remove --scope user unity-mcp

If you added the entry to a single project, run the command in that project folder and change user to local. If it lives in the project’s .mcp.json, change it to project. unity mcp configure has a --replace-legacy option, but for Claude Code it only prints the removal command above and does not remove anything.

If you want to keep the package and the AI Assistant window in the Editor, update the package to 2.13 or later. Older versions conflict with Unity CLI.

Set up Unity CLI

To install Unity CLI and sign in, see the Unity CLI install guide. Open the project in Unity 6.0 or later and keep it on an NTFS drive. If the project sits on a ReFS Dev Drive, Unity CLI cannot reach the Editor. The symptom is listed under Troubleshooting.

Install the Pipeline package

Unity CLI drives the Editor through the Pipeline package inside it. For an existing project, install the package from the terminal first:

1unity pipeline install --project-path C:\UnityProjects\CatCli

Projects created with unity projects create already include the package, and the command reports alreadyInstalled as true.

Check that the Editor is connected

After the package is installed, open the project with unity open. When the Editor finishes loading, run unity status. A ready state means Unity CLI can drive this Editor. You can take a Game view screenshot yourself to confirm that unity command works:

1unity status --project-path C:\UnityProjects\CatCli
2unity command capture game_view --output-path Screenshots/cat.png

A relative screenshot path starts from the project folder:

The terminal shows the Unity Editor state as ready, then capture game_view saves a 1280x720 screenshot

Run unity command with no arguments to list every command group, such as scene, gameobject, script, and capture. Add a group name to list its commands and parameters.

Install the Unity plugin

Once the commands work, install Unity’s official plugin so Claude Code knows how to combine them:

1unity setup claude

You are done when claude plugin list shows unity@claude-plugins-official as enabled. The unity-cli skill in the plugin tells the agent to use unity command, not the MCP server, when it can run terminal commands.

Set up unity mcp

When your client cannot run terminal commands, use unity mcp instead. It is the MCP server built into Unity CLI, and it also drives the Editor through the Pipeline package, so the steps for installing the Pipeline package and checking the connection still apply. Then add it to Claude Code:

1unity mcp configure claude-code

The command runs claude mcp add and adds a server named unity-editor-mcp at user scope, so every project sees it. When it finishes, run claude mcp get unity-editor-mcp and check that the status is Connected:

The terminal shows unity-editor-mcp with User config scope, Connected status, and the arguments mcp –tool-groups

The default --tool-groups option merges each command group into one tool, which cuts the tool count from 199 to 44. If you have several projects open, add --project-path to configure to pick the one to drive. Run unity mcp configure --list for the names of other clients.

If Claude Code also has the Unity plugin installed, the agent may follow the skill and switch to unity command. That happened once in my tests. After I blocked Claude Code from running terminal commands, the agent used only the MCP tools.

Set up MCP for Unity

MCP for Unity is an open-source package maintained by Coplay. It supports Unity 2021.3 and later, and its tool list includes tools that Unity CLI lacks, such as generating images and 3D models and working with ProBuilder. Its MCP server is written in Python, so install Python 3.10 or later and the Python package manager uv first.

Install the package

In Package Manager, click the + button in the top-left corner, choose Install package from git URL, enter this URL, and click Install:

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

The #v10.3.0 at the end pins this version. Without the version tag, Package Manager installs the latest version from the main branch. After the install finishes, MCP for Unity appears in the list with Git as its source:

Package Manager lists MCP for Unity 10.3.0 under Packages - Coplay, with Git as the source

Configure Claude Code

After the package installs, the MCP Setup window opens on its own and first checks for Python, uv, and Git:

The system requirements page of MCP for Unity Setup shows green lights for Python 3.15.1, uv 0.13.6, and Git

Click Next. The window lists the MCP clients it found on your computer, all selected by default. To connect only Claude Code, clear the other check boxes and click Configure Selected:

The Configure MCP Clients page with only Claude Code selected

MCP for Unity adds the Claude Code entry for this project only, at local scope. Other projects are not affected. The entry connects to http://127.0.0.1:8080/mcp.

Start the server

The server is not running when setup finishes. Claude Code cannot connect, and claude mcp list shows the UnityMCP connection as refused (ECONNREFUSED). Open Window > MCP for Unity > Toggle MCP Window from the menu and click Start Server. The first time, the window asks whether to start the server in the background. Click Start. When the window shows Session Active, the server is connected to the Editor:

The MCP for Unity window with Transport set to HTTP Local, a Stop Server button next to Local Server, and Session Active (CatCoplay) below

Now run claude mcp list in the project folder. UnityMCP shows Connected. The server does not start on its own after you reopen the Editor, so click Start Server again each time.

Let Claude Code drive the Editor

After you set up Unity CLI or MCP for Unity, keep the Editor open, start Claude Code in the project folder, and tell it what to do and what to check when it finishes:

1The project C:\UnityProjects\CatCli is open in the Unity Editor. Work in this running Editor:
2create the scene Assets/Scenes/Cat.unity, build a sitting orange cat from the built-in primitive shapes,
3and write a script that spins the cat around the Y axis at 45 degrees per second, then attach it.
4After compilation finishes and the Console shows no errors,
5enter Play Mode, take a Game view screenshot, then exit Play Mode and save the scene.

With unity command, Claude Code first loads the unity-cli skill and creates the scene with unity command scene create. It then runs C# several times with unity command script eval to create the objects and the material. After the script compiles, Claude Code enters Play Mode, takes a screenshot with capture game_view, and reads the image to confirm the cat is on screen:

The Game view screenshot Claude Code took, with an orange cat built from spheres, cubes, and a capsule in the center

With unity mcp or MCP for Unity, Claude Code calls MCP tools to create the scene, write the script, and take the screenshot. It also reads the screenshot afterward to confirm the cat is on screen.

Troubleshooting

Symptom Cause Fix
The Console shows Pipeline: Descriptor ... was not written every 15 seconds, followed by icacls could not restrict The project is on a ReFS Dev Drive, and the permissions on the port file cannot be changed Move the project to an NTFS drive
unity command reports that it cannot find a Pipeline instance for the project The Editor is still loading or recompiling scripts Run unity status --until-ready and wait for the Editor to be ready
unity mcp configure reports already exists in user config An entry with the same name already exists Run claude mcp remove --scope user unity-editor-mcp, then configure again
A call through unity mcp fails and the Console shows ObjectDisposedException Recompiling scripts triggers a domain reload, which drops the connection The call succeeded when the agent retried, and the error did not affect the project
An MCP for Unity screenshot fails with resolves outside the Unity project root The screenshot path points outside the project folder Save it inside the project folder, for example Assets/Screenshots

Test notes

Every test used the prompt from “Let Claude Code drive the Editor”, plus a request to save the screenshot to a given path and report whether each step succeeded. I ran unity mcp three times and the other two setups twice each. Before every run, I reset the project to just the default scene, then ran claude -p with the Sonnet model and allowed only the tools that setup needs:

  • unity command: the Unity plugin enabled, unity commands allowed, and no MCP server connected.
  • unity mcp: the Unity plugin enabled, only unity mcp --tool-groups connected, and terminal commands blocked.
  • MCP for Unity: only the MCP for Unity server connected.

The turns, time, and cost in the table come from the claude -p result records. A turn is one round trip in which Claude Code sends a request, runs a tool, and reads the result. Extra tokens at startup is the difference between the input tokens of the first request with and without the setup connected, when the prompt just asks Claude Code to reply “OK”. In each cell, the numbers are listed in run order:

Item unity command unity mcp MCP for Unity
Loaded at startup Unity plugin 44 tools 49 tools
Extra tokens at startup 1,707 965 2,344
Turns 13, 13 44, 34, 24 29, 20
Time to finish 100, 81 seconds 83, 89, 54 seconds 92, 87 seconds
Cost 0.35, 0.33 USD 0.35, 0.59, 0.36 USD 0.34, 0.28 USD
Where screenshots can go Inside or outside the project Inside or outside the project Only inside the project folder
While scripts recompile No errors A call failed in all three runs, and the agent finished after retrying No errors

I checked every screenshot, and each one showed the cat. By default, Claude Code loads only the names of MCP tools and reads the full definitions when it needs them, so connecting an MCP server adds few tokens at startup. With ENABLE_TOOL_SEARCH=false, Claude Code loads every tool definition up front, and startup grows by 21,863 tokens for unity mcp and 45,454 tokens for MCP for Unity.

Summary

If you used the AI Assistant package’s MCP, remove the old entry first, then choose a setup based on whether your client can run terminal commands and which Unity version your project uses. With unity command, Claude Code built the cat and confirmed it with a screenshot within 13 turns in both runs. With unity mcp, recompiling scripts dropped the connection, and Claude Code finished only after retrying.

Further reading

Ted Liou

Ted Liou

Software engineer writing about Unity and AI development.

Comments