# CoderGamester/mcp-unity: an MCP server that lets Cursor and Claude Code drive the Unity Editor

> mcp-unity is an MIT-licensed Unity package plus a Node.js MCP server that exposes scene, GameObject, component, package and test operations to AI coding agents. It is a tooling bridge, not a runtime library, and its limits are the limits of the Unity Editor's main thread.

**CoderGamester/mcp-unity** — Model Context Protocol (MCP) plugin to connect with Unity Editor — designed for Cursor, Claude Code, Codex, Windsurf and other IDEs

- Repository: https://github.com/CoderGamester/mcp-unity
- Stars: 1,919 · Forks: 245
- Language: C#
- License: MIT
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/codergamester-mcp-unity

## The gap mcp-unity fills between an AI agent and the Unity Editor

An AI coding assistant working in a Unity project can read and write C# files, but it cannot see the scene. It does not know which GameObjects exist, what components they carry, what the console printed, or whether the EditMode tests pass. Everything it produces is a guess about a project state it cannot observe.

mcp-unity closes that gap. It is a Model Context Protocol implementation for the Unity Editor, and the README describes it as "a bridge between Unity and a Node.js server that implements the MCP protocol." The audience is narrow and specific: developers who already run an MCP-capable host such as Cursor, Windsurf, Claude Code, Codex CLI, GitHub Copilot, Google Antigravity or OpenCode, and who want that host to execute operations inside the Editor. If you do not use an MCP client, the package has nothing to offer you.

The design choice worth noting is where the intelligence lives. The Unity package does not parse natural language. It registers tools and executes them. The Node.js server speaks MCP, and the agent decides what to call. That split keeps the C# side small and testable, and it means the tool surface is the product.

## How the Unity package and the Node.js MCP server talk to each other

The repository layout makes the architecture visible. Editor/ holds the C# side that runs inside Unity. Server~/ holds the Node.js MCP server, kept outside the compiled package by the tilde suffix. The root package.json declares the Unity package as com.gamelovers.mcp-unity, version 1.5.0, with a minimum Unity version of 2022.3 and three dependencies: com.unity.nuget.newtonsoft-json 3.2.1, com.unity.editorcoroutines 1.0.0 and com.unity.test-framework 1.3.3.

Those dependencies hint at what the Editor side does. Newtonsoft.Json serialises tool arguments and results. EditorCoroutines lets work run across Editor frames without blocking a single call. The test framework dependency exists because run_tests drives the Unity Test Runner. The declared mcpname is io.github.codergamester/mcp-unity.

On the tool side, the README lists operations grouped by what they touch: scene operations (create_scene, load_scene, unload_scene, delete_scene, save_scene, get_scene_info), GameObject operations (select_gameobject, update_gameobject, get_gameobject, add_asset_to_scene, create_prefab), component and package operations (update_component, add_package), plus run_tests, recompile_scripts, send_console_log and get_console_logs. The README gives example prompts for each, such as "Add a Rigidbody component to the Player object and set its mass to 5" for update_component. Note the semantics: update_component adds the component if the GameObject does not already contain it, and update_gameobject creates the GameObject if it does not exist. Those are upserts, not strict updates, and an agent that assumes otherwise will get surprising results.

## Installing mcp-unity and running a first scene query

The README does not spell out package installation steps in the text available, so the reliable starting point is the repository itself: the project is distributed as a Unity package (com.gamelovers.mcp-unity) with a Node.js server under Server~. You need Unity 2022.3 or newer, per package.json, and a Node.js runtime, which the README badges as a requirement.

Once the package is present and the Editor-side bridge is open, the agent host needs an MCP server entry. The exact server command and arguments come from the repository's server directory, so read the files under Server~ rather than copying a command from a blog post. A generic MCP client entry looks like this, with the command taken from that directory:

```json
{
  "mcpServers": {
    "mcp-unity": {
      "command": "node",
      "args": ["path/to/Server~/build/index.js"]
    }
  }
}
```

After the client reconnects, its tool list should include the names above: get_scene_info, get_gameobject, run_tests and the rest. A first useful call is a read, not a write. Ask the agent what scenes are loaded, which maps to get_scene_info, and check that the answer matches the Editor's own hierarchy. Then ask for the details of a single GameObject by name, which maps to get_gameobject. If those two return real project data, the bridge is wired correctly and you can move on to mutations such as update_gameobject or add_asset_to_scene.

One packaging detail matters for day-to-day work. The README states that mcp-unity adds the Unity Library/PackedCache folder to VSCode-like workspaces (Visual Studio Code, Cursor, Windsurf, Google Antigravity) so code intelligence and autocompletion improve for Unity packages. That is a workspace mutation performed by the package, not something you configure by hand.

## Where mcp-unity breaks down: Editor-bound, upsert semantics and a thin README

The first limitation is structural. The bridge runs inside the Unity Editor, so the Editor must be open, the project loaded, and the MCP bridge active for any tool call to succeed. That rules out headless CI usage. If you want an agent to compile and test a Unity project on a build machine with no GUI, this is the wrong tool, and the README does not document a headless mode.

The second is the upsert behaviour described above. update_gameobject creates a GameObject when the path does not match, and update_component adds a component when it is missing. For an agent this is convenient, because a single call either fixes or creates state. For a human reviewing the diff, it means a typo in a GameObject name silently produces a new object rather than an error. There is no documented dry-run flag in the README.

