The Problem

Unity developers who want AI‑driven assistants (Cursor, Claude Code, Windsurf, etc.) need a reliable bridge that exposes editor actions (scene loading, asset creation, component updates) through a network API. Without a standard protocol, each IDE must implement its own ad‑hoc scripts, leading to fragile integrations and duplicated effort.

What This Does

mcp-unity implements the Model Context Protocol (MCP) for the Unity Editor. The Unity side lives under Editor/ and consists of C# resources (e.g., Editor/Resources/GetGameObjectResource.cs) and tools (e.g., Editor/Tools/MaterialTools.cs). These classes expose editor commands and forward them over a WebSocket to a Node.js server located in Server~/src/.

Key files:

  • Server~/src/index.ts – entry point that creates the HTTP/Express server and registers the MCP routes.
  • Server~/src/unity/mcpUnity.ts – core wrapper that sends/receives JSON messages to the Unity socket.
  • Server~/src/utils/logger.ts and Server~/src/utils/errors.ts – shared utilities imported by 36–37 other modules, forming the stability hub of the codebase.

The plugin automatically adds the Unity Library/PackedCache folder to the IDE workspace, giving editors full type information for Unity packages.

How It Is Wired

  1. Startup – Execution begins at Server~/src/index.ts. It imports the logger, error helpers, and the MCP controller (mcpUnity.ts). The file constructs an Express app, applies JSON middleware, and mounts route handlers from the resources/ folder.
  2. Request handling – A client (e.g., a Cursor extension) POSTs to /api/getGameObject. The route handler (Server~/src/resources/getGameObjectResource.ts) parses the payload and calls mcpUnity.executeCommand(...).
  3. Unity bridge – mcpUnity.ts serialises the command and forwards it via a WebSocket managed by Editor/UnityBridge/McpUnitySocketHandler.cs in the Unity editor process.
  4. Editor execution – The Unity side receives the message, maps the command name to a concrete C# tool (e.g., Editor/Tools/GetGameObjectTool.cs), executes the Unity API (scene loading, component update), and returns a JSON result.
  5. Response – mcpUnity.ts resolves the promise, the resource handler formats the response, and Express sends it back to the caller.

The import graph shows no circular dependencies and 44 internal modules with 142 import edges. The three most‑connected modules are utils/errors.ts (37 inbound imports), utils/logger.ts (36 inbound), and unity/mcpUnity.ts (31 inbound, 4 outbound). Their high “blast radius” means changes here can affect the majority of the codebase.

How To Use It

# Clone the repository
git clone https://github.com/moses-y/mcp-unity.git
cd mcp-unity

# Install server dependencies (Node.js 18+ required)
npm install               # runs in the repository root; Server~/package.json is used

# Option 1 – Run locally with ts-node (if installed)
npx ts-node Server~/src/index.ts

# Option 2 – Build and run the Docker image
docker build -t mcp-unity -f Server~/Dockerfile .
docker run -p 3000:3000 mcp-unity

The Unity side automatically loads when the Unity Editor opens the project (the Editor/ folder is a standard Unity package). No additional configuration files are required beyond the default Unity settings.

Real‑World Use

A CI pipeline for a game studio can start the Node server in a container, then let a developer’s IDE issue commands like “create a prefab for a new enemy” via the MCP endpoint. The server forwards the request to the open Unity instance, which creates the prefab instantly, allowing the developer to continue coding without manually opening Unity menus.

Code Health & Issues

  • HIGH – Commit a lockfile beside the manifest – package.json exists without a corresponding lockfile.
  • HIGH – Add a workflow that builds and tests this repository – 91 source files, no CI configuration.
  • HIGH – Add a build gate for the deployable artifacts – Server~/Dockerfile is present but never validated by CI.
  • MEDIUM – Enable Dependabot or Renovate – two manifest files (package.json, Server~/package.json) lack automated dependency updates.
  • MEDIUM – Pin the container base image by digest – Dockerfile uses mutable tags node:18-alpine.
  • LOW – Add repository convention files – missing .editorconfig, .gitattributes, and formatter config.

Additional observations: tests are present (Server~/src/__tests__/*.test.ts and Editor/Tests/*.cs), but no CI runs them. The repository includes a license (LICENSE.md) and a Dockerfile, but lacks CI pipelines and a lockfile, exposing the build to non‑reproducible dependency versions.

The Bottom Line

mcp-unity delivers a functional MCP bridge that lets AI assistants manipulate Unity projects through a clean WebSocket/HTTP API. The codebase is well‑structured with clear separation between server logic and Unity tools, but the absence of a lockfile, CI pipelines, and pinned Docker bases makes production deployments riskier. Teams comfortable managing their own CI can adopt it quickly; organizations seeking out‑of‑the‑box reproducibility should first add the recommended health fixes.