Unity MCP

🎮 Control Unity Editor • ⚡ Execute ANY Unity API • 🚀 Simplified & Powerful

✨ What It Does

Unity MCP provides real-time control of Unity Editor via the Model Context Protocol. Use it from Claude Desktop, Cursor, or any MCP client to create and modify games with natural language prompts.

Related MCP server: Unity MCP

🚀 Quick Setup

📋 Prerequisites

• Node.js >= 18.0.0 - Download

• Unity 2022.3 LTS or later - Download

• Claude Desktop or any MCP client - Download

📥 Installation

Method 1: Automatic Setup (Recommended) ⚡

One command does everything:

claude mcp add @spark-apps/unity-mcp

✅ Installs the package ✅ Configures your MCP client automatically ✅ Ready to use immediately after restart

Method 2: Manual Setup 🛠️

If you prefer to configure manually or use a different MCP client:

Step 1: Install the package globally

npm i -g @spark-apps/unity-mcp

Step 2: Add to your MCP client configuration

Edit your MCP client config file:

• Windows %APPDATA%\\Claude\\claude_desktop_config.json

• macOS ~/Library/Application Support/Claude/claude_desktop_config.json

• Linux ~/.config/Claude/claude_desktop_config.json

Add this configuration:

{
  "mcpServers": {
    "unity-mcp": {"command": "npx", "args": ["-y", "@spark-apps/unity-mcp"]}
  }
}

Step 3: Restart your MCP client

🎮 Unity Editor Integration

Step 1: Add Package via Git URL

In Unity Editor:

1. Open Window → Package Manager

2. Click the + button (top-left)

3. Select Add package from git URL...

4. Paste this URL:

   https://github.com/muammar-yacoob/unity-mcp.git?path=/UnityPackage

5. Click Add

Unity will install the package with all editor scripts:

• 🚀 Bridge Installer - Beautiful wizard for AI client setup

• ⚡ WebSocket server - Fast, real-time communication (port 8090)

• 🎨 Control Panel UI - Status monitoring with 🟢🟠🔴⚪ indicators

• ⚙️ ScriptableObject config - Persistent settings across sessions

• ⭐ 8 Essential Tools - Simplified architecture with execute_csharp for unlimited flexibility

Step 2: Configure AI Client

After installation:

1. Open Tools → Unity MCP → Bridge Installer 🎯 Start here!

2. Follow the setup wizard to configure your AI client

The Bridge Installer will:

• ✅ Check Node.js installation

• 🎯 Auto-configure Claude Desktop or Claude Code

• 📝 Provide manual config for other MCP clients

• 🎉 Guide you to completion

Done! Use the Control Panel (Tools → Unity MCP → Control Panel) to manage settings and monitor your connection.

🚀 Bridge Installer Guide

The Bridge Installer provides a beautiful wizard to configure your AI client in just a few clicks.

Opening the Installer

After installing the Unity package, open Unity and navigate to:

Tools → Unity MCP → Bridge Installer

Wizard Steps

Step 1: Welcome & Requirements

• View what you'll get

• Check prerequisites

• ✅ Unity 2022.3+

• ✅ Node.js 18.0+

• ✅ AI client (Claude Desktop, etc.)

Step 2: Node.js Verification

• Automatic detection of Node.js version

• Download link if not installed

• Recheck button after installation

Step 3: Configure AI Client

Choose your setup method:

Option A: Claude Desktop (One-Click)

• Automatically creates configuration at:

  • Windows: %APPDATA%\Claude\claude_desktop_config.json

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

  • Linux: ~/.config/Claude/claude_desktop_config.json

• Restart reminder included

Option B: Claude Code / VSCode

• Creates .claude/config.json in your project

• Works with Claude Code CLI and VSCode MCP extension

Option C: Manual Configuration

• Copy-paste ready JSON config

• Platform-specific paths provided

• For other MCP clients

Step 4: Complete!

• Success confirmation

• Next steps guide

• Quick launch to Control Panel

Troubleshooting

Node.js not detected?

1. Download from nodejs.org

2. Restart Unity Editor

3. Click "Recheck Installation"

Can't connect?

1. Verify server is running (Control Panel)

2. Restart AI client after configuration

3. Check firewall isn't blocking ports

⚡ WebSocket Transport (Default)

Unity MCP uses WebSocket by default for maximum speed and real-time control.

Default Configuration

The WebSocket server in Unity auto-starts on port 8090 when you install the package.

Advanced Configuration

You can customize ports and timeouts via environment variables:

Example with custom port:

{
  "mcpServers": {
    "unity-mcp": {
      "command": "npx",
      "args": ["-y", "@spark-apps/unity-mcp"],
      "env": {
        "UNITY_MCP_WS_PORT": "9090"
      }
    }
  }
}

Unity Editor Configuration

WebSocket server auto-starts when Unity loads. You can also:

1. Open Tools → Unity MCP → Control Panel to view status

2. Configure port in MCPConfig ScriptableObject

