# UnityMCP: Seamless Integration Between Unity and AI Assistants


> Discover UnityMCP, a powerful Unity Editor plugin implementing the Model Context Protocol (MCP) that enables seamless integration between Unity and AI assistants with real-time monitoring and remote command execution capabilities.

**Published:** 2025-03-19T22:20:00+00:00

**Keywords:** unity mcp,unity editor plugin

# 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](https://smithery.ai/server/@Arodoid/unitymcp):

```bash
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

```bash
cd unity-mcp-server
npm install
npm run build
```

## Usage: Bringing AI to Your Unity Workflow

### Launching the Server

```bash
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

```csharp
// 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

```bash
cd unity-mcp-server
npm run build
```

### Live Development with Auto-Refresh

```bash
npm run watch
```

### Debugging Communication

```bash
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

**Source:** https://model-context-protocol.com/blog/unity-model-context-protocol-connecting-unity