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 --headless and legacy -- --headless syntax)
• 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_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.

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 | 30000 | Request timeout in ms | | UNITY_MCP_DEBUG | false | Enable debug logging for troubleshooting |

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 listing and opening | | com.unity.inputsystem | Input Action map and binding inspection | | com.unity.multiplayer.playmode | MPPM scenario listing, activation, start/stop, player info | | Amplify Shader Editor (Asset Store) | Amplify shader listing, inspection, opening |

Features for uninstalled packages return helpful messages explaining what to install.

Requirements

• Node.js 18+
• Unity Hub (for Hub tools)
• Unity Editor with unity-mcp-plugin installed (for Editor tools)

Troubleshooting

"Connection failed" errors — Make sure Unity Editor is open and the plugin is installed. Check the Unity Console for [MCP Bridge] Server started on port 7890.

"Unity Hub not found" — Update UNITY_HUB_PATH in your config to match your installation.

"Category disabled" errors — A feature category may be toggled off. Open Window > MCP Dashboard in Unity to check category settings.

Port conflicts — Change UNITY_BRIDGE_PORT in your Claude config and update the port in Unity's MCP Dashboard settings.

Why AnkleBreaker Unity MCP?

AnkleBreaker Unity MCP is the most comprehensive MCP integration for Unity, purpose-built to leverage the full power of Claude Cowork and other AI assistants. Here's how it compares to alternatives:

Feature Comparison

| Feature | AnkleBreaker MCP | Bezi | Coplay MCP | Unity AI | |---------|:-------------------:|:--------:|:--------------:|:------------:| | Total Tools | 200+ | ~30 | 34 | Limited (built-in) | | Feature Categories | 30+ | ~5 | ~5 | N/A | | Non-Blocking Editor | ✅ Full background operation | ❌ Freezes Unity during tasks | ✅ | ✅ | | Open Source | ✅ MIT License | ❌ Proprietary | ✅ MIT License | ❌ Proprietary | | Claude Cowork Optimized | ✅ Two-tier lazy loading | ❌ Not MCP-based | ⚠️ Basic | ❌ Not MCP-based | | Multi-Instance Support | ✅ Auto-discovery | ❌ | ❌ | ❌ | | Multi-Agent Support | ✅ Session tracking + queuing | ❌ | ❌ | ❌ | | Unity Hub Control | ✅ Install editors & modules | ❌ | ❌ | ❌ | | Scene Hierarchy | ✅ Full tree + pagination | ⚠️ Limited | ⚠️ Basic | ⚠️ Limited | | Physics Tools | ✅ Raycasts, overlap, settings | ❌ | ❌ | ❌ | | Terrain Tools | ✅ Full terrain pipeline | ❌ | ❌ | ❌ | | Shader Graph | ✅ Create, inspect, open | ❌ | ❌ | ❌ | | Profiling & Debugging | ✅ Profiler + Frame Debugger + Memory | ❌ | ❌ | ⚠️ Basic | | Animation System | ✅ Controllers, clips, parameters | ⚠️ Basic | ⚠️ Basic | ⚠️ Basic | | NavMesh / Navigation | ✅ Bake, agents, obstacles | ❌ | ❌ | ❌ | | Particle Systems | ✅ Full module editing | ❌ | ❌ | ❌ | | MPPM Multiplayer | ✅ Scenarios, start/stop | ❌ | ❌ | ❌ | | Visual Inspection | ✅ Scene + Game view capture | ❌ | ⚠️ Limited | ❌ | | Play Mode Resilient | ✅ Survives domain reload | ❌ | ❌ | N/A | | Project Context | ✅ Custom docs for AI agents | ❌ | ❌ | ⚠️ Built-in only |

Cost Comparison

AnkleBreaker Unity MCP is completely free and open source. The prices below reflect only the cost of the AI assistant (Claude) itself — the MCP plugin and server are $0.

| Solution | Monthly Cost | What You Get | |----------|:----------:|--------------| | AnkleBreaker MCP (free) + Claude Pro | $20/mo | 200+ tools, full Unity control, open source — MCP is free, price is Claude only | | AnkleBreaker MCP (free) + Claude Max 5x | $100/mo | Same + 5x usage for heavy workflows — MCP is free, price is Claude only | | AnkleBreaker MCP (free) + Claude Max 20x | $200/mo | Same + 20x usage for teams/studios — MCP is free, price is Claude only | | Bezi Pro | $20/mo | ~30 tools, 800 credits/mo, freezes Unity | | Bezi Advanced | $60/mo | ~30 tools, 2400 credits/mo, freezes Unity | | Bezi Team | $200/mo | 3 seats, 8000 credits, still freezes Unity | | Unity AI | Included with Unity Pro/Enterprise | Limited AI tools, Unity Points system, no MCP | | Coplay MCP | Free (beta) | 34 tools, basic categories |

Key Advantages

vs. Bezi: Bezi runs as a proprietary Unity plugin with its own credit-based billing — $20–$200/mo on top of your AI subscription. It has historically suffered from freezing the Unity Editor during AI tasks, blocking your workflow. AnkleBreaker MCP is completely free and open source, runs entirely in the background with zero editor impact, and offers 6x more tools — the only cost is your existing Claude subscription.

vs. Coplay MCP: Coplay MCP provides 34 tools across ~5 categories. AnkleBreaker MCP delivers 200+ tools across 30+ categories including advanced features like physics raycasts, terrain editing, shader graph management, profiling, NavMesh, particle systems, and MPPM multiplayer — none of which exist in Coplay. Our two-tier lazy loading system is specifically optimized for Claude Cowork's tool limits.

vs. Unity AI: Unity AI (successor to Muse) is built into Unity 6.2+ but limited to Unity's own AI models and a credit-based "Unity Points" system. It cannot be used with Claude or any external AI assistant, has no MCP support, and offers a fraction of the automation capabilities. AnkleBreaker MCP works with any MCP-compatible AI while giving you full control over which AI models you use.

Support the Project

If Unity MCP helps your workflow, consider supporting its development! Your support helps fund new features, bug fixes, documentation, and more open-source game dev tools.

Sponsor tiers include priority feature requests — your ideas get bumped up the roadmap! Check out the tiers on GitHub Sponsors or Patreon.

What's New in v2.21.0

• Graphics capture data path fix — Fixed unity_graphics_scene_capture and unity_graphics_game_capture returning false "no image data" errors by correctly unwrapping the bridge response structure (result.data.base64)
• MPPM route overrides — Fixed Multiplayer Play Mode tools (unity_mppm_*) failing via the advanced tool proxy by adding explicit route mappings for scenario/* endpoints
• Hub CLI resilience — Rewrote Unity Hub CLI wrapper with strategy-based fallback (modern → legacy syntax), better error recovery from non-zero exit codes, and 10MB output buffer
• Property type coercion — unity_component_set_property now auto-converts string values like "5.0" to proper numeric types, preventing C# parsing failures across different locales
• Response size protection — Global truncation safety net prevents oversized responses (large hierarchies, asset lists) from causing Write EOF errors on the stdio transport

License

MIT with Attribution Requirement — see LICENSE

Any product built with Unity MCP must display "Made with AnkleBreaker MCP" (or "Powered by AnkleBreaker MCP") with the logo. Personal/educational use is exempt.