README.md
Gives AI assistants full control over Unity Hub and Unity Editor
Unity MCP Server
A Model Context Protocol (MCP) server that gives AI assistants like Claude full control over Unity Hub and Unity Editor. Built by AnkleBreaker Studio.
Features
200+ 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 | Read/clear Unity console logs (errors, warnings, info) |
| 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 | List, inspect, open Amplify shaders & functions (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 |
| 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
--headlessand legacy-- --headlesssyntax) - Unity Editor via the companion unity-mcp-plugin which runs an HTTP API inside the editor
Two-Tier Tool System
To avoid overwhelming MCP clients with 200+ tools, the server uses a two-tier architecture:
- Core tools (~70) are always exposed directly
- Advanced tools (~130+) are accessed via a single
unity_advanced_toolproxy 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 differen
Tools (2)
unity_advanced_toolProxy tool for accessing over 130 advanced Unity features via lazy loadingunity_list_advanced_toolsLists all available advanced tools categorized by Unity functionalityConfiguration
claude_desktop_config.json
{"mcpServers": {"unity": {"command": "npx", "args": ["-y", "@anklebreaker-studio/unity-mcp-server"]}}}Try it
→Create a new empty GameObject in the current scene and add a BoxCollider component to it.
→List all scenes in the project and open the main menu scene.
→Run a build for the Android platform and report any console errors.
→Find all materials in the project and assign a new shader to them.
→Start the Unity profiler and capture data for the next 10 seconds.