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.
Feature | Description |
|---|---|
  | Execute any Unity API code with full UnityEngine/Editor access |
  | Load, save, inspect scene hierarchy in real-time |
  | Enter/exit play mode and monitor status programmatically |
  | Retrieve and filter Unity console logs for debugging |
🚀 Quick Setup
📋 Prerequisites
🔑 Requirements
📥 Installation
📦 Choose your setup method
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
⚡ Install via Unity Package Manager
Step 1: Add Package via Git URL
In Unity Editor:
- Open Window → Package Manager
- Click the + button (top-left)
- Select Add package from git URL...
- Paste this URL:
https://github.com/muammar-yacoob/unity-mcp.git?path=/UnityPackage - 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:
- Open Tools → Unity MCP → Bridge Installer 🎯 Start here!
- 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
🎯 Step-by-step wizard for AI client setup
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
- Windows:
- Restart reminder included
Option B: Claude Code / VSCode
- Creates
.claude/config.jsonin 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?
- Download from nodejs.org
- Restart Unity Editor
- Click "Recheck Installation"
Can't connect?
- Verify server is running (Control Panel)
- Restart AI client after configuration
- Check firewall isn't blocking ports
⚡ WebSocket Transport (Default)
⚡ Fast, real-time bidirectional communication
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:
| Variable | Description | Default |
|---|---|---|
UNITY_MCP_TRANSPORT | Transport type: websocket or http | websocket |
UNITY_MCP_WS_PORT | WebSocket port | 8090 |
UNITY_MCP_TIMEOUT | Request timeout (ms) | 30000 |
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:
- Open Tools → Unity MCP → Control Panel to view status
- Configure port in MCPConfig ScriptableObject
- 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
🔧 View all 8 tools
⭐ execute_csharp
Tool | Description |
|---|---|
 | Execute ANY Unity operation with full UnityEngine and UnityEditor API access |
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)
Tool | Description |
|---|---|
  | Get complete scene hierarchy with GameObjects, components, and transforms |
  | Load scene by name or build index |
  | Save current scene or all open scenes |
📋 Console & Logging (1 tool)
Tool | Description |
|---|---|
  | Retrieve Unity console logs with filtering by type (log/warning/error) |
🧪 Play Mode Testing (3 tools)
Tool | Description |
|---|---|
  | Enter play mode programmatically with optional pause |
  | Exit play mode and return to edit mode |
  | Check if Unity is in play mode, edit mode, or paused |
💬 Example Commands
⭐ execute_csharp: The Swiss Army Knife
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"
🗺️ Scene Operations
- "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"
🧪 Play Mode Testing
- "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"
📋 Console & Debugging
- "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
⚙️ Manage settings and monitor status
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