The third is documentation depth. The README is a tool catalogue with example prompts. It does not document rollback, concurrency behaviour when two agents call tools at once, or what happens if the Editor is mid-recompile when a call arrives. recompile_scripts exists as a tool, which implies the agent can trigger a domain reload while other calls may be pending, but the README does not describe how that is serialised. Treat concurrent agent sessions against one Editor as unverified territory.

## mcp-unity compared with other Unity MCP bridges

The related searches show people comparing mcp-unity against Ivanmurzak/Unity-MCP and against a project referred to as Coplay MCP Unity. The README covers only mcp-unity, so the honest comparison is about approach rather than a feature table.

What distinguishes mcp-unity in its own documentation is the two-process split: a C# Editor package that registers and executes tools, and a separate Node.js MCP server that speaks the protocol. That means the Node.js side can be inspected, replaced or run on a different machine from the Editor, and the C# side stays focused on Unity APIs. The trade-off is an extra runtime to install and keep in sync with the package version. A single-process bridge embedded entirely in C# would avoid the Node.js dependency but would tie the protocol implementation to the Editor's lifecycle.

The other distinguishing choice is breadth over depth. mcp-unity exposes scene, GameObject, component, package, prefab, asset, console and test operations, roughly twenty tools. That is a wide surface for an agent to reason over. A narrower bridge with five well-specified tools would be easier for a model to use correctly but would cover less of the Editor. Neither is objectively better; it depends on whether you want the agent to do asset wiring or just scene inspection.

## Licence, versioning and what an upgrade actually costs

mcp-unity is MIT licensed, both in the repository metadata and in package.json. MIT is permissive: you can use, modify and redistribute it, including in commercial projects, provided the copyright notice and permission notice travel with it. That is a statement about the licence text, not legal advice for your situation.

The maintenance signal is straightforward. The repository is not archived, and the last push was on 2026-09-03, the same day release 1.5.0 was published. Before that, 1.4.0 landed on 2026-07-24 and 1.3.0 on 2026-04-26. The cadence is roughly every two to three months across those three releases, with two of them within about six weeks of each other.

Upgrade cost is dominated by the version coupling. The Unity package version in package.json and the Node.js server under Server~ are released together, and the MCP tool names are the contract between them. If you pin the package to 1.5.0 but run an older server build, tool calls can fail on argument shape. Pin both. The declared Unity floor of 2022.3 and the three package dependencies (Newtonsoft.Json 3.2.1, EditorCoroutines 1.0.0, Test Framework 1.3.3) are the other upgrade constraints: bumping the Unity floor in a future release would lock out older projects, and the README does not state a policy on that.

## Conclusion

Adopt mcp-unity if you already drive Unity from Cursor, Claude Code, Codex CLI, Windsurf, Copilot, Google Antigravity or OpenCode and you want the agent to reach into scenes, GameObjects, components and the Test Runner instead of only editing text files. Skip it if your project is still on a Unity version below 2022.3, or if you need unattended CI automation, because the bridge depends on a running Editor with its MCP bridge window open. Verify first that your Unity version meets the package.json floor, that the Node.js server starts and registers, and that your agent's MCP client actually lists the tools after configuration.

## FAQ

### What is Unity MCP?

In this project it is an implementation of the Model Context Protocol for the Unity Editor, distributed as the Unity package com.gamelovers.mcp-unity plus a Node.js MCP server. It lets MCP-capable AI hosts execute Editor operations and request Editor information.

### Does Unity have an MCP?

Unity itself does not ship one as part of the Editor based on the README. mcp-unity is an MIT-licensed package that adds an MCP bridge to the Editor, with a minimum supported Unity version of 2022.3.

### Is Unity MCP free?

mcp-unity is released under the MIT licence, so the package and its server can be used and modified without a fee. The licence text is in the repository as LICENSE.md.

### How do I use mcp-unity?

Install the Unity package into a project on Unity 2022.3 or newer, run the Node.js MCP server from Server~, and register that server in your MCP client. The agent can then call tools such as get_scene_info, update_gameobject, update_component and run_tests.

### What is mcp-unity?

It is a Model Context Protocol implementation for the Unity Editor that provides a bridge between Unity and a Node.js server implementing MCP. Through that bridge, AI agents like Cursor, Windsurf, Claude Code, Codex CLI, GitHub Copilot, Google Antigravity and OpenCode can execute operations inside the Editor.

### Does mcp-unity work with VS Code?

The README lists Visual Studio Code among the VSCode-like IDEs that receive automatic integration, by adding the Unity Library/PackedCache folder to the workspace. That integration improves code intelligence and autocompletion for Unity packages.

## Sources

- [CoderGamester/mcp-unity on GitHub](https://github.com/CoderGamester/mcp-unity)
- [Issues](https://github.com/CoderGamester/mcp-unity/issues)
- [License: MIT](https://github.com/CoderGamester/mcp-unity/blob/main/LICENSE)
- [README](https://github.com/CoderGamester/mcp-unity/blob/main/README.md)
- [Releases](https://github.com/CoderGamester/mcp-unity/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/codergamester-mcp-unity