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:

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

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.