cqbase.net · English & Chinese

CQBase

Context & Query Base

MCP

Unity MCP

A bridge between an AI assistant and the Unity Editor, so a model can manage assets and control a scene.

CoplayDev/unity-mcp is MIT licensed. It is an MCP bridge between an AI assistant and the Unity Editor, so a model can manage assets and control a scene. It talks to a running editor, not only to text files in a repository.

Try it in a disposable project and keep a copy of the scene. If the agent can change scenes and assets, it can also break the project layout. Do not enable writes on an unbacked release branch.

Mentioned by:

  • @HermesWatcher mentioned this project on 27 October 2026 (1149 likes and 126 reposts, captured 15 November 2026).
  • @skizzyy2 mentioned this project on 12 November 2026 (20 likes and 0 reposts, captured 15 November 2026).

This page is a guide, not the original text.

What problem it solves

Unity MCP (repository CoplayDev/unity-mcp, also called MCP for Unity in the docs) is a bridge between an MCP client and a running Unity Editor. An agent can manage assets, control a scene, edit scripts, and run tests, rather than only editing text files in a repository.

Official docs describe three layers: the MCP client, a Python server in the middle, and a C# plugin inside the Editor. The client does not talk to the Unity process directly. The tool count is not identical across official sources. The repository README says “48 focused MCP tool entrypoints.” The documentation homepage says “50 tools.” This page does not invent a single number.

Who it is for

It is for people already on Unity 2021.3 LTS through 6.x who want Claude Desktop, Claude Code, Cursor, VS Code, or another MCP client to drive the Editor. The project is MIT-licensed. Official docs describe it as a free open-source tool, and it is not affiliated with Unity Technologies.

It changes scenes and assets in a running Editor. Try it in a disposable project and keep a copy of the scene. Do not enable writes on an unbacked release branch.

How to install it

Checked on 15 November 2026 (Asia/Shanghai) against the repository README and the official Install page.

You need Unity 2021.3 LTS or newer, Python 3.10 or newer, and uv. The setup wizard can guide you through the last two if they are missing.

In Unity, open Window → Package Manager, click +, choose Add package from git URL..., and paste:

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

That path needs git on the PATH that Package Manager uses. You can also install with OpenUPM:

openupm add com.coplaydev.unity-mcp

Official docs also describe an Asset Store path. After import, a setup wizard appears. Confirm Python and uv, pick the MCP clients to configure, and click Configure Selected. You can return later via Window → MCP for Unity to start or stop the server, switch between HTTP and stdio, and check that the status reads Connected.

Claude Desktop

Official docs say Claude Desktop supports stdio only. MCP for Unity will silently configure it that way even if you selected HTTP elsewhere. After auto-configuration it usually connects on the next launch. If you need a manual config, the official macOS / Linux example is:

{
  "mcpServers": {
    "unityMCP": {
      "command": "uvx",
      "args": ["--from", "mcpforunityserver", "mcp-for-unity", "--transport", "stdio"]
    }
  }
}

On Windows, the official example uses the full path to uvx, such as C:/Users/YOUR_USERNAME/AppData/Local/Microsoft/WinGet/Links/uvx.exe, with the same arguments.

Cursor

The wizard can write the config, but official docs are explicit: after auto-configuration you still have to enable the unityMCP toggle in Cursor’s own Settings → MCP. HTTP is the default transport for these IDE clients. A manual entry looks like this:

{
  "mcpServers": {
    "unityMCP": {
      "url": "http://localhost:8080/mcp"
    }
  }
}

Claude Code and VS Code

Official docs say Claude Code, VS Code, Windsurf, Cline, and several CLI clients auto-connect after configuration. The default HTTP URL is http://localhost:8080/mcp. VS Code’s manual config goes under servers, not mcpServers, and needs "type": "http".

A worked example

The prompt below comes from the First prompt section on the official Install page. It is a check, not a guaranteed result. It was not run in Unity for this review, so this page does not invent objects in the scene.

  1. Finish the install in a disposable project. Confirm Window → MCP for Unity shows Connected, and that unityMCP is enabled in the client.
  2. Save a copy of the current scene, then send: Create a red, a blue, and a yellow cube in the current scene.
  3. Return to the Editor and check whether three cubes appeared, whether the colors match the request, and whether anything else in the scene changed. If the result is wrong, restore from your copy before you debug further.

Common pitfalls

  • The Package Manager reports that it cannot execute git. Official docs require git on the PATH that Package Manager can see, and they point this class of error at the troubleshooting notes.
  • The status panel says uv is missing, or the server never starts. Check uv --version in a terminal. Unity launched from Finder on macOS often does not inherit your shell PATH. Official docs suggest setting the uv location in the MCP window; see Install or Repair uv + Python.
  • Cursor looks configured, but the tools never appear. Official docs say Cursor still needs its own MCP toggle after auto-configuration.
  • After you switch between HTTP and stdio, the client reports no Unity instances. The official uv troubleshooting page recommends restarting the client so it reloads the config.
  • On Windows, the wizard says Python is missing even though python --version works in a terminal. Issue #1324 recorded Microsoft Store execution aliases shadowing a real interpreter (that issue was closed on 2 October 2026; if you still see it, compare your current version with that discussion).

FAQ

Do I need a paid Unity or MCP account?

MCP for Unity itself is free under MIT. You need a Unity version that matches the docs, Python, uv, and an MCP client. The client, such as Claude Code, may have its own account requirements. The same maintainers also offer a paid assistant called Aura. That is a different product; do not confuse it with this open-source bridge.

Can Claude Desktop use HTTP?

Official docs say no. Claude Desktop supports stdio only, and the plugin will configure it that way even if you selected HTTP in the MCP for Unity window.

What is the default HTTP URL?

The official Install page gives http://localhost:8080/mcp. If the client cannot connect, confirm in Window → MCP for Unity that the server is running, and that the URL in the client config matches.

Can I use several Unity Editors at once?

Official docs describe multi-instance routing in Multi-Instance Routing. This page did not run a multi-instance setup. Follow that guide for the switching details.

What if auto-configuration fails?

Use the “Manual MCP client configuration” snippets on the Install page. Claude Desktop uses stdio. Cursor, VS Code, and similar clients default to HTTP. The Windows stdio example needs the full path to uvx.

Sources and license

CoplayDev/unity-mcp is licensed under MIT. This page follows the README, Install, Choosing an MCP Client, and the uv troubleshooting guide as of 15 November 2026, rewritten for CQBase — Context & Query Base. If the install URL, transports, or client toggles change, follow those official pages.

Subscribe to CQBase Weekly

One email a week with newly catalogued public AI skills, prompts, MCP servers, and methods. Unsubscribe at any time. We will not hand your address to a third party for their marketing.