3. Manually restart via Tools → Unity MCP → Start WebSocket Server

Why WebSocket?

• ⚡ Lower latency - Real-time bidirectional communication

• 🚀 Faster execution - Persistent connection, no handshake overhead

• 🔄 Better for automation - Ideal for rapid command sequences

• 📡 Modern protocol - JSON-RPC 2.0 over WebSocket

HTTP transport is still available as a fallback by setting UNITY_MCP_TRANSPORT=http

🛠️ Available Tools

⭐ execute_csharp

Example Usage:

// Select all enemies and move them up
execute_csharp({
  code: `
    var enemies = GameObject.FindGameObjectsWithTag("Enemy");
    foreach (var enemy in enemies) {
      enemy.transform.position += Vector3.up * 2;
    }
    return $"Moved {enemies.Length} enemies";
  `
})

// Create a cube with custom material
execute_csharp({
  code: `
    var cube = GameObject.CreatePrimitive(PrimitiveType.Cube);
    cube.name = "AICube";
    var renderer = cube.GetComponent<Renderer>();
    renderer.material.color = Color.cyan;
    return "Created glowing cyan cube";
  `
})

Real-World Example - Build a Complete Game:

"Build a 3D Flappy Bird using execute_csharp: sky blue ortho camera, 
yellow sphere bird with Rigidbody physics (zero velocity before jump), 
8 green cube pipes that move left and reset when off-screen, 
TextMeshPro score UI, and game over panel on collision."

This single prompt creates an entire playable game by streaming C# code to Unity via MCP!

🗺️ Scene Operations (3 tools)

📋 Console & Logging (1 tool)

🧪 Play Mode Testing (3 tools)

💬 Example Commands

Object Selection & Manipulation:

• "Use execute_csharp to select all enemies and move them 5 units up"

• "Execute C# code to align all UI buttons horizontally"

• "Use execute_csharp to duplicate the Player object 10 times in a circle"

• "Find all cameras and set their field of view to 60"

Component Management:

• "Add a Rigidbody component to all objects tagged 'Box'"

• "Remove all AudioSource components from inactive objects"

• "Set the color of all materials with 'Enemy' in their name to red"

• "Enable collision on all objects in the 'Props' layer"

Scene Automation:

• "Create 100 cubes in a 10x10 grid at y=0"

• "Delete all objects with missing scripts"

• "Parent all 'Weapon' tagged objects under the Player"

• "Bake all lights and generate lightmap UVs"

Advanced Operations:

• "Run the Build Player menu command"

• "Install the TextMeshPro package"

• "Create a new C# script called 'EnemyAI' in Assets/Scripts/"

• "Execute a custom editor window that you define"

• "Load the MainMenu scene"

• "Show me the complete hierarchy of the current scene"

• "Save all open scenes"

• "Get the hierarchy and find all disabled objects"

• "Enter play mode"

• "Check if we're in play mode and show the console logs"

• "Exit play mode and save the scene"

• "Enter play mode, then use execute_csharp to simulate player input"

• "Get all error logs from the console"

• "Show me the last 10 warnings"

• "Clear console, then use execute_csharp to log custom debug info"

🎛️ Unity Control Panel

Once installed, access the Control Panel via Tools → Unity MCP → Control Panel.

Features:

• 🟢 Real-time Status Monitoring

  • 🟢 Connected - Server running normally

  • 🟠 Starting - Server is initializing

  • 🔴 Error - Connection failed

  • ⚪ Disconnected - Server stopped

• ⚙️ Server Settings (Collapsable)

  • Port configuration (default: 8090)

  • Auto-start on Unity load

  • Request timeout settings

  • Remote connections (⚠️ use with caution)

• ✨ Features (Collapsable)

  • Console monitoring (max logs configurable)

  • Auto-refresh assets on changes

  • Verbose logging for debugging

• ⚡ Quick Actions (Collapsable)

  • 📋 View Console Logs

  • 🔄 Refresh Assets

  • 💾 Save Scene

  • 🧹 Clear Console

  • 📁 Open Config

  • 📖 Documentation

• 🔧 Tools Overview (Collapsable)

  • View all 8 essential tools categorized by type

  • Highlights execute_csharp as the killer tool

  • Quick reference without leaving Unity

• ⚡ Advanced Settings (Collapsable)

  • Undo/Redo support

  • Auto-backup scenes

  • Reset to defaults

Configuration is stored as a ScriptableObject: Assets/Editor/UnityMCP/Resources/MCPConfig.asset

All settings persist across Unity sessions!

🌱 Support & Contributions

⭐ Star the repo & I power up like Mario 🍄
☕ Devs run on coffee - Buy me one?
💰 Crypto tips welcome - Tip in crypto
🤝 Contributions are welcome - 🍴 Fork, improve, PR!
🎥 Need help? Setup Tutorial • Join Discord

💖 Sponsor

Your support helps maintain and improve the tool. please consider sponsoring the project.

Made with ❤️ for Game Devs • Privacy Policy • Terms of Service