README.md•17.3 kB
[//]: # (Constants)
[license-link]: ../../blob/main/LICENSE
[stars-link]: ../../stargazers
[issues-link]: ../../issues
[discord-link]: https://discord.gg/5skXfKRytR
[website-link]: https://spark-games.co.uk
[coffee-link]: https://buymeacoffee.com/spark88
[release-link]: ../../releases
[fork-link]: ../../fork
[privacy-link]: ./PRIVACY.md
[vid-link]: https://www.youtube.com/shorts/CCbY_ETwFss
# Unity MCP
<div align="center">
**🎮 Control Unity Editor • ⚡ Execute ANY Unity API • 🚀 Simplified & Powerful**
[](https://www.npmjs.com/package/@spark-apps/unity-mcp)
[](https://www.npmjs.com/settings/spark-apps/packages)
[][license-link]
[](https://github.com/sponsors/muammar-yacoob)
[][discord-link]
[][stars-link]
<img src="res/MCP.png" alt="Unity MCP">
</div>
## ✨ 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.
| <div align="left">Feature</div> | <div align="left">Description</div> |
|:---------|:-------------|
|  | 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
<details>
<summary><strong>🔑 Requirements</strong></summary>
- **Node.js** >= 18.0.0 - [Download](https://nodejs.org/)
- **Unity** 2022.3 LTS or later - [Download](https://unity.com/)
- **Claude Desktop** or any MCP client - [Download](https://claude.ai/download)
</details>
---
## 📥 Installation
<details>
<summary><strong>📦 Choose your setup method</strong></summary>
### Method 1: Automatic Setup (Recommended) ⚡
**One command does everything:**
```bash
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**
```bash
npm i -g @spark-apps/unity-mcp
```
**Step 2: Add to your MCP client configuration**
Edit your MCP client config file:
- <span style="background: #1e90ff; color: white; padding: 2px 6px; border-radius: 3px; font-size: 11px; font-weight: bold;">Windows</span> `%APPDATA%\\Claude\\claude_desktop_config.json`
- <span style="background: #c0c0c0; color: black; padding: 2px 6px; border-radius: 3px; font-size: 11px; font-weight: bold;">macOS</span> `~/Library/Application Support/Claude/claude_desktop_config.json`
- <span style="background: #ffd700; color: black; padding: 2px 6px; border-radius: 3px; font-size: 11px; font-weight: bold;">Linux</span> `~/.config/Claude/claude_desktop_config.json`
Add this configuration:
```json
{
"mcpServers": {
"unity-mcp": {"command": "npx", "args": ["-y", "@spark-apps/unity-mcp"]}
}
}
```
**Step 3: Restart your MCP client**
</details>
---
## 🎮 Unity Editor Integration
<details>
<summary><strong>⚡ Install via Unity Package Manager</strong></summary>
### 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.
</details>
---
## 🚀 Bridge Installer Guide
<details>
<summary><strong>🎯 Step-by-step wizard for AI client setup</strong></summary>
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](https://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
</details>
---
## ⚡ WebSocket Transport (Default)
<details>
<summary><strong>⚡ Fast, real-time bidirectional communication</strong></summary>
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:**
```json
{
"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`
</details>
---
## 🛠️ Available Tools
<details>
<summary><strong>🔧 View all 8 tools</strong></summary>
### **⭐ execute_csharp**
| <div align="left">Tool</div> | <div align="left">Description</div> |
|:------|:-------------|
|  | Execute ANY Unity operation with full UnityEngine and UnityEditor API access |
**Example Usage:**
```typescript
// 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)**
| <div align="left">Tool</div> | <div align="left">Description</div> |
|:------|:-------------|
|  | 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)**
| <div align="left">Tool</div> | <div align="left">Description</div> |
|:------|:-------------|
|  | Retrieve Unity console logs with filtering by type (log/warning/error) |
---
### **🧪 Play Mode Testing (3 tools)**
| <div align="left">Tool</div> | <div align="left">Description</div> |
|:------|:-------------|
|  | 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 |
</details>
---
## 💬 Example Commands
<details>
<summary><strong>⭐ execute_csharp: The Swiss Army Knife</strong></summary>
**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"*
</details>
<details>
<summary><strong>🗺️ Scene Operations</strong></summary>
- *"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"*
</details>
<details>
<summary><strong>🧪 Play Mode Testing</strong></summary>
- *"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"*
</details>
<details>
<summary><strong>📋 Console & Debugging</strong></summary>
- *"Get all error logs from the console"*
- *"Show me the last 10 warnings"*
- *"Clear console, then use execute_csharp to log custom debug info"*
</details>
---
## 🎛️ Unity Control Panel
<details>
<summary><strong>⚙️ Manage settings and monitor status</strong></summary>
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!
</details>
---
## 🌱 Support & Contributions
⭐ **Star the repo** & I power up like Mario 🍄
☕ **Devs run on coffee** - [Buy me one?][coffee-link]
💰 **Crypto tips welcome** - [Tip in crypto](https://tip.md/muammar-yacoob)
🤝 **Contributions are welcome** - [🍴 Fork][fork-link], improve, PR!
🎥 **Need help?** <img src="https://img.icons8.com/color/20/youtube-play.png" alt="YouTube" width="20" height="20" style="vertical-align: middle;"> [Setup Tutorial][vid-link] • <img src="https://img.icons8.com/color/20/discord--v2.png" alt="Discord" width="20" height="20" style="vertical-align: middle;"> [Join Discord][discord-link]
## 💖 Sponsor
Your support helps maintain and improve the tool. please consider [sponsoring the project][stars-link].
---
<div align="center">
**Made with ❤️ for Game Devs** • [Privacy Policy](PRIVACY.md) • [Terms of Service](TERMS.md)