Unity MCP

<div align="center">

🎮 Control Unity Editor • ⚡ Real-time automation • 🚀 AI-powered workflows

<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
• Unity 2022.3 LTS or later - Download
• Claude Desktop or any MCP client - 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:

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:

• <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:

{
  "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?
💰 Crypto tips welcome - Tip in crypto
🤝 Contributions are welcome - 🍴 Fork, 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 • <img src="https://img.icons8.com/color/20/discord--v2.png" alt="Discord" width="20" height="20" style="vertical-align: middle;"> Join Discord

💖 Sponsor

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

---

<div align="center">

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