Skip to content

AutoVRse-Enterprise/unity-mcp-server

 
 

Repository files navigation

AnkleBreaker MCP

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
Infinity Workshop Search, download, and place assets from Upload Master server (VRseBuilder)

Infinity Workshop Tools (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.

Available Tools

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)

Usage Examples

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 }
})

Authentication Requirements

Tools that interact with the remote server require authentication:

  • Use vrse_infinity_initialize to 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

Conflict Handling

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

Collision-Safe Placement Contract

NEW BEHAVIOR (2026-03): All Infinity placement tools now include collision-safe placement logic to prevent overlaps and clutter by default.

Quality Validation System

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

Strict Safe Mode (Default for Batch)

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_smartstrictSafePlacement=false (preserves backward compatibility for single assets)
  • vrse_infinity_place_smart_batchstrictSafePlacement=true (prevents batch clutter)
  • vrse_infinity_download_and_placestrictSafePlacement=true (ensures clean multi-asset placement)

Quality Presets

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

Adaptive Scale Safety

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")

Placement Diagnostics

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"
  }
}

Recommended Defaults for AI Agents

When placing multiple assets from Infinity Workshop:

  1. Always use batch tools (vrse_infinity_place_smart_batch or vrse_infinity_download_and_place) — they prevent overlap race conditions
  2. Keep strictSafePlacement=true (default for batch) — prevents messy scenes
  3. Start with balanced preset — escalate to relaxed only if placement rate is unacceptably low
  4. Provide centerPosition — improves predictability and layout quality
  5. Review diagnostics — if many assets skipped, inspect rejectionReason and adjust strategy (e.g., expand placement area, reduce asset count, or use relaxed preset)

Fallback Behavior

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).

Architecture

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 --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.

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"

VRse Story Save Contract

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_info is read-only and never writes files.

This prevents partial writes and keeps the JSON file as the source of truth.

VRse Interactable Tools (VRseBuilder)

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.

Available Tools

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

Target Resolution

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

Usage Examples

Convert selected object:

vrse_convert_to_grabbable({ targetHint: "" })
// Uses currently selected object in Unity Editor

Convert 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 selection

Create new PlacePoint:

vrse_create_placepoint({ targetHint: "table center" })
// Creates PlacePoint at position of object matching "table center"

Conversion Details

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

Naming Convention

All interactable tools use contextual, mechanic-based naming (not user prompts):

  • Grabbable conversion: Renames object to {OriginalName}_Grabbable
    • Example: Cosmetics_Bottle_SprayCosmetics_Bottle_Spray_Grabbable
  • PlacePoint conversion: Renames object to {OriginalName}_PlacePoint
    • Example: Table_SurfaceTable_Surface_PlacePoint
  • 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
  • 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.

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_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.

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 ✅ AnkleBreaker Open 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
Port Resilience ✅ Identity validation + crash detection 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.

GitHub Sponsors Patreon

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.25.0

  • Parallel-safe instance routing — When multiple AI agents (e.g. Claude Cowork tasks) share the same MCP process, each agent can now include a port parameter in every unity_* tool call to guarantee routing to the correct Unity Editor instance. This prevents cross-agent contamination where one task's unity_select_instance could 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 port parameter 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 port parameter is automatically injected into every unity_* tool schema (except unity_list_instances, unity_select_instance, and unity_hub_*), so AI assistants see it as a legitimate parameter and pass it consistently.
  • Enhanced select_instance responseunity_select_instance now returns explicit routing instructions telling the AI to include port in all subsequent calls.

License

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.

About

MCP Server for Unity Hub and Unity Editor integration — gives AI assistants like Claude full control over Unity

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

 
 
 

Contributors

Languages

  • JavaScript 100.0%