A Model Context Protocol (MCP) server that gives AI assistants like Claude full control over Unity Hub and Unity Editor. Built by AnkleBreaker Studio.
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 |
| Infinity Workshop | Search, download, and place assets from Upload Master server (VRseBuilder) |
VRseBuilder projects include integrated tools for searching, downloading, and placing assets from the Upload Master / Infinity Workshop server. These tools enable AI assistants to discover and add 3D models directly from a remote asset library.
| Tool | Purpose |
|---|---|
vrse_infinity_status |
Check authentication status, current tenant, and available tenants |
vrse_infinity_initialize |
Auto-initialize and authenticate Infinity Workshop Manager |
vrse_infinity_list_assets |
Search remote assets with backend query, tags, and filters |
vrse_infinity_download_assets |
Download specific assets by ID with conflict handling |
vrse_infinity_download_by_query |
One-shot: search + download top matches |
vrse_infinity_find_local_model_paths |
Resolve downloaded asset IDs to Unity paths (FBX/prefab) |
vrse_infinity_add_to_scene |
Instantiate downloaded asset at specific position |
vrse_infinity_place_smart |
Intelligently place single asset by analyzing scene |
vrse_infinity_place_smart_batch |
Place multiple assets with proper spacing (recommended for 2+ objects) |
vrse_infinity_download_and_place |
Complete workflow: search, download, and place (recommended for simple requests) |
Check authentication:
vrse_infinity_status()
// Returns: { isAuthenticated: true, username: "user@domain.com", currentTenant: {...} }Search for medieval furniture:
vrse_infinity_list_assets({
query: "castle",
tags: "medieval,furniture",
limit: 20
})
// Returns: { assets: [{assetId, name, tags, thumbnailUrl}], total: 15 }Download and place in scene:
// RECOMMENDED: One-shot workflow (handles everything)
vrse_infinity_download_and_place({
query: "car",
tags: "Vehicle",
maxResults: 3,
centerPosition: { x: -115, y: 0, z: -58 },
spacing: 4.0,
snapToGround: true
})
// Downloads 3 cars, places them with proper spacing at specified location
// Alternative: Manual control (for advanced use)
vrse_infinity_download_by_query({ query: "castle wall", topK: 1 })
vrse_infinity_find_local_model_paths({ assetIds: ["asset123"] })
vrse_infinity_place_smart({
assetPath: "Assets/CommonArt/3DAssets/CastleWall/CastleWall.prefab",
centerPosition: { x: 0, y: 0, z: 0 },
spacing: 1.0,
snapToGround: true
})
// Option 2: Manual positioning
vrse_infinity_add_to_scene({
assetPath: "Assets/CommonArt/3DAssets/CastleWall/CastleWall.prefab",
position: { x: 0, y: 0, z: 5 }
})Tools that interact with the remote server require authentication:
- Use
vrse_infinity_initializeto auto-initialize and authenticate (recommended) - Or manually login via Window > Infinity Workshop in Unity
- After initialization/login, all search/download tools work automatically
- Local tools (
find_local_model_paths,add_to_scene,place_smart) do not require authentication
When downloading assets that already exist locally, use conflictPolicy:
"cancel"(default) — stops download if asset already exists"overwrite"— replaces existing asset"skip"— skips conflicting asset, continues with others
NEW BEHAVIOR (2026-03): All Infinity placement tools now include collision-safe placement logic to prevent overlaps and clutter by default.
Placement tools use a Placement Quality Engine that validates every candidate position:
| Check | Description |
|---|---|
| Bbox Overlap | Expanded bounds must not intersect existing objects (configurable padding) |
| Center Distance | Minimum distance between object centers enforced |
| Footprint Limit | Rejects or auto-scales assets with excessive XZ footprint |
| Neighborhood Density | Limits object count within local radius to prevent clustering |
strictSafePlacement parameter (defaults to true for batch operations):
- When enabled: Uses candidate scoring, adaptive retries, and quality gates. May reject placement if no quality spot exists.
- When disabled: Falls back to legacy spiral search (no quality validation).
Default behavior:
vrse_infinity_place_smart—strictSafePlacement=false(preserves backward compatibility for single assets)vrse_infinity_place_smart_batch—strictSafePlacement=true(prevents batch clutter)vrse_infinity_download_and_place—strictSafePlacement=true(ensures clean multi-asset placement)
Use qualityPreset to control spacing and density rules:
| Preset | Use Case | Min Spacing | Min Center Dist | Max Footprint | Max Neighbors |
|---|---|---|---|---|---|
"strict" |
Low-density scenes, showcases | 3.0m | 8.0m | 150m² | 5 |
"balanced" |
Default, general purpose | 2.0m | 5.0m | 200m² | 8 |
"relaxed" |
High-density urban scenes | 1.0m | 3.0m | 300m² | 12 |
When strictSafePlacement=true, oversized assets are automatically scaled down to fit MaxFootprintXZ:
- Clamps scale between 0.1x and 1.0x (never scales up)
- Rejects placement if asset requires scale < 0.2x (with explicit
rejectionReason: "tooLargeAfterScaleClamp")
All placement tools return detailed diagnostics:
{
"success": true,
"placed": 15,
"skipped": 3,
"placedItems": [...],
"skippedItems": [
{
"assetPath": "...",
"rejectionReason": "tooLargeAfterScaleClamp",
"message": "Asset too large even after scale-down (would need scale=0.15)"
}
],
"diagnostics": {
"totalRequested": 18,
"placementRate": 0.833,
"retriesUsed": 7,
"strictModeEnabled": true,
"qualityPreset": "balanced"
}
}When placing multiple assets from Infinity Workshop:
- Always use batch tools (
vrse_infinity_place_smart_batchorvrse_infinity_download_and_place) — they prevent overlap race conditions - Keep strictSafePlacement=true (default for batch) — prevents messy scenes
- Start with balanced preset — escalate to relaxed only if placement rate is unacceptably low
- Provide centerPosition — improves predictability and layout quality
- Review diagnostics — if many assets skipped, inspect
rejectionReasonand adjust strategy (e.g., expand placement area, reduce asset count, or use relaxed preset)
If no valid placement is found after exhaustive search with adaptive retries:
- With strictSafePlacement=true: Returns error with explicit
rejectionReason(placement is skipped) - With strictSafePlacement=false: Places object 100m away from center as last resort
Never force-places overlapping objects — AI agents must handle placement rejections gracefully (e.g., by adjusting parameters or selecting different assets).
Claude / AI Assistant ←→ MCP Server (this repo) ←→ Unity Editor Plugin (HTTP bridge)
↕ ↕
Unity Hub CLI Infinity Workshop API
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
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.
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.
In Unity: Window > Package Manager > + > Add package from git URL:
https://github.com/AnkleBreaker-Studio/unity-mcp-plugin.git
git clone https://github.com/AnkleBreaker-Studio/unity-mcp-server.git
cd unity-mcp-server
npm installOpen 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!
- "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"
For VRse story mutation tools (vrse_apply_story_json, vrse_patch_story), save semantics are explicit:
- Validate first; if validation/ops fail, no write happens.
- On success, write the story JSON to disk at the StoryCreator file path.
- After write, reload StoryCreator from file in Unity so editor state matches disk.
vrse_get_story_infois read-only and never writes files.
This prevents partial writes and keeps the JSON file as the source of truth.
VRseBuilder projects include tools for converting scene objects into VRSE interactables (grabbable, placepoint, touch, ray). These tools call the same underlying Unity methods as the VRse Object tab but support intelligent target resolution from user prompts.
| Tool | Purpose |
|---|---|
vrse_convert_to_vrse_object |
Add GameObjectQuery to make object queryable in stories |
vrse_convert_to_touch_object |
Add HandTouchDetectable + BoxCollider for touch interactions |
vrse_convert_to_grabbable |
Convert mesh to Network Grabbable (full prefab-based setup) |
vrse_convert_to_placepoint |
Convert object to Network PlacePoint (snap target for grabbables) |
vrse_create_placepoint |
Create new Network PlacePoint at target/selection position |
vrse_convert_to_ray_interactable |
Add ray pointer interaction components |
All conversion tools support intelligent target resolution:
- Explicit path:
objectPath: "Environment/Props/Door_01"→ uses exact hierarchy path - User prompt:
targetHint: "emergency telephone"→ searches scene by name/token match - Selected object: if selected object matches hint or no hint provided → uses selection
- Ambiguity handling: returns candidate list if multiple matches found
Convert selected object:
vrse_convert_to_grabbable({ targetHint: "" })
// Uses currently selected object in Unity EditorConvert by name search:
vrse_convert_to_grabbable({ targetHint: "fire extinguisher" })
// Searches scene for objects matching "fire extinguisher"Convert by explicit path:
vrse_convert_to_grabbable({ objectPath: "Props/Tools/Extinguisher_01" })
// Uses exact hierarchy path, ignores selectionCreate new PlacePoint:
vrse_create_placepoint({ targetHint: "table center" })
// Creates PlacePoint at position of object matching "table center"All tools use network variants (Photon Fusion multiplayer-ready):
- Grabbable →
NetworkMetaXRGrabbable.prefab - PlacePoint →
NetworkMetaXRPlacePoint.prefab
Each conversion:
- Validates target compatibility (mesh/collider requirements)
- Calls canonical Unity converter methods (not UI automation)
- Returns structured result with resolved path and success status
- Handles prefab unpacking automatically if needed
All interactable tools use contextual, mechanic-based naming (not user prompts):
- Grabbable conversion: Renames object to
{OriginalName}_Grabbable- Example:
Cosmetics_Bottle_Spray→Cosmetics_Bottle_Spray_Grabbable
- Example:
- PlacePoint conversion: Renames object to
{OriginalName}_PlacePoint- Example:
Table_Surface→Table_Surface_PlacePoint
- Example:
- PlacePoint creation: Names based on reference context
- With reference object:
{ReferenceObjectName}_PlacePoint(strips "_Grabbable" suffix if present) - With parent only:
{ParentName}_PlacePoint - At world origin:
NetworkPlacePoint
- With reference object:
- VRse Object, Touch, Ray: Preserves original object name (no suffix added)
This ensures consistent, predictable naming that reflects the object's purpose and mechanic type, independent of how the user described it in their prompt.
| 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_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 |
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.
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.
- Node.js 18+
- Unity Hub (for Hub tools)
- Unity Editor with unity-mcp-plugin installed (for Editor tools)
"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.
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 | 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 | ✅ AnkleBreaker Open License | ❌ Proprietary | ✅ MIT License | ❌ Proprietary |
| Claude Cowork Optimized | ✅ Two-tier lazy loading | ❌ Not MCP-based | ❌ 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 | |||
| Physics Tools | ✅ Raycasts, overlap, settings | ❌ | ❌ | ❌ |
| Terrain Tools | ✅ Full terrain pipeline | ❌ | ❌ | ❌ |
| Shader Graph | ✅ Create, inspect, open | ❌ | ❌ | ❌ |
| Profiling & Debugging | ✅ Profiler + Frame Debugger + Memory | ❌ | ❌ | |
| Animation System | ✅ Controllers, clips, parameters | |||
| NavMesh / Navigation | ✅ Bake, agents, obstacles | ❌ | ❌ | ❌ |
| Particle Systems | ✅ Full module editing | ❌ | ❌ | ❌ |
| MPPM Multiplayer | ✅ Scenarios, start/stop | ❌ | ❌ | ❌ |
| Visual Inspection | ✅ Scene + Game view capture | ❌ | ❌ | |
| Play Mode Resilient | ✅ Survives domain reload | ❌ | ❌ | N/A |
| Port Resilience | ✅ Identity validation + crash detection | ❌ | ❌ | N/A |
| Project Context | ✅ Custom docs for AI agents | ❌ | ❌ |
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 |
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.
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.
- Parallel-safe instance routing — When multiple AI agents (e.g. Claude Cowork tasks) share the same MCP process, each agent can now include a
portparameter in everyunity_*tool call to guarantee routing to the correct Unity Editor instance. This prevents cross-agent contamination where one task'sunity_select_instancecould redirect another task's commands to the wrong project. - Per-request port override — A new stateless routing mechanism bypasses the shared per-agent state entirely. The
portparameter is extracted by middleware before the tool handler runs, used for routing, then stripped from the args. This is safe because MCP stdio transport processes requests sequentially. - Schema injection — The optional
portparameter is automatically injected into everyunity_*tool schema (exceptunity_list_instances,unity_select_instance, andunity_hub_*), so AI assistants see it as a legitimate parameter and pass it consistently. - Enhanced select_instance response —
unity_select_instancenow returns explicit routing instructions telling the AI to includeportin all subsequent calls.
AnkleBreaker Open License v1.0 — see LICENSE
This license requires: (1) including the copyright notice, (2) displaying "Made with AnkleBreaker MCP" (or "Powered by AnkleBreaker MCP") attribution in any product built with it (personal/educational use is exempt), and (3) reselling the tool is forbidden — you may not sell, sublicense, or commercially distribute this software or derivatives of it. See the full LICENSE for details.