Unity MCP Server

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

Features

• 71 Tools for manipulating scenes, GameObjects, components, prefabs, transforms, reflection, capture, 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 2022.3 LTS or later (Unity 6 recommended)
• 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

The McpSettings.json ports are the team-preferred defaults (the file is meant to be committed). If they're taken when the server starts (typically by another Unity project's MCP server), a free port pair is allocated automatically and stored per-machine in UserSettings/McpPortOverride.json (gitignored), so one machine's port shuffle never gets committed to the team. Changing ports manually in the MCP Server window updates the shared settings and clears the local override. The window always shows the project's current endpoint URL.

Multiple Unity Editors

Each open project runs its own server on its own port pair, so multiple Editors can be used side by side, each with its own MCP endpoint:

1. The first project gets the default ports (HTTP 5173 / IPC 52100)
2. The next project detects the ports are taken, asks the running server which project it belongs to (bridge.identify), and auto-allocates the next free pair (e.g. 5174/52101)
3. Allocated ports are persisted per-machine, so endpoints stay stable across sessions

Point each AI assistant at the project's own endpoint (shown in Window > Unity MCP Server) with that project's own auth token. The server also validates project identity on every bridge connection, so an Editor can never take over a server belonging to a different project - even with misconfigured ports.

If you start the Node server manually (node src/server.js), set MCP_PROJECT_ROOT to the project path so Editors can identify it; without it, the server accepts whichever project connects first.

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.

Capture

• unity_capture_panel - Render a UI Toolkit PanelSettings to a PNG (returned as an MCP image content block). Renders to an off-screen RenderTexture so the output has no Scene chrome. Auto-detects the active panel via UIDocuments in loaded scenes if panelPath is omitted.
• unity_capture_game_view - Capture the Game view to a PNG. Uses ScreenCapture.CaptureScreenshotAsTexture in play mode.

Note: unity_capture_panel currently produces a blank image in edit mode (offscreen render doesn't fire on the first frame after targetTexture is reassigned). Use play mode for reliable panel captures until this is resolved. unity_capture_game_view only works in play mode in Unity 6.3+ (PlayModeView.targetTexture is not exposed via reflection in edit mode).

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.