Architecture: Seamless Integration of Unity and AI

The Unity Machine Control Protocol (Unity MCP) creates a powerful bridge between your Unity Editor and AI systems, enabling real-time interaction and automation. This innovative solution consists of two main components working in harmony:

1. Unity Plugin (UnityMCPPlugin)

This robust Unity Editor plugin serves as the interface within your Unity environment, providing:

• A comprehensive debug window for monitoring connection status and activity
• A WebSocket client that enables real-time bidirectional communication
• A powerful C# code execution engine that brings AI commands to life
• Detailed logging capabilities for troubleshooting and monitoring
• Sophisticated editor state tracking and serialization for context awareness

2. MCP Server (unity-mcp-server)

This TypeScript-based server acts as the central hub, exposing Unity Editor functionality through standardized tools:

Key Tools at Your Disposal

1. get_editor_state
   • Captures a snapshot of your Unity Editor's current state
   • Provides detailed information about GameObjects, selection state, and play mode
   • Delivers comprehensive scene hierarchy and project structure data
   • Supports flexible output formats (Raw, scripts only, no scripts) to suit your needs
2. execute_editor_command
   • Runs C# code directly within your Unity Editor environment
   • Provides complete access to UnityEngine and UnityEditor APIs
   • Executes commands in real-time with thorough error handling
   • Implements command timeout protection for stability
3. get_logs
   • Retrieves and filters Unity Editor logs with precision
   • Supports advanced filtering by type, content, and timestamp
   • Offers customizable output fields for targeted information
   • Incorporates buffer management for optimal performance

Installation: Getting Started Quickly

Automated Installation via Smithery

For the fastest setup with Claude Desktop, use Smithery:

npx -y @smithery/cli install @Arodoid/unitymcp --client claude

Manual Installation Requirements

• Unity 2022.3 or newer
• Node.js 18 or later
• npm 9 or later

Setting Up the Unity Plugin

1. Copy the UnityMCPPlugin folder into your Unity project's Assets directory
2. Launch your Unity Editor
3. Access the plugin through Unity's top menu: UnityMCP > Debug Window

Setting Up the MCP Server

cd unity-mcp-server
npm install
npm run build

Usage: Bringing AI to Your Unity Workflow

Launching the Server

cd unity-mcp-server
node build/index.js

Connecting from Unity

1. Open your Unity project
2. Navigate to the UnityMCP Debug Window (Window > UnityMCP > Debug Window)
3. The plugin will automatically attempt to establish a connection
4. Monitor connection status and system logs in the debug window

Example Commands

// Reset selected object to origin
Selection.activeGameObject.transform.position = Vector3.zero;

// Toggle between play and edit modes
EditorApplication.isPlaying = !EditorApplication.isPlaying;

// Generate a new cube in the scene
GameObject.CreatePrimitive(PrimitiveType.Cube);

Development: Extending the Platform

Building the Server

cd unity-mcp-server
npm run build

Live Development with Auto-Refresh

npm run watch

Debugging Communication

npm run inspector

Technical Details: Under the Hood

Communication Protocol

• WebSocket-based communication operating on port 8080
• Fully bidirectional updates in real-time
• Standardized JSON message format
• Intelligent reconnection handling for reliability

Security Features

• Robust command execution timeout protection
• Comprehensive error handling and validation
• Efficient log buffer management
• Continuous connection state monitoring

Error Management

The system implements thorough error handling for various scenarios:

• Network connection issues
• Command execution failures
• Code compilation errors
• Runtime exceptions
• Timeout situations

Contributing: Join the Community

1. Fork the repository to your GitHub account
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes with descriptive messages
4. Push to your branch (git push origin feature/amazing-feature)
5. Submit a Pull Request for review