@spark-apps/unity-mcp

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

🔑 Requirements

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

📥 Installation

📦 Choose your installation method

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

⚡ Required one-time setup per Unity project

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:

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

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

• 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
• Restart Unity Editor
• Verify in Console: [Unity MCP] Server started on port 8080

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

🛠️ Available Tools

🔧 View All Available Tools (19 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

🎯 Object Manipulation

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

🧪 Automated Testing

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

🗺️ Scene Operations

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

❌ Common Issues

MCP Server Not Showing:

• Verify Node.js is installed: node --version
• Check config file path is correct
• Ensure JSON syntax is valid
• Restart MCP client completely

Unity Editor Not Responding:

• Ensure Unity Editor is open
• Check Assets/Editor/UnityMCP/ scripts are installed
• Verify Console for [Unity MCP] Server started on port 8080
• Check no errors in Unity Console

Port Already in Use:

• Default port is 8080
• Check what's using it: lsof -i :8080 (Mac/Linux) or netstat -ano | findstr :8080 (Windows)
• 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