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)
- 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 scenesunity_scene_load- Load a sceneunity_scene_save- Save scene(s)unity_scene_new- Create a new sceneunity_scene_close- Close a scene
GameObject Operations
unity_gameobject_create- Create GameObjects (with optional primitives)unity_gameobject_find- Find GameObjects by name, tag, or pathunity_gameobject_delete- Delete GameObjectsunity_gameobject_set_active- Enable/disable GameObjectsunity_gameobject_set_parent- Reparent GameObjectsunity_gameobject_rename- Rename GameObjectsunity_gameobject_duplicate- Duplicate GameObjects
Component Management
unity_component_list- List components on a GameObjectunity_component_add- Add componentsunity_component_remove- Remove componentsunity_component_set_enabled- Enable/disable componentsunity_component_get_properties- Get component propertiesunity_component_set_property- Set component properties
Transform Operations
unity_transform_get- Get position/rotation/scaleunity_transform_set- Set position/rotation/scaleunity_transform_translate- Move by deltaunity_transform_rotate- Rotate by euler anglesunity_transform_look_at- Orient toward targetunity_transform_reset- Reset to identity
Editor Operations
unity_selection_get/set/focus- Editor selectionunity_editor_execute_menu_item- Execute menu commandsunity_editor_notification- Show notificationsunity_editor_log- Log to consoleunity_editor_get_state- Get editor stateunity_editor_pause/step- Playmode controlunity_undo_*- Undo/redo operations
Prefab Operations
unity_prefab_load- Load a prefab asset for inspection/editingunity_prefab_save- Save changes to a prefabunity_prefab_get_hierarchy- Get full prefab hierarchyunity_prefab_find_component- Find component within prefab by path
Testing
unity_test_list- List available tests (returns structured JSON withstatusfield)unity_test_run- Run tests asynchronously, returnsrunIdfor pollingunity_test_run_sync- Start EditMode tests (not truly sync; pollget_results)unity_test_get_results- Get test results byrunId
Note: After domain reload (script recompilation), wait ~1 second before calling test tools. If
unity_test_listreturnsstatus: "not_ready", you can still run tests directly withunity_test_run(without filter) and see all tests in the results.
Project & Assets
unity_project_list_files- List project filesunity_project_read_text- Read text filesunity_project_write_text- Write text filesunity_assets_refresh- Refresh AssetDatabaseunity_assets_import- Import specific assets
Reflection & Decompilation
unity_reflection_search_types- Search for types by name pattern across all assembliesunity_reflection_get_type_info- Get detailed structured JSON data about a type's membersunity_reflection_get_method_info- Get method overloads with full parameter detailsunity_reflection_get_public_api- Get concise C# interface stub (best for quick API overview)unity_reflection_get_assemblies- List all loaded assembliesunity_reflection_decompile- Decompile type/method to C# source codeunity_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.