Abbabon/unity-mcp-sharp

• Real-time bidirectional communication with Unity Editor
• Extensible command/response pattern
• Support for Unity operations and queries

• Multiple Unity Editors: Connect multiple Unity Editor instances to a single MCP server
• Per-Session Selection: Each MCP client (LLM session) can select and work with different editors independently
• Smart Auto-Selection: Single editor scenarios work seamlessly without manual selection
• Persistent Across Recompilations: Editor selection survives Unity script compilation reconnects
• Rich Metadata: Each editor reports project name, scene, machine, process ID, Unity version

• ✅ All tools return confirmation messages for reliable feedback
• 🔗 Tool descriptions include cross-references for chaining operations
• ⚠️ Side effects and warnings clearly documented
• 📝 Rich return descriptions help LLMs understand responses

• 🎨 UIToolkit-based dashboard with status monitoring
• 👁️ Visual feedback system with operation tracking
• 🐳 Docker container lifecycle management
• 🔄 Auto-connect and auto-start capabilities
• ⚙️ Configuration via ScriptableObject

• Built with .NET 9.0 and ASP.NET Core
• Published to GitHub Container Registry (ghcr.io)
• Multi-platform support (linux/amd64, linux/arm64)
• Full CI/CD pipeline with GitHub Actions

1. Open Unity Package Manager
2. Click + → "Add package from git URL..."
3. Enter: https://github.com/Abbabon/unity-mcp-sharp.git

Add to Packages/manifest.json:

{
  "dependencies": {
    "com.mezookan.unity-mcp-sharp": "https://github.com/Abbabon/unity-mcp-sharp.git"
  }
}

1. Install Docker Desktop (if not already installed)

   • Download from docker.com
   • Start Docker Desktop

2. Open the Setup Wizard

   • In Unity: Tools → Unity MCP Server → Setup Wizard
   • Follow the on-screen instructions

3. Start the Server

   • Go to Tools → Unity MCP Server → Dashboard
   • Click "Start Server" (downloads Docker image on first run)
   • Click "Connect" to establish WebSocket connection

4. Verify Connection

   • Dashboard shows "Connected ✓" in green
   • Console logs: "Unity MCP Server connected successfully"

Add to .vscode/settings.json:

{
  "mcpServers": {
    "unity": {
      "url": "http://localhost:8080/mcp",
      "transport": "sse"
    }
  }
}

Add to ~/.cursor/config.json:

{
  "mcpServers": {
    "unity": {
      "url": "http://localhost:8080/mcp",
      "transport": "sse"
    }
  }
}

Add to your Claude Desktop MCP configuration:

{
  "mcpServers": {
    "unity": {
      "url": "http://localhost:8080/mcp",
      "transport": "sse"
    }
  }
}

New in v0.4: Resources are read-only, application-controlled data sources that provide fresh data on each access. They reduce LLM cognitive load by separating read operations from action-based tools.

unity://project/info

Unity project metadata including name, version, active scene, paths, and editor state.

Returns: Project information with name, Unity version, active scene, data path, play/pause state

💡 Tip: Use this first when starting work on a project to understand the environment.

🔄 Updates: Automatically when scenes change or play mode changes

unity://console/logs

Recent console logs from Unity Editor (errors, warnings, debug logs).

Returns: Console logs with type, message, and stack traces

💡 Tip: Check this after creating scripts, entering play mode, or when compilation fails.

🔄 Updates: Automatically when new log messages appear

unity://compilation/status

Current compilation status and last compilation result.

Returns: Compilation status (idle/compiling) and success/failure state

🔗 Related: unity_trigger_script_compilation

🔄 Updates: Automatically when compilation starts or finishes

unity://editor/playmode

Current play mode state of Unity Editor.

Returns: Play mode state (Playing, Paused, or Stopped)

🔗 Related: unity_enter_play_mode, unity_exit_play_mode

🔄 Updates: Automatically when play mode changes

unity://scenes/active

Information about the currently active Unity scene.

Returns: Scene name, path, isDirty status, root GameObject count, loaded state

💡 Tip: If isDirty is true, use unity_save_scene to save changes.

🔄 Updates: Automatically when active scene changes or scenes are loaded

unity://scenes/active/objects

Complete GameObject hierarchy of the active scene.

Returns: Hierarchical list with active/inactive state indicators

🔗 Related: unity_find_game_object, unity_create_game_object

🔄 Updates: Automatically when scenes change

unity://scenes/all

List of all .unity scene files in the project.

Returns: List of scene paths relative to project root

🔗 Related: unity_open_scene, unity_get_active_scene

🔄 Updates: When asset database refreshes

unity_trigger_script_compilation

Force Unity to recompile all C# scripts.

Returns: Confirmation that compilation was triggered

