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

Via Git URL (Package Manager)

Open Window > Package Manager
Click the + button > Add package from git URL
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

Install the package
Open Window > Unity MCP Server
The server starts automatically when Unity opens
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.

UnityMCP