Skip to content

README.md

Latest commit

 

History

History
180 lines (138 loc) · 7.72 KB

README.md

File metadata and controls

180 lines (138 loc) · 7.72 KB

Unity MCP Server

Unity 6+ License: MIT

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.