Unity MCP Server

A Model Context Protocol (MCP) server for Unity Editor, enabling AI assistants like Claude to interact with Unity projects.

Features

• 69 Tools for manipulating scenes, GameObjects, components, prefabs, transforms, reflection, and more
• MCP Resources for live access to console logs, scene hierarchy, test results, and project files
• Auto-start Node.js server - no manual setup required
• Editor Window for monitoring and configuration
• Full test coverage with unit and integration tests

Requirements

• Unity 6 or later
• Node.js 18 or later

Installation

Direct git clone

cd YOUR_PROJECT/Packages
git clone https://github.com/Singtaa/UnityMCP.git com.singtaa.unity-mcp

Via Git URL (Package Manager)

1. Open Window > Package Manager
2. Click the + button > Add package from git URL
3. Enter: https://github.com/Singtaa/UnityMCP.git

Via git submodule

git submodule add https://github.com/Singtaa/UnityMCP.git Packages/com.singtaa.unity-mcp

Quick Start

1. Install the package
2. Open Window > Unity MCP Server
3. The server starts automatically when Unity opens
4. Configure your AI assistant to connect to http://127.0.0.1:5173/mcp

Configuration

Settings are stored in ProjectSettings/McpSettings.json:

| Setting | Default | Description | |---------|---------|-------------| | HTTP Port | 5173 | Port for MCP HTTP server | | IPC Port | 52100 | Port for Unity-Node TCP bridge | | Auto Start | true | Start server on Unity launch | | Auth Enabled | true | Require bearer token authentication |

Available Tools

Scene Management

• unity_scene_list - List all loaded scenes
• unity_scene_load - Load a scene
• unity_scene_save - Save scene(s)
• unity_scene_new - Create a new scene
• unity_scene_close - Close a scene

GameObject Operations

• unity_gameobject_create - Create GameObjects (with optional primitives)
• unity_gameobject_find - Find GameObjects by name, tag, or path
• unity_gameobject_delete - Delete GameObjects
• unity_gameobject_set_active - Enable/disable GameObjects
• unity_gameobject_set_parent - Reparent GameObjects
• unity_gameobject_rename - Rename GameObjects
• unity_gameobject_duplicate - Duplicate GameObjects

Component Management

• unity_component_list - List components on a GameObject
• unity_component_add - Add components
• unity_component_remove - Remove components
• unity_component_set_enabled - Enable/disable components
• unity_component_get_properties - Get component properties
• unity_component_set_property - Set component properties

Transform Operations

• unity_transform_get - Get position/rotation/scale
• unity_transform_set - Set position/rotation/scale
• unity_transform_translate - Move by delta
• unity_transform_rotate - Rotate by euler angles
• unity_transform_look_at - Orient toward target
• unity_transform_reset - Reset to identity

Editor Operations

• unity_selection_get/set/focus - Editor selection
• unity_editor_execute_menu_item - Execute menu commands
• unity_editor_notification - Show notifications
• unity_editor_log - Log to console
• unity_editor_get_state - Get editor state
• unity_editor_pause/step - Playmode control
• unity_undo_* - Undo/redo operations

Prefab Operations

• unity_prefab_load - Load a prefab asset for inspection/editing
• unity_prefab_save - Save changes to a prefab
• unity_prefab_get_hierarchy - Get full prefab hierarchy
• unity_prefab_find_component - Find component within prefab by path

Testing

• unity_test_list - List available tests (returns structured JSON with status field)
• unity_test_run - Run tests asynchronously, returns runId for polling
• unity_test_run_sync - Start EditMode tests (not truly sync; poll get_results)
• unity_test_get_results - Get test results by runId

Note: After domain reload (script recompilation), wait ~1 second before calling test tools. If unity_test_list returns status: "not_ready", you can still run tests directly with unity_test_run (without filter) and see all tests in the results.

Project & Assets

• unity_project_list_files - List project files
• unity_project_read_text - Read text files
• unity_project_write_text - Write text files
• unity_assets_refresh - Refresh AssetDatabase
• unity_assets_import - Import specific assets

Reflection & Decompilation

• unity_reflection_search_types - Search for types by name pattern across all assemblies
• unity_reflection_get_type_info - Get detailed structured JSON data about a type's members
• unity_reflection_get_method_info - Get method overloads with full parameter details
• unity_reflection_get_public_api - Get concise C# interface stub (best for quick API overview)
• unity_reflection_get_assemblies - List all loaded assemblies
• unity_reflection_decompile - Decompile type/method to C# source code
• unity_reflection_invoke_static - Invoke parameterless static methods/properties

MCP Resources

| Resource URI | Description | |--------------|-------------| | unity://console/logs | Live console output | | unity://hierarchy | Scene hierarchy | | unity://hierarchy/{scene} | Specific scene hierarchy | | unity://tests/results | Latest test results | | unity://project/files | Project file tree |

Architecture

┌─────────────────────────────────────────────────────────────┐
│                      AI Assistant                           │
├─────────────────────────────────────────────────────────────┤
│                 HTTP JSON-RPC (Port 5173)                   │
├─────────────────────────────────────────────────────────────┤
│              Node.js MCP Server (Server~/)                  │
├─────────────────────────────────────────────────────────────┤
│                TCP NDJSON (Port 52100)                      │
├─────────────────────────────────────────────────────────────┤
│                Unity Editor C# Bridge                       │
│  (McpBridge → ToolRegistry → MainThreadDispatcher)          │
├─────────────────────────────────────────────────────────────┤
│                     Unity APIs                              │
└─────────────────────────────────────────────────────────────┘

Development

Running Tests

Open Window > General > Test Runner and run:

• EditMode tests for unit and integration tests
• PlayMode tests for runtime behavior

Building the Node Server

The Node.js server is in Server~/. Dependencies are installed automatically on first run.

License

MIT License - see LICENSE for details.

Contributing

Contributions are welcome! Please read our contributing guidelines and submit PRs to the main branch.