README.md•16.2 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 • ⚡ Real-time automation • 🚀 AI-powered workflows**
[](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 allowing you to:
| <div align="left">Feature</div> | <div align="left">Description</div> |
|:---------|:-------------|
|  | Select, move, rotate, and scale objects with natural language |
|  | Align, distribute, duplicate objects with undo support |
|  | Enter play mode and run test scenarios programmatically |
|  | Load, save, inspect scene hierarchy in real-time |
## 🚀 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
> **⚠️ REQUIRED:** You must install Unity MCP before using any of its tools.
<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>⚡ One-time setup per Unity project</strong></summary>
Tell Claude to set up the integration:
```
Setup Unity MCP in my project at /path/to/unity/project
```
This installs 8 editor scripts to `Assets/Editor/UnityMCP/` including:
- HTTP server with auto-start (port 8080)
- Control Panel UI with 🟢🟠🔴⚪ status monitoring
- ScriptableObject configuration for persistent settings
- Handlers for all 30 tools
**After installation:**
1. Restart Unity Editor
2. Open **Tools → Unity MCP → Control Panel**
3. Verify 🟢 **Connected** status
Done! Use the Control Panel to manage settings and monitor your connection.
</details>
---
## 🛠️ Available Tools
<details>
<summary><strong>🔧 View All 30 Available Tools</strong></summary>
### **🎯 Editor Control (7 tools)**
| <div align="left">Tool</div> | <div align="left">Description</div> |
|:------|:-------------|
|  | Install editor integration into Unity project |
|  | Select by name, tag, or pattern with framing |
|  | Move, rotate, scale objects |
|  | Align left/right/top/bottom/center |
|  | Distribute evenly along axis |
|  | Clone objects with undo support |
|  | Find by component type or pattern |
### **🗺️ Scene Management (6 tools)**
| <div align="left">Tool</div> | <div align="left">Description</div> |
|:------|:-------------|
|  | List all scenes in build settings |
|  | Load scene by name or index |
|  | Save current or all scenes |
|  | Get complete scene hierarchy |
|  | Find objects in current scene |
|  | Remove missing scripts and empty objects |
### **🧪 Testing & Play Mode (5 tools)**
| <div align="left">Tool</div> | <div align="left">Description</div> |
|:------|:-------------|
|  | Start play mode programmatically |
|  | Exit play mode programmatically |
|  | Execute automated test scenarios |
|  | Get play mode status and logs |
|  | Slow motion or fast forward |
### **📦 Assets & Console (5 tools)**
| <div align="left">Tool</div> | <div align="left">Description</div> |
|:------|:-------------|
|  | Retrieve Unity console logs for debugging |
|  | Clear all console logs |
|  | Create prefab from selected GameObject |
|  | List project assets with filtering |
|  | Refresh Unity asset database |
### **⚡ Advanced Tools (7 tools)**
| <div align="left">Tool</div> | <div align="left">Description</div> |
|:------|:-------------|
|  | Execute any Unity Editor menu command |
|  | Install Unity packages via Package Manager |
|  | Execute Test Runner tests (EditMode/PlayMode) |
|  | Add prefab or asset to current scene |
|  | Create, read, update, delete C# scripts |
|  | Validate C# script syntax |
|  | Delete objects with undo support |
</details>
---
## 💬 Example Commands
<details>
<summary><strong>🎯 Object Manipulation</strong></summary>
- *"Select all objects with tag 'Enemy' and align them horizontally"*
- *"Move the Player object to position (0, 5, 10)"*
- *"Distribute selected objects evenly along the x axis"*
- *"Find all objects with Camera component"*
- *"Duplicate selected object 5 times"*
</details>
<details>
<summary><strong>🧪 Automated Testing</strong></summary>
- *"Enter play mode and move Player to (10, 0, 0) for 5 seconds"*
- *"Set time scale to 0.5 for slow motion"*
- *"Run a test that destroys the Boss after 2 seconds"*
- *"Check play mode status and show test logs"*
</details>
<details>
<summary><strong>🗺️ Scene Operations</strong></summary>
- *"List all scenes in the project"*
- *"Load the MainMenu scene"*
- *"Show me the complete hierarchy of the current scene"*
- *"Find all objects with Rigidbody component"*
- *"Clean up scene by removing missing scripts"*
</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: 8080)
- 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 30 available tools categorized by type
- 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>
---
## 🐛 Troubleshooting
<details>
<summary><strong>🐞 Common Issues</strong></summary>
**MCP Server Not Showing:**
1. Verify Node.js is installed: `node --version`
2. Check config file path is correct
3. Ensure JSON syntax is valid
4. Restart MCP client completely
**Unity Editor Not Responding:**
1. Ensure Unity Editor is open
2. Check `Assets/Editor/UnityMCP/` scripts are installed
3. Verify Console for `[Unity MCP] Server started on port 8080`
4. Check no errors in Unity Console
**Port Already in Use:**
1. Default port is `8080`
2. Check what's using it: `lsof -i :8080` (Mac/Linux) or `netstat -ano | findstr :8080` (Windows)
3. Stop conflicting process or change port in Unity scripts
</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)