⚠️ Note: Unity temporarily disconnects during compilation. Use unity://compilation/status resource after to verify success.

unity_create_game_object

Create a new GameObject in the currently active scene.

Parameters:

• name (string, required): GameObject name
• x, y, z (float, default: 0): World position
• components (string, optional): Comma-separated components (e.g., "Rigidbody,BoxCollider")
• parent (string, optional): Parent GameObject name

Returns: Confirmation with name, position, components, and hierarchy location

📌 Example: Create a "Player" at position (0, 1, 0) with Rigidbody and CapsuleCollider

🔗 Related: unity_find_game_object, unity_add_component_to_object

unity_find_game_object

Find a GameObject by name, tag, or path with detailed information.

Parameters:

• name (string, required): GameObject name
• searchBy (string, default: "name"): Search mode: "name", "tag", or "path"

Returns: Position, rotation, scale, active state, and all attached components

🔗 Related: unity_list_scene_objects, unity_add_component_to_object

unity_add_component_to_object

Add a component to an existing GameObject.

Parameters:

• gameObjectName (string, required): Target GameObject
• componentType (string, required): Component type (e.g., "Rigidbody", "BoxCollider", custom scripts)

Returns: Confirmation that component was added

💡 Tip: Use unity_find_game_object first to verify the GameObject exists.

unity_set_component_field

Set a field or property value on a component attached to a GameObject.

Parameters:

• gameObjectName (string, required): Name of the GameObject with the component
• componentType (string, required): Type of the component (e.g., "Transform", "Rigidbody", custom scripts)
• fieldName (string, required): Field or property name to set (e.g., "enabled", "mass", "config")
• value (string, required): Value to set (primitive, asset path, or GameObject name)
• valueType (string, default: "string"): Type of value: "string", "int", "float", "bool", "asset", "gameObject"

Returns: Confirmation that field was set

📌 Example: Set ScriptableObject reference: valueType: "asset", value: "Assets/Config/MyConfig.asset"

🔗 Related: unity_find_game_object, unity_add_component_to_object

unity_list_scene_objects

Get the complete GameObject hierarchy of the active scene.

Returns: Hierarchical list with active/inactive state indicators

🔗 Related: unity_find_game_object, unity_create_game_object

unity_batch_create_game_objects

Create multiple GameObjects in a single operation (more efficient than one-by-one).

Parameters:

• gameObjectsJson (string, required): JSON array of GameObject specs

Returns: Confirmation that batch creation was initiated

unity_create_game_object_in_scene

Create a GameObject in a specific scene (not necessarily the active one).

Parameters:

• scenePath (string, required): Scene path (e.g., "Scenes/Level1.unity")
• name, x, y, z, components, parent: Same as unity_create_game_object

Returns: Confirmation with scene path, name, and position

⚠️ Note: If scene is not loaded, it will be opened additively first.

unity_list_scenes

List all .unity scene files in the project.

Returns: List of scene paths relative to project root

🔗 Related: unity_open_scene, unity_get_active_scene

unity_get_active_scene

Get information about the currently active scene.

Returns: Scene name, path, isDirty status, root GameObject count, loaded state

💡 Tip: Use unity_save_scene if isDirty is true to save changes.

unity_open_scene

Open a Unity scene by path.

Parameters:

• scenePath (string, required): Path relative to Assets folder
• additive (bool, default: false): Keep other scenes open if true

Returns: Confirmation with scene path and mode (single/additive)

🔗 Related: unity_list_scenes, unity_get_active_scene

unity_close_scene

Close a specific scene (only works with multiple scenes open).

Parameters:

• sceneIdentifier (string, required): Scene name or path

Returns: Confirmation that scene was closed

⚠️ Note: Cannot close the last open scene.

unity_save_scene

Save the active scene or a specific scene.

Parameters:

• scenePath (string, optional): Specific scene to save (null = active)
• saveAll (bool, default: false): Save all open scenes

Returns: Confirmation of which scene(s) were saved

⚠️ Important: Always save after making changes, otherwise they'll be lost!

unity_set_active_scene

Set which scene is active (where new GameObjects are created).

Parameters:

• sceneIdentifier (string, required): Scene name or path

Returns: Confirmation that scene is now active

⚠️ Note: Only works when multiple scenes are open.

unity_create_script

Create a new C# MonoBehaviour script file.

Parameters:

• scriptName (string, required): Script name (without .cs)
• folderPath (string, required): Path within Assets (e.g., "Scripts/Player")
• scriptContent (string, required): Full C# class code

Returns: Confirmation with file path and recompilation notice

🔗 Related: unity_get_compilation_status, unity_get_console_logs

unity_create_asset

Create any type of Unity asset with support for complex nested structures using SerializedObject API.

Parameters:

• assetName (string, required): Asset name (without extension)
• folderPath (string, required): Path within Assets
• assetTypeName (string, required): Full type name (e.g., "UnityEngine.Material", custom ScriptableObject)
• propertiesJson (string, optional): JSON properties to set (supports nested objects, arrays, Lists)

Returns: Confirmation with asset name, type, and path

✨ New in v0.4: Enhanced with SerializedObject support for complex nested structures!

📌 Example properties:

• Material: {"shader":"Standard","color":"#FF0000"}
• Texture2D: {"width":256,"height":256}
• ScriptableObject with nested List:

{
  "primitives": [
    {
      "primitiveType": 0,
      "position": {"x": 0, "y": 0, "z": 0},
      "color": {"r": 1, "g": 0, "b": 0, "a": 1},
      "scale": {"x": 1, "y": 1, "z": 1}
    }
  ]
}

🎯 Supported Unity types: Vector3, Vector2, Color, Quaternion, Bounds, Rect, asset references, and more!

🔗 Related: unity_refresh_assets

unity_refresh_assets

Refresh Unity Asset Database to detect file changes.

Returns: Confirmation that refresh was initiated

💡 Use after: Batch file operations or when changes aren't detected automatically

⚠️ Note: Can take a few seconds for large projects. Use unity_get_compilation_status to check if recompilation is complete.

unity_enter_play_mode

Enter Unity play mode (start running the game).

Returns: Confirmation message with important warning

⚠️ IMPORTANT: Changes made in play mode are NOT saved! GameObjects created will be destroyed when exiting.

🔗 Related: unity_get_play_mode_state, unity_exit_play_mode

unity_exit_play_mode

Exit Unity play mode (stop running the game).

Returns: Confirmation that play mode was exited

⚠️ Note: All changes made during play mode will be reverted.

unity_get_play_mode_state

Get current play mode state.

Returns: Current state (Playing, Paused, or Stopped)

🔗 Related: unity_enter_play_mode, unity_exit_play_mode

unity_run_menu_item

Execute any Unity Editor menu item by its path.

Parameters:

• menuPath (string, required): Full menu path (e.g., "GameObject/Create Empty", "Edit/Undo")

Returns: Confirmation that menu item was executed

💡 Use as: Fallback for operations not covered by dedicated tools

📌 Examples:

• "GameObject/Create Empty"
• "Edit/Undo"
• "Assets/Refresh"

The project includes convenience scripts in Scripts~/:

# Build server + Docker image
./Scripts~/rebuild.sh

# Start MCP server container
./Scripts~/start-mcp-server.sh

# Run smoke tests
./Scripts~/test.sh

The package is structured as a Unity UPM package:

.
├── Runtime/              # Runtime scripts (MCPClient, MCPServerManager)
├── Editor/               # Editor scripts (Dashboard, Integration, Menu Items)
├── Documentation~/       # User documentation (excluded from package)
├── Scripts~/             # Development scripts (excluded from package)
├── Server~/              # MCP server (excluded from package)
├── TestProject~/         # Test Unity project (excluded from package)
└── package.json          # UPM manifest

Note: Directories with ~/ suffix are excluded from Unity package imports.

Solution: Install Docker Desktop and ensure it's running.

Download from docker.com

Possible causes:

1. Docker container not running → Start it from Dashboard
2. Port 8080 already in use → Change port in configuration
3. Firewall blocking connection → Allow Docker in firewall settings

Check logs:

docker logs unity-mcp-server

Or use the Logs tab in the Unity MCP Dashboard.

The package will automatically pull the image on first start. If this fails:

# Manually pull the image
docker pull ghcr.io/abbabon/unity-mcp-server:latest

Solution: The package automatically checks common Docker paths on macOS:

• /usr/local/bin/docker (Docker Desktop)
• /opt/homebrew/bin/docker (Homebrew on Apple Silicon)
• /usr/bin/docker (Standard location)

If still not found, ensure Docker Desktop is installed and running.

Starting with Unity 6.3, the Package Manager displays signature warnings for unsigned packages. This is informational only - the package still works correctly.

Options:

1. Download the signed .tgz from GitHub Releases (if available)
2. Install via OpenUPM (warning is cosmetic only)
3. See for details

The project includes comprehensive GitHub Actions workflows:

• Build Server - Builds and tests the .NET server on every push/PR
• Publish Docker - Publishes multi-arch images to ghcr.io on main branch
• Publish OpenUPM - Creates GitHub releases and guides OpenUPM publication on version tags

Creating a Release

# Update version in package.json
# Commit changes
git add package.json
git commit -m "Bump version to 1.0.0"

# Create and push tag
git tag v1.0.0
git push origin main --tags

This triggers the full CI/CD pipeline.