<p align="center"> <img src="icon.png" alt="AnkleBreaker MCP" width="180" /> </p>

Unity MCP Server AI-Powered Unity Editor & Hub Control

The most comprehensive Model Context Protocol (MCP) server for Unity game development. Connect Claude, Cursor, Windsurf, or any MCP-compatible AI assistant to Unity Editor and Unity Hub with 330+ tools across 30+ categories. Built and maintained by AnkleBreaker Studio.

AnkleBreaker Unity MCP turns your AI assistant into a full Unity co-pilot — create scenes, manipulate GameObjects, manage components, run builds, profile performance, edit Shader Graphs, control Amplify Shader Editor, sculpt terrain, bake NavMesh, manage animations, run multiplayer playmode scenarios, and much more — all without leaving your AI chat. Works with Claude Desktop, Claude Cowork, Cursor, Windsurf, and any tool that supports the Model Context Protocol.

Neon Brick Breaker — Built from scratch by AI in under 5 minutes

Claude creates the entire game: scene setup, neon materials with bloom post-processing, brick grid layout, game scripts, VFX, and UI — all through Unity MCP commands.

<p align="center"> <img src="docs/unity-mcp-showcase-brickbreaker.gif" alt="Unity MCP AI building a neon brick breaker game in Unity Editor" width="800" /> </p>

3D Medieval Village — AI-generated terrain, houses, and environment

From an empty scene to a fully decorated village: terrain sculpting, material creation, procedural house building via C# editor scripts, trees, fences, and pathways.

<p align="center"> <img src="docs/unity-mcp-showcase-village.gif" alt="Unity MCP — AI building a 3D medieval village with houses, trees, and terrain" width="800" /> </p>

3D Castle — Complete level with FPS walkthrough

AI builds a multi-room castle with courtyard, throne room, armory, and guard room. Adjusts lighting, spawns the player, and runs an FPS walkthrough to verify the result.

<p align="center"> <img src="docs/unity-mcp-showcase-castle.gif" alt="Unity MCP — AI building a 3D castle with FPS walkthrough in Unity Editor" width="800" /> </p>

How It Works — AI → MCP Server → Unity Plugin → Unity Editor

The Model Context Protocol connects your AI assistant to Unity through a lightweight bridge. Commands flow from your AI chat directly into the editor in real-time.

<p align="center"> <img src="docs/unity-mcp-architecture.gif" alt="Unity MCP Architecture — AI Assistant → MCP Server → Unity Plugin → Unity Editor" width="800" /> </p>

Features

330+ tools covering the full Unity workflow:

| Category | Tools | |----------|-------| | Unity Hub | List/install editors, manage modules, set install paths | | Scenes | Open, save, create scenes, get full hierarchy tree with pagination | | GameObjects | Create (primitives/empty), delete, duplicate, reparent, activate/deactivate, transform (world/local) | | Components | Add, remove, get/set any serialized property, wire object references, batch wire | | Assets | List, import, delete, search, create prefabs, create & assign materials | | Scripts | Create, read, update C# scripts | | Builds | Multi-platform builds (Windows, macOS, Linux, Android, iOS, WebGL) | | Console & Compilation | Read/clear Unity console logs (errors, warnings, info); get C# compilation errors via CompilationPipeline (independent of console buffer) | | Testing | Run EditMode/PlayMode tests, poll results, list available tests via Unity Test Runner API | | Play Mode | Play, pause, stop | | Editor | Execute menu items, run C# code, get editor state, undo/redo | | Project | Project info, packages (list/add/remove/search), render pipeline, build settings | | Animation | List clips & controllers, get parameters, play animations | | Prefab | Open/close prefab mode, get overrides, apply/revert changes | | Physics | Raycasts, sphere/box casts, overlap tests, physics settings | | Lighting | Manage lights, environment, skybox, lightmap baking, reflection probes | | Audio | AudioSources, AudioListeners, AudioMixers, play/stop, mixer params | | Terrain | Create/modify terrains, paint heightmaps/textures, manage terrain layers, trees, details | | Navigation | NavMesh baking, agents, obstacles, off-mesh links | | Particles | Particle system creation, inspection, module editing | | UI | Canvas, UI elements, layout groups, event system | | Tags & Layers | List/add/remove tags, assign tags & layers | | Selection | Get/set editor selection, find by name/tag/component/layer/tag | | Graphics | Scene and game view capture (inline images for visual inspection) | | Input Actions | Action maps, actions, bindings (Input System package) | | Assembly Defs | List, inspect, create, update .asmdef files | | ScriptableObjects | Create, inspect, modify ScriptableObject assets | | Constraints | Position, rotation, scale, aim, parent constraints | | LOD | LOD group management and configuration | | Profiler | Start/stop profiling, stats, deep profiles, save profiler data | | Frame Debugger | Enable/disable, draw call list & details, render targets | | Memory Profiler | Memory breakdown, top consumers, snapshots (com.unity.memoryprofiler) | | Shader Graph | List, inspect, create, open Shader Graphs & Sub Graphs; VFX Graphs | | Amplify Shader Editor | Full graph manipulation — create, inspect, add/remove/connect/disconnect/duplicate nodes, set properties, templates, save/close (if installed) | | MPPM Scenarios | List, activate, start, stop multiplayer playmode scenarios; get status & player info | | Multi-Instance | Discover and switch between multiple running Unity Editor instances | | Multi-Agent | List active agents, get agent action logs, queue monitoring | | SpriteAtlas | Create, inspect, add/remove sprites, configure settings, delete, list SpriteAtlases | | UMA (Unity Multipurpose Avatar) | Create slots, overlays, wardrobe recipes from FBX; equip/unequip items on DCA; browse/rebuild Global Library | | Project Context | Auto-inject project-specific docs and guidelines for AI agents |

Architecture

Claude / AI Assistant ←→ MCP Server (this repo) ←→ Unity Editor Plugin (HTTP bridge)
                                ↕
                          Unity Hub CLI

This server communicates with:

• Unity Hub via its CLI (supports both modern --headless and legacy -- --headless syntax)
• Unity Editor via the companion unity-mcp-plugin which runs an HTTP API inside the editor

330+ Tools Across 30+ Categories

Scene management, GameObjects, components, physics, terrain, Shader Graph, Amplify Shader Editor, profiling, animation, NavMesh, builds, multiplayer, and more.

<p align="center"> <img src="docs/unity-mcp-features.gif" alt="Unity MCP Features — 268 tools across 30+ categories for AI-powered game development" width="800" /> </p>

Two-Tier Tool System

To avoid overwhelming MCP clients with 330+ tools, the server uses a two-tier architecture:

• Core tools (~70) are always exposed directly
• Advanced tools (254) are accessed via a single unity_advanced_tool proxy with lazy loading

This keeps the tool count manageable for clients like Claude Desktop and Cowork while still providing access to every Unity feature. Use unity_list_advanced_tools to discover all advanced tools by category.

Multi-Instance Support

The server automatically discovers all running Unity Editor instances on startup. If only one instance is found, it auto-connects. If multiple instances are running (e.g., main editor + ParrelSync clones), it prompts you to select which one to work with.

Port Resilience — The server includes a multi-layer protection system for reliable multi-project workflows:

• Port Identity Validation — When restoring a saved connection, the server verifies the instance identity (project name + path) matches the expected target. If Unity restarts and a different project grabs the port, the server detects this and re-discovers the correct instance.
• Compile-Time Resilience — During long Unity compiles (when the editor is unresponsive), the server checks the shared instance registry. If the registry entry is fresh (updated within the last 5 minutes via heartbeat), the connection is preserved instead of dropped.
• Crash Detection — The plugin sends a heartbeat every 30 seconds to the instance registry. If Unity crashes and the heartbeat stops, the server detects the stale registry entry (>5 minutes old) and clears it, allowing proper re-discovery.
• Port Affinity — The plugin remembers its last-used port via EditorPrefs and reclaims it on restart, minimizing port swaps across editor restarts.

Quick Start

1. Install the Unity Plugin

In Unity: Window > Package Manager > + > Add package from git URL:

https://github.com/AnkleBreaker-Studio/unity-mcp-plugin.git

2. Install this MCP Server

git clone https://github.com/AnkleBreaker-Studio/unity-mcp-server.git
cd unity-mcp-server
npm install

3. Add to Claude Desktop

Open Claude Desktop > Settings > Developer > Edit Config, and add:

{
  "mcpServers": {
    "unity": {
      "command": "node",
      "args": ["C:/path/to/unity-mcp-server/src/index.js"],
      "env": {
        "UNITY_HUB_PATH": "C:\\Program Files\\Unity Hub\\Unity Hub.exe",
        "UNITY_BRIDGE_PORT": "7890"
      }
    }
  }
}

Restart Claude Desktop. Done!

4. Try It

• "List my installed Unity editors"
• "Show me the scene hierarchy"
• "Create a red cube at position (0, 2, 0) and add a Rigidbody"
• "Profile my scene and show the top memory consumers"
• "List all Shader Graphs in my project"
• "Build my project for Windows"
• "List and start my MPPM multiplayer scenarios"
• "Capture a screenshot of my scene view"
• "Show me the active agent sessions"

Configuration

| Environment Variable | Default | Description | |---------------------|---------|-------------| | UNITY_HUB_PATH | C:\Program Files\Unity Hub\Unity Hub.exe | Unity Hub executable path | | UNITY_BRIDGE_HOST | 127.0.0.1 | Editor bridge host | | UNITY_BRIDGE_PORT | 7890 | Editor bridge port (auto-discovered when using multi-instance) | | UNITY_BRIDGE_TIMEOUT | 60000 | Request timeout in ms | | UNITY_PORT_RANGE_START | 7890 | Start of port scan range for multi-instance discovery | | UNITY_PORT_RANGE_END | 7899 | End of port scan range | | UNITY_REGISTRY_STALENESS_TIMEOUT | 300000 | Registry entry staleness timeout in ms (crash detection) | | UNITY_RESPONSE_SOFT_LIMIT | 2097152 | Response size soft limit in bytes (warning) | | UNITY_RESPONSE_HARD_LIMIT | 4194304 | Response size hard limit in bytes (truncation) | | UNITY_MCP_DEBUG | unset | Set to 1 to append diagnostics to UnityMCP/mcp-debug.log (5MB rotation) | | UNITY_MCP_PRETTY_JSON | unset | Set to 1 to pretty-print tool responses (default is compact JSON — 20-50% fewer tokens) | | UNITY_MCP_COMPACT_TOOLS | unset | Set to 1 for a minimal tools/list (~21KB vs ~43KB): keeps all 79 tools and strict schema structure, drops per-parameter prose. For clients with registry size limits (e.g. Codex Desktop on Windows) |

The Unity plugin also has its own settings accessible via the Dashboard (Window > MCP Dashboard) for port, auto-start, and per-category feature toggles.

Optional Package Support

Some tools activate automatically when their packages are detected in the Unity project:

| Package / Asset | Features Unlocked | |----------------|-------------------| | com.unity.memoryprofiler | Memory snapshot capture via MemoryProfiler API | | com.unity.shadergraph | Shader Graph creation, inspection, opening | | com.unity.visualeffectgraph | VFX Graph