unity-mcp

<div align="center"> # Unity MCP [](https://unity.com/) [](https://modelcontextprotocol.io/) [](LICENSE) **Let AI assistants directly control your Unity Editor** [English](docs/README.en.md) | English </div> **Unity MCP** is a [Model Context Protocol](https://modelcontextprotocol.io/) server embedded in the Unity Editor. After installation, AI assistants like Claude, Cursor, VS Code Copilot, and Windsurf can read scenes, create objects, modify materials, run tests, take screenshots, and more - all through natural language, without manual operation. ``` MCP Client (Claude/Cursor/VS Code/Windsurf) ↕ stdio / streamable-http (JSON-RPC 2.0) Python FastMCP Server (Dynamic Tool Discovery) ↕ TCP (Custom Frame Protocol) Unity Editor (TCP Server + Tool Registry) ``` --- ## Quick Start Complete the setup in 3 steps and start AI-driven Unity development. ### 1. Install Unity Package **Git URL (Recommended)** — In Unity: `Window > Package Manager > + > Add package from git URL`: ``` https://github.com/mzbswh/unity-mcp.git?path=unity-mcp ``` <details> <summary>Other Installation Methods</summary> **Local Clone** ```bash git clone https://github.com/mzbswh/unity-mcp.git ``` In Unity: `Window > Package Manager > + > Add package from disk`, select `unity-mcp/package.json`. </details> ### 2. Configure Client with One Click Open `Window > Unity MCP`, switch to the **Clients** tab, and click the **Configure** button next to your client. Supported clients for automatic configuration: | Client | Configuration Location | Description | |--------|------------------------|-------------| | **Claude Code** | `~/.claude.json` | Write to project path | | **Cursor** | `.cursor/mcp.json` | Project-level configuration | | **VS Code / Copilot** | `.vscode/mcp.json` | Project-level configuration | | **Windsurf** | `~/.codeium/windsurf/mcp_config.json` | Global configuration | > Other clients can use **Copy Config to Clipboard** for manual paste. MCP client configuration example (using Cursor): ```json { "mcpServers": { "unity": { "command": "uvx", "args": ["unity-mcp-server"] } } } ``` > `uvx` will automatically download and run from PyPI, no manual installation needed. You can also install with `pip install unity-mcp-server` and run directly with `unity-mcp-server`. > Default connection port is 51279. For multi-instance scenarios, specify `UNITY_MCP_PORT` via the `env` field. ### 3. Verification Tell your AI assistant: > "List all GameObjects in my Unity scene" If it returns the scene hierarchy information, the configuration is successful. --- ## Features - **146 Editor Tools** — GameObject, Scene, Asset, Material, Animation, Prefab, UI Toolkit, VFX, Graphics, Lighting, NavMesh, Physics, Terrain, Shader, Texture, Build, Package, Test, Screenshot, Console, ProBuilder, etc. - **11 Python-side Tools** — PSD parsing/exporting/compositing/to UI, Figma design draft retrieval/cutting map download (can run without Unity connection) - **13 Resource Endpoints** — Read-only data query (scene hierarchy, project information, editor state, console logs, current selection, etc.) - **48 Prompt Templates** — Unity best practices guide (architecture, script, performance, Shader, XR, ECS, network, etc.) - **PSD → UI Workflow** — Parse PSD/PSB file structure, export layer images, automatically generate Unity UI hierarchy - **Figma Integration** — Retrieve Figma design draft list, download design diagrams for AI analysis, batch download cutting maps to the project - **Batch Execution** — Execute multiple tool operations in one request, support atomic rollback - **Runtime Mode** — Optional runtime MCP server, control running games (8 runtime tools) - **Dynamic Tool Discovery** — Python server automatically discovers and registers all tools/resources/prompt templates when started from Unity - **Multi-instance Support** — Run multiple Unity Editor instances simultaneously - **Custom Tool API** — Add custom tools with C# attributes, automatically discovered at startup - **Domain Reload Safety** — Unity script recompilation automatically reconnects; Python server automatically caches and replays received requests during the period, nearly imperceptible to MCP clients - **Dependency Detection** — First startup automatically checks Python/uv/uvx environment, guides installation - **Version Update Check** — Daily automatic check for new versions, prompts update in the settings window - **Tool Invocation Diagnosis** — Records the name, time consumption, and success/failure status of recent tool invocations ## Tool List <details> <summary><b>GameObject & Component (14 tools)</b></summary> | Tool | Description | |------|------| | `gameobject_create` | Create GameObject | | `gameobject_destroy` | Delete GameObject | | `gameobject_find` | Find by name/path | | `gameobject_modify` | Modify properties (name, tag, layer, active state) | | `gameobject_set_parent` | Set parent-child relationship | | `gameobject_duplicate` | Duplicate GameObject | | `gameobject_get_components` | Get component list | | `gameobject_look_at` | Look at target | | `gameobject_set_sibling_index` | Set sibling order | | `gameobject_add_component` | Add component | | `gameobject_remove_component` | Remove component | | `gameobject_get_component` | View component properties | | `gameobject_modify_component` | Modify component properties | | `gameobject_copy_component` | Copy component values | </details> <details> <summary><b>Scene (15 tools)</b></summary> | Tool | Description | |------|------| | `scene_create` / `scene_open` / `scene_save` | Scene management | | `scene_get_hierarchy` / `scene_list_all` | Hierarchy view | | `scene_align_with_view` / `scene_move_to_view` | View alignment | | `scene_frame_selected` | Focus on selected object | | `scene_view_get` / `scene_view_set` | Scene view position control | | `scene_view_get_settings` / `scene_view_set_settings` | Scene view settings | | `game_view_get_settings` / `game_view_set_settings` | Game view settings | | `scene_view_snap_angle` | Snap to preset angle | </details> <details> <summary><b>Asset (10 tools)</b></summary> | Tool | Description | |------|------| | `asset_find` / `asset_get_info` | Asset search and information | | `asset_create_folder` / `asset_delete` / `asset_move` / `asset_copy` | Asset file operations | | `asset_refresh` | Refresh asset database | | `asset_set_import_settings` / `asset_set_model_import` | Import settings | | `asset_find_references` | Find references | </details> <details> <summary><b>Material & Shader (8 tools)</b></summary> | Tool | Description | |------|------| | `material_create` / `material_modify` | Material creation and modification | | `material_set_render_mode` | Set render mode | | `material_get_keywords` / `material_set_keywords` | Material keyword management | | `shader_list` / `shader_get_properties` | Shader query | | `shader_info` | Shader detailed information | </details> <details> <summary><b>Prefab (10 tools)</b></summary> | Tool | Description | |------|------| | `prefab_create` / `prefab_instantiate` | Prefab workflow | | `prefab_open` / `prefab_close` | Prefab edit mode | | `prefab_get_hierarchy` / `prefab_get_stage_objects` | Prefab hierarchy view | | `prefab_modify_contents` | Modify prefab contents | | `prefab_apply_overrides` / `prefab_revert_overrides` | Override management | | `prefab_unpack` | Unpack prefab | </details> <details> <summary><b>Animation (6 tools)</b></summary> | Tool | Description | |------|------| | `animation_create_clip` | Create animation clip | | `animation_manage_controller` | Manage Animator Controller | | `animation_add_transition` | Add state transition | | `animation_add_layer` | Add animation layer | | `animation_create_blend_tree` | Create blend tree | | `animation_set_clip_curve` | Set animation curve | </details> <details> <summary><b>UI Toolkit (4 tools)</b></summary> | Tool | Description | |------|------| | `uitoolkit_create` | UXML/USS creation | | `uitoolkit_list` | List UI assets | | `uitoolkit_attach` | Bind UIDocument | | `uitoolkit_get_visual_tree` | Get runtime visual tree | </details> <details> <summary><b>VFX (1 tool)</b></summary> | Tool | Description | |------|------| | `vfx_create_graph` | VFX Graph creation | </details> <details> <summary><b>Graphics (11 tools)</b></summary> | Tool | Description | |------|------| | `graphics_get_skybox` / `graphics_set_skybox` | Skybox | | `graphics_get_fog` / `graphics_set_fog` | Fog | | `graphics_get_ambient` / `graphics_set_ambient` | Ambient light | | `graphics_get_render_pipeline` | Render pipeline information | | `graphics_get_quality` / `graphics_set_quality` | Quality settings | | `graphics_get_stats` | Graphics statistics | | `graphics_get_lightmap_settings` | Lightmap settings | </details> <details> <summary><b>Lighting (2 tools)</b></summary> | Tool | Description | |------|------| | `lighting_bake` | Light baking | | `lighting_cancel_bake` | Cancel baking | </details> <details> <summary><b>Physics & NavMesh (6 tools)</b></summary> | Tool | Description | |------|------| | `physics_create_material` | Physics material | | `physics_raycast` | Raycast detection | | `physics_get_settings` / `physics_set_gravity` | Physics settings | | `navmesh_bake` / `navmesh_clear` | NavMesh baking | </details> <details> <summary><b>Terrain (6 tools)</b></summary> | Tool | Description | |------|------| | `terrain_create` | Create terrain | | `terrain_get_info` | Get terrain information | | `terrain_set_height` / `terrain_flatten` | Height editing | | `terrain_add_layer` | Add terrain layer | | `terrain_add_tree` | Add tree | </details> <details> <summary><b>Texture (2 tools)</b></summary> | Tool | Description | |------|------| | `texture_get_info` | Get texture information | | `texture_search` | Search texture assets | </details> <details> <summary><b>PSD & Design System (11 tools, Python side)</b></summary> | Tool | Description | |------|------| | `psd_summary` | Get PSD/PSB file summary (size, layer count, color mode, etc.) | | `psd_layer_detail` | Get detailed layer information (hierarchy, blend mode, visibility, etc.) | | `psd_parse` | Parse PSD/PSB and return complete layer tree (optional export image) | | `psd_export_images` | Export all visible layers of PSD as PNG images (only return export list) | | `psd_to_image` | Merge PSD/PSB into a single PNG/JPG image (support scaling) | | `psd_to_ui` | PSD to Unity UI complete process (parse + export + generate UI) | | `lanhu_set_cookie` | Set Lanhu authentication Cookie | | `lanhu_get_designs` | Get Lanhu project design draft list | | `lanhu_analyze_design` | Download Lanhu design draft for AI analysis | | `lanhu_get_slices` | Get Lanhu design draft slice list | | `lanhu_download_slices` | Batch download Lanhu slices to Unity project | </details> <details> <summary><b>Editor & Utility (50+ tools)</b></summary> | Tool | Description | |------|------| | `editor_get_state` / `editor_set_playmode` | Editor state control | | `editor_execute_menu` | Execute menu command | | `editor_selection_get` / `editor_selection_set` | Selected object management | | `editor_undo` / `editor_redo` | Undo/Redo | | `editor_open_window` | Open editor window | | `editor_get_compile_status` | Script compilation status | | `screenshot_scene` / `screenshot_game` | Scene/Game view screenshot (return MCP image) | | `console_get_logs` | Console logs | | `test_run` / `test_get_results` | Test run | | `package_list` / `package_add` / `package_remove` / `package_search` / `package_get_info` | UPM package management | | `build_player` / `build_get_settings` / `build_set_scenes` / `build_switch_platform` | Build management | | `build_get_player_settings` / `build_set_player_settings` | Player Settings | | `settings_get_tags` / `settings_add_tag` / `settings_get_layers` / `settings_add_layer` | Tag and layer management | | `settings_get_sorting_layers` / `settings_add_sorting_layer` | Sorting layer | | `settings_get_quality` / `settings_set_quality` | Quality level | | `settings_get_time` / `settings_set_time` | Time settings | | `so_create` / `so_get` / `so_modify` / `so_list_types` | ScriptableObject management | | `code_execute` / `code_validate` | C# code execution | | `batch_execute` | Atomic batch execution | | `instance_list` / `instance_set_active` | Multi-instance management | | `editor_is_clone` / `editor_get_mppm_tags` | MPPM support | | `probuilder_create_shape` / `probuilder_get_mesh_info` / `probuilder_extrude_faces` / `probuilder_set_material` | ProBuilder modeling | </details> <details> <summary><b>Resources (13 Resources)</b></summary> | URI | Description | |-----|------| | `unity://scene/hierarchy` | Scene hierarchy tree | | `unity://scene/list` | Scene list in Build Settings | | `unity://project/info` | Project metadata | | `unity://editor/state` | Editor state | | `unity://editor/selection` | Current selected object | | `unity://console/logs` | Console logs | | `unity://gameobject/{id}` | GameObject detailed information | | `unity://assets/search/{filter}` | Asset search | | `unity://packages/list` | Installed UPM packages | | `unity://tests/{mode}` | Test list | | `unity://tags` | Tag list | | `unity://layers` | Layer list | | `unity://menu/items` | Menu items | </details> --- ## Custom Tools Use C# attributes to add custom tools — automatically discovered and registered at startup. See **Built-in** and **Custom** distinction in `Window > Unity MCP > Tools` tab. ```csharp using UnityEngine; using UnityMcp.Shared.Attributes; using UnityMcp.Shared.Models; [McpToolGroup("MyProject.Tools")] public static class MyTools { [McpTool("my_hello", "A simple greeting tool", ReadOnly = true)] public static ToolResult Hello( [Desc("Your name")] string name = "World") { return ToolResult.Json(new { message = $"Hello, {name}!" }); } [McpResource("unity://custom/status", "Custom Status", "Project-specific status resource")] public static ToolResult GetStatus() { return ToolResult.Json(new { projectName = Application.productName, objectCount = Object.FindObjectsByType<GameObject>( FindObjectsSortMode.None).Length }); } } ``` Import the complete example through `Package Manager > Unity MCP > Samples > Custom Tools Example`. ### Attribute Reference | Attribute | Target | Description | |------|------|------| | `[McpToolGroup("name")]` | Class | Mark as MCP tool/resource/prompt container | | `[McpTool("name", "desc")]` | Method | Register as MCP tool. Options: `Group`, `ReadOnly`, `Idempotent`, `Title`, `AutoRegister` | | `[McpResource("uri", "name", "desc")]` | Method | Register as MCP resource. Options: `MimeType` | | `[McpPrompt("name", "desc")]` | Method | Register as MCP prompt | | `[Desc("description")]` | Parameter | Add description for parameter | ## Architecture ``` unity-mcp/ ├── unity-mcp/ # UPM Package (com.mzbswh.unity-mcp) │ ├── Editor/ │ │ ├── Core/ # McpServer, TcpTransport, RequestHandler, ToolRegistry │ │ │ ToolCallLogger, DependencyChecker, PackageUpdateChecker │ │ ├── Tools/ # 146 Built-in Tools │ │ ├── Resources/ # 13 Read-only Resources │ │ ├── Prompts/ # 48 Best Practice Prompts │ │ ├── Utils/ # Editor Utilities │ │ └── Window/ # Settings Interface, Client Configuration │ ├── Runtime/ # Runtime Mode (requires UNITY_MCP_RUNTIME) │ ├── Shared/ # Editor and Runtime Shared Code │ │ ├── Attributes/ # [McpTool], [McpResource], [McpPrompt], [Desc] │ │ ├── Models/ # ToolResult, McpConst, McpCapabilities, Pagination │ │ ├── Interfaces/ # IToolRegistry, ITcpTransport, IMainThreadDispatcher │ │ ├── Instance/ # Multi-Instance Discovery (InstanceDiscovery) │ │ └── Utils/ # PaginationHelper, ParameterBinder, JsonSchemaGenerator │ ├── Samples~/ # Custom Tool Examples │ └── Tests/ # EditMode Tests (9 test files) ├── unity-server/ # Python FastMCP Server (PyPI: unity-mcp-server) │ ├── unity_mcp_server/ │ │ ├── server.py # FastMCP Entry + Dynamic Tool Discovery Registration │ │ ├── unity_connection.py # TCP Connection Management + Auto-Reconnection │ │ ├── config.py # Environment Variable Configuration │ │ └── tools/ # Python Tools (PSD Parsing, Lakou Integration, etc.) │ ├── pyproject.toml # PyPI Package Configuration │ ├── Dockerfile # Docker Deployment │ └── docker-compose.yml └── scripts/ # bump-version.sh Version Management ``` ### How it Works The Unity plugin starts a TCP server when the Editor starts, scanning all methods with `[McpTool]`, `[McpResource]`, and `[McpPrompt]` attributes and registering them. The MCP client starts the Python FastMCP server via stdio, which connects to the Unity TCP port, retrieves all tool/resource/prompt definitions using the `discover` command, and dynamically registers them with FastMCP. All subsequent MCP calls are executed through Python → TCP → Unity main thread. --- ## Runtime Mode (Experimental) Control a running game with MCP. Add `UNITY_MCP_RUNTIME` to `Player Settings > Scripting Define Symbols` to enable. Runtime Tools (8): `runtime_get_stats` / `runtime_time_scale` / `runtime_load_scene` / `runtime_invoke` / `runtime_get_logs` / `runtime_profiler_snapshot` / `screenshot_game` / `screenshot_camera` The runtime server listens on `port + 1`. --- ## Docker Deployment <details> <summary><b>Docker Configuration</b></summary> ```bash cd unity-server # stdio mode (default) docker compose up -d # Streamable HTTP mode UNITY_MCP_TRANSPORT=streamable-http docker compose up -d # Manual docker build -t unity-mcp-server . docker run -it --rm \ -e UNITY_MCP_HOST=host.docker.internal \ -e UNITY_MCP_PORT=51279 \ --add-host=host.docker.internal:host-gateway \ unity-mcp-server ``` | Environment Variable | Default Value | Description | |----------|--------|------| | `UNITY_MCP_HOST` | `127.0.0.1` | Unity Editor Host Address | | `UNITY_MCP_PORT` | `51279` | Unity Editor TCP Port | | `UNITY_MCP_TIMEOUT` | `60` | Request Timeout (seconds) | | `UNITY_MCP_TRANSPORT` | `stdio` | Transport Mode: `stdio` or `streamable-http` | | `UNITY_MCP_HTTP_PORT` | `8080` | HTTP Port (only `streamable-http` mode) | </details> --- ## Settings Access via `Window > Unity MCP`: | Setting | Default Value | Description | |------|--------|------| | Port | 51279 | TCP Port, can be modified for multi-instance scenarios | | Auto Start | Enabled | Automatically start MCP service when Unity starts | | Request Timeout | 60s | Maximum tool execution timeout | | Log Level | Info | Debug / Info / Warning / Error / Off | | Audit Log | Disabled | Record each tool call and duration | | Max Batch Operations | 50 | Maximum operations allowed in a single `batch_execute` call | --- ## Frequently Asked Questions <details> <summary><b>Server Not Started</b></summary> - Check the status indicator in `Window > Unity MCP`. Green = running. - Click the **Restart** button to restart. - View `[MCP]` logs in the Unity Console. - If prompted to install Python/uv during the first startup, follow the instructions. </details> <details> <summary><b>MCP Client Cannot Connect</b></summary> - Confirm the port in the client configuration matches the port displayed in `Window > Unity MCP`. - Ensure Python 3.10+ and `uvx` are installed (run `uvx --version` to check). - If using multiple instances, ensure the `UNITY_MCP_PORT` environment variable is set correctly. - Check if the client is displayed as **Configured** in the Clients tab. </details> <details> <summary><b>Custom Tool Not Displayed</b></summary> - Ensure the tool class is marked with `[McpToolGroup]` and the method is marked with `[McpTool]`. - Check if the script compiles successfully. - Tools are scanned during startup; click **Restart** after adding a new tool. - View the **Custom** area in the Tools tab. </details> <details> <summary><b>Domain Reload Causes Disconnection</b></summary> This is expected behavior. When Unity scripts are recompiled, the TCP connection is temporarily interrupted but automatically handled: 1. Unity sends a `notifications/reloading` notification before domain reload. 2. After TCP disconnection, the Python server automatically enters exponential backoff reconnection (0s → 1s → 2s → 4s → ...). 3. During reconnection, MCP client requests are cached. 4. After Unity recompilation, TCP is restored, and cached requests are replayed automatically. The entire process is nearly transparent to the MCP client, usually recovering within 2-5 seconds. </details> --- ## System Requirements - **Unity** 2021.2+ - **Python** 3.10+ (recommended to use `uvx`, which automatically installs dependencies) - **Unity Dependencies**: `com.unity.nuget.newtonsoft-json` 3.2.1+ (automatically resolved) - **Python Dependencies** (automatically installed): `mcp`, `psd-tools` (PSD parsing), `httpx` (Lakou integration) ## License [MIT](LICENSE)