MCP Unity Server

## Overview

MCP Unity (v1.3.0, 1.7k+ stars) is the leading open-source MCP server for Unity Editor. It lets AI coding assistants interact with your Unity project in real time via a WebSocket bridge. The server runs as a Node.js process and connects to a Unity Editor package.

Requires **Unity 6+** and **Node.js 18+**.

## Key Tools

| Tool | Purpose |
|---|---|
| `execute_menu_item` | Trigger any Unity menu item |
| `select_gameobject` | Select objects in the hierarchy |
| `update_gameobject` | Create or modify GameObject properties |
| `update_component` | Add/update components and their fields |
| `get_gameobject` | Inspect GameObject with all components |
| `create_prefab` | Create prefabs with optional scripts |
| `create_scene` / `load_scene` / `save_scene` | Scene management |
| `move_gameobject` / `rotate_gameobject` / `scale_gameobject` | Transform operations |
| `create_material` / `assign_material` / `modify_material` | Material workflow |
| `run_tests` | Execute Unity Test Runner tests |
| `add_package` | Install packages via Package Manager |
| `batch_execute` | Atomic batch operations with rollback |
| `get_console_logs` | Read Unity console with pagination |
| `recompile_scripts` | Trigger script recompilation |

## Resources

- `unity://scenes-hierarchy` — Full scene hierarchy
- `unity://gameobject/{id}` — Detailed component inspection
- `unity://logs` — Console logs
- `unity://packages` — Package Manager state
- `unity://assets` — Asset Database queries
- `unity://tests/{testMode}` — Test Runner listing

## Installation

### 1. Install the Unity package

```
Window > Package Manager > + > Add package from git URL:
https://github.com/CoderGamester/mcp-unity.git
```

### 2. Configure VS Code

Add to `.vscode/mcp.json`:

```json
{
  "servers": {
    "mcp-unity": {
      "type": "stdio",
      "command": "node",
      "args": ["<path-to-project>/Library/PackedCache/com.gamestar.mcp-unity@*/Server~/build/index.js"]
    }
  }
}
```

Or use the Unity Editor UI: **Tools > MCP Unity > Server Window > Configure**.

### 3. Start the server

**Tools > MCP Unity > Server Window > Start Server**, then open your AI coding IDE.

## IDE Integration

The package automatically adds Unity's `Library/PackedCache` folder to your VS Code workspace for better code intelligence and AI context about Unity packages.

## Tips

- Break complex scene modifications into `batch_execute` calls for atomicity.
- Use `get_console_logs` with error filter after operations to catch issues.
- Start with `unity://scenes-hierarchy` to understand the scene before making changes.
- The default WebSocket port is `8090` — configurable in the Server Window.

## Unity's Official MCP Server (Beta)

Unity also ships an official **Unity AI MCP Server** as part of the Unity AI Suite (beta). It requires Unity 6+ and a Unity Cloud link. The official server offers:
- Agentic in-editor assistant tuned for Unity workflows
- AI Gateway for connecting custom models
- Asset generation from images and references

The official server is free during beta but will become a paid feature. For open-source, self-hosted workflows, use mcp-unity above.