Unity MCP

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

✨ What It Does

Unity MCP provides real-time control of Unity Editor through the Model Context Protocol, allowing you to:

| Feature | Description | |:---------|:-------------| | | 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

• Node.js >= 18.0.0 - Download
• Unity 2022.3 LTS or later - Download
• Claude Desktop or any MCP client - Download

📥 Installation

Option 1: Claude Code (Recommended)

claude mcp add @spark-apps/unity-mcp

Option 2: Manual Installation

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

Then add to your MCP client config:

• Windows %APPDATA%\\Claude\\claude_desktop_config.json
• macOS ~/Library/Application Support/Claude/claude_desktop_config.json
• Linux ~/.config/Claude/claude_desktop_config.json

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

Restart your MCP client after installation.

🎮 Unity Editor Integration

Why is this needed? Unity MCP installs C# editor scripts into your Unity project that create an HTTP server on port 8080. The MCP tools communicate with Unity through this server.

Setup Steps:

1. Open your MCP client (e.g., Claude Desktop or Claude Code)
2. Tell Claude:

   Setup Unity MCP in my project at /path/to/unity/project

3. This installs 4 C# scripts to Assets/Editor/UnityMCP/:
   • MCPEditorServer.cs - HTTP server
   • EditorCommandHandler.cs - Command processor with undo support
   • PlayModeHandler.cs - Play mode automation
   • SceneHandler.cs - Scene operations
4. Restart Unity Editor
5. Verify in Console: [Unity MCP] Server started on port 8080

Done! The MCP tools can now control Unity Editor via HTTP.

🛠️ Available Tools

Safe Operations (Read-only) | Tool | Description | |:------|:-------------| | | Install editor integration into Unity project | | | Select by name, tag, or pattern with framing | | | Find by component type or pattern | | | List all scenes in build settings | | | Get complete scene hierarchy | | | Find objects in current scene | | | Get play mode status and logs |

Modifications (With Undo Support) | Tool | Description | |:------|:-------------| | | Move, rotate, scale objects | | | Align left/right/top/bottom/center | | | Distribute evenly along axis | | | Clone objects with undo support | | | Start play mode programmatically | | | Exit play mode programmatically | | | Execute automated test scenarios | | | Slow motion or fast forward | | | Load scene by name or index | | | Save current or all scenes |

Destructive Operations (Use with Caution) | Tool | Description | |:------|:-------------| | | Delete objects with undo support | | | Remove missing scripts and empty objects |

💬 Example Commands

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

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

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

🐛 Troubleshooting

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

📖 Documentation

• Unity Editor Scripting API
• Model Context Protocol
• Report Issues

🤝 Contributing

Contributions welcome! Focus areas:

• ✅ Editor manipulation and automation
• ✅ Testing workflows
• ✅ Scene management
• ✅ Bug fixes and improvements

Not in scope: Code generation (use context7 MCP instead)

📝 License

MIT © Muammar Yacoob

🌟 If Unity MCP saves you time, show some love!

Built with ❤️ for game developers who want to automate repetitive tasks