unity-mcp-server

# unity-mcp-server > Skill by [ara.so](https://ara.so) — MCP Skills collection. ## Overview **unity-mcp-server** is a comprehensive Model Context Protocol (MCP) server that connects AI assistants (Claude Desktop, Cursor, Windsurf) to Unity Editor and Unity Hub. It provides 288 tools across 30+ categories for AI-assisted game development, including scene management, GameObject manipulation, component wiring, builds, profiling, Shader Graph editing, terrain sculpting, NavMesh baking, and multiplayer scenarios. The server uses a two-tier architecture: ~70 core tools exposed directly, and ~130+ advanced tools accessed via `unity_advanced_tool` proxy with lazy loading to avoid overwhelming MCP clients. **Architecture:** ``` AI Assistant ↔ MCP Server (Node.js) ↔ Unity Editor Plugin (HTTP bridge) ↔ Unity Editor ↕ Unity Hub CLI ``` ## Installation ### 1. Install Unity Plugin In Unity Editor: 1. Open **Window > Package Manager** 2. Click **+ > Add package from git URL** 3. Enter: `https://github.com/AnkleBreaker-Studio/unity-mcp-plugin.git` 4. Wait for installation to complete 5. Verify plugin is running: **Window > MCP Dashboard** ### 2. Install MCP Server ```bash git clone https://github.com/AnkleBreaker-Studio/unity-mcp-server.git cd unity-mcp-server npm install ``` ### 3. Configure Claude Desktop Edit Claude Desktop config (`~/.config/Claude/claude_desktop_config.json` on macOS/Linux, `%APPDATA%\Claude\claude_desktop_config.json` on Windows): ```json { "mcpServers": { "unity": { "command": "node", "args": ["/absolute/path/to/unity-mcp-server/src/index.js"], "env": { "UNITY_HUB_PATH": "/Applications/Unity Hub.app/Contents/MacOS/Unity Hub", "UNITY_BRIDGE_PORT": "7890" } } } } ``` **Windows example:** ```json { "mcpServers": { "unity": { "command": "node", "args": ["C:\\Dev\\unity-mcp-server\\src\\index.js"], "env": { "UNITY_HUB_PATH": "C:\\Program Files\\Unity Hub\\Unity Hub.exe", "UNITY_BRIDGE_PORT": "7890" } } } } ``` ### 4. Configure Cursor/Windsurf Add to `.cursor/mcp.json` or Windsurf settings: ```json { "mcpServers": { "unity": { "command": "node", "args": ["/absolute/path/to/unity-mcp-server/src/index.js"], "env": { "UNITY_HUB_PATH": "/Applications/Unity Hub.app/Contents/MacOS/Unity Hub", "UNITY_BRIDGE_PORT": "7890" } } } } ``` Restart your AI assistant after configuration. ## Configuration ### Environment Variables | Variable | Default | Description | |----------|---------|-------------| | `UNITY_HUB_PATH` | (OS-dependent) | Path to Unity Hub executable | | `UNITY_BRIDGE_HOST` | `127.0.0.1` | Editor plugin HTTP host | | `UNITY_BRIDGE_PORT` | `7890` | Editor plugin HTTP port (auto-discovered in multi-instance mode) | | `UNITY_BRIDGE_TIMEOUT` | `30000` | Request timeout in milliseconds | | `UNITY_PORT_RANGE_START` | `7890` | Port scan range start for multi-instance discovery | | `UNITY_PORT_RANGE_END` | `7899` | Port scan range end | | `UNITY_REGISTRY_STALENESS_TIMEOUT` | `300000` | Registry entry staleness timeout (crash detection) | | `UNITY_RESPONSE_SOFT_LIMIT` | `2097152` | Response size soft limit (2MB, warning only) | | `UNITY_RESPONSE_HARD_LIMIT` | `4194304` | Response size hard limit (4MB, truncates) | | `UNITY_MCP_DEBUG` | `false` | Enable debug logging | ### Unity Plugin Settings Access via **Window > MCP Dashboard** in Unity Editor: - **HTTP Port**: Change the server port (default: 7890) - **Auto-Start Server**: Start HTTP server on editor launch - **Category Toggles**: Enable/disable specific tool categories (Shader Graph, Amplify, MPPM, etc.) ## Core Tools ### Unity Hub Management **List installed Unity editors:** ``` unity_hub_list_editors ``` **Install a Unity editor version:** ``` unity_hub_install_editor { "version": "2022.3.20f1", "modules": ["android", "ios", "webgl"] } ``` **Set Unity Hub install path:** ``` unity_hub_set_install_path { "path": "/Applications/Unity/Hub/Editor" } ``` ### Scene Management **Get scene hierarchy (with pagination):** ``` unity_get_scene_hierarchy { "page": 1, "pageSize": 50 } ``` **Open scene:** ``` unity_open_scene { "scenePath": "Assets/Scenes/MainMenu.unity" } ``` **Create new scene:** ``` unity_create_scene { "sceneName": "Level_01", "savePath": "Assets/Scenes/Level_01.unity", "additive": false } ``` ### GameObject Manipulation **Create primitive GameObject:** ``` unity_create_gameobject { "name": "RedCube", "primitiveType": "Cube", "position": [0, 2, 0], "parent": null } ``` **Delete GameObject:** ``` unity_delete_gameobject { "objectPath": "RedCube" } ``` **Set transform (local):** ``` unity_set_transform { "objectPath": "RedCube", "position": [0, 5, 0], "rotation": [0, 45, 0], "scale": [2, 2, 2], "space": "Local" } ``` **Reparent GameObject:** ``` unity_set_parent { "objectPath": "RedCube", "parentPath": "GameObjects/Level", "worldPositionStays": true } ``` ### Component Management **Add component:** ``` unity_add_component { "objectPath": "RedCube", "componentType": "Rigidbody" } ``` **Set component property:** ``` unity_set_component_property { "objectPath": "RedCube", "componentType": "Rigidbody", "propertyPath": "mass", "value": 10.5 } ``` **Get component properties:** ``` unity_get_component { "objectPath": "RedCube", "componentType": "Rigidbody" } ``` **Wire object reference:** ``` unity_wire_object_reference { "sourceObjectPath": "Player", "sourceComponentType": "PlayerController", "propertyPath": "target", "targetObjectPath": "Enemy/Boss" } ``` **Batch wire references:** ``` unity_batch_wire_references { "operations": [ { "sourceObjectPath": "UI/HealthBar", "sourceComponentType": "HealthDisplay", "propertyPath": "player", "targetObjectPath": "Player" }, { "sourceObjectPath": "Camera", "sourceComponentType": "CameraFollow", "propertyPath": "target", "targetObjectPath": "Player" } ] } ``` ### Asset Management **List assets:** ``` unity_list_assets { "path": "Assets/Materials", "recursive": true } ``` **Create material:** ``` unity_create_material { "name": "RedMetal", "savePath": "Assets/Materials/RedMetal.mat", "shader": "Standard", "properties": { "_Color": [1, 0, 0, 1], "_Metallic": 0.8, "_Glossiness": 0.6 } } ``` **Assign material:** ``` unity_assign_material { "objectPath": "RedCube", "materialPath": "Assets/Materials/RedMetal.mat" } ``` **Create prefab:** ``` unity_create_prefab { "objectPath": "RedCube", "savePath": "Assets/Prefabs/RedCube.prefab" } ``` ### Script Management **Create C# script:** ``` unity_create_script { "scriptName": "PlayerController", "savePath": "Assets/Scripts/PlayerController.cs", "template": "MonoBehaviour" } ``` **Read script:** ``` unity_read_script { "scriptPath": "Assets/Scripts/PlayerController.cs" } ``` **Update script:** ``` unity_update_script { "scriptPath": "Assets/Scripts/PlayerController.cs", "content": "using UnityEngine;\n\npublic class PlayerController : MonoBehaviour\n{\n public float speed = 5f;\n \n void Update()\n {\n float h = Input.GetAxis(\"Horizontal\");\n float v = Input.GetAxis(\"Vertical\");\n transform.Translate(new Vector3(h, 0, v) * speed * Time.deltaTime);\n }\n}" } ``` ### Build Management **Build for Windows:** ``` unity_build { "target": "StandaloneWindows64", "outputPath": "Builds/Windows/Game.exe", "developmentBuild": false } ``` **Build for WebGL:** ``` unity_build { "target": "WebGL", "outputPath": "Builds/WebGL", "developmentBuild": true } ``` **Supported platforms:** `StandaloneWindows64`, `StandaloneOSX`, `StandaloneLinux64`, `Android`, `iOS`, `WebGL` ### Console & Compilation **Get console logs:** ``` unity_get_console_logs { "includeErrors": true, "includeWarnings": true, "includeInfo": false, "maxCount": 50 } ``` **Clear console:** ``` unity_clear_console ``` **Get compilation errors (independent of console):** ``` unity_get_compilation_errors ``` ### Play Mode Control **Enter play mode:** ``` unity_play ``` **Pause play mode:** ``` unity_pause ``` **Stop play mode:** ``` unity_stop ```