Unity MCP Server (Rust)

MCP (Model Context Protocol) server for Unity Editor integration, written in Rust.

This server enables AI assistants (like Claude) to interact with the Unity Editor through the standardized MCP protocol, allowing operations like scene management, GameObject manipulation, script editing, and more.

Building

Prerequisites

• Rust 1.70+ (install via rustup)
• On Windows: Visual Studio Build Tools with C++ workload

Build Commands

# Development build
cargo build

# Release build (optimized)
cargo build --release

# Run directly
cargo run -- --help

The binary will be at target/debug/unity-mcp (or target/release/unity-mcp for release builds).

Usage

# Default: STDIO transport (for MCP client integration)
unity-mcp

# HTTP transport with WebSocket support
unity-mcp --transport http

# Custom HTTP port
unity-mcp --transport http --http-port 8090

# Target a specific Unity instance
unity-mcp --default-instance "MyProject@abc123"

# Enable debug logging
unity-mcp --log-level debug

Command Line Options

Unity Plugin Setup

This server works with the MCP for Unity plugin, which must be installed in your Unity project.

Installing the Plugin

1. Copy the MCPForUnity folder to your Unity project's Assets directory, or install via Unity Package Manager
2. Open Unity and allow the plugin to compile
3. The plugin will automatically start listening for MCP server connections

Plugin Configuration

The Unity plugin connects to the MCP server via WebSocket. By default, it expects:

• WebSocket URL: ws://localhost:8080/hub/plugin
• Port Range for Discovery: 6400-6500 (TCP)

If you're running the server on a different port, update the plugin settings in Unity:

• Go to Window > MCP for Unity > Settings
• Update the server URL to match your configuration

Connection Flow

1. Unity plugin starts and opens a WebSocket connection to the MCP server
2. Plugin registers itself with project info (name, path, hash)
3. MCP server can now send commands to Unity through this connection
4. Commands are executed in Unity and responses are sent back

Architecture

┌─────────────────┐       WebSocket        ┌─────────────────┐
│   MCP Client    │◄─────────────────────►│   Unity MCP     │
│  (Claude, etc)  │                        │     Server      │
└─────────────────┘                        └────────┬────────┘
                                                    │
                                           WebSocket│/TCP
                                                    │
                                           ┌────────▼────────┐
                                           │  Unity Editor   │
                                           │    (Plugin)     │
                                           └─────────────────┘

Transport Modes

• STDIO: Standard input/output transport for MCP protocol. Used when the server is spawned by an MCP client.
• HTTP: HTTP server with WebSocket support. Useful for development and when running the server standalone.

Key Components

• Plugin Hub (/hub/plugin): WebSocket endpoint for Unity plugin connections
• Tool Registry: Registers and executes MCP tools (manage_scene, manage_gameobject, etc.)
• Resource Registry: Provides MCP resources (editor_state, project_info, etc.)
• Port Discovery: Scans ports 6400-6500 to find Unity instances (legacy TCP mode)

HTTP Endpoints

When running with HTTP transport (--transport http):

Available Tools

The server exposes these MCP tools for Unity interaction:

Available Resources

Logs

Logs are written to:

• stderr: Console output
• File: ~/.unity_mcp/logs/unity_mcp_server.log (daily rotation)

MCP Client Configuration

Claude Desktop

Add to your Claude Desktop config (~/.config/claude/claude_desktop_config.json on Linux/Mac, %APPDATA%\Claude\claude_desktop_config.json on Windows):

{
  "mcpServers": {
    "unity": {
      "command": "path/to/unity-mcp",
      "args": []
    }
  }
}

With HTTP Transport

If running the server separately with HTTP transport:

{
  "mcpServers": {
    "unity": {
      "url": "http://localhost:8080"
    }
  }
}

Development

Project Structure

src/
├── main.rs           # Entry point and CLI
├── lib.rs            # Library root
├── config.rs         # Configuration management
├── error.rs          # Error types
├── server.rs         # HTTP server and routing
├── middleware/       # Request context
├── models/           # Data models and types
├── services/
│   ├── tools/        # MCP tool implementations
│   └── resources/    # MCP resource implementations
├── transport/
│   ├── plugin_hub.rs     # WebSocket hub for Unity
│   ├── plugin_registry.rs # Plugin session tracking
│   ├── unity_transport.rs # Transport abstraction
│   └── legacy/           # TCP framing protocol
├── telemetry/        # Usage telemetry (optional)
└── utils/            # Utility functions

Running Tests

cargo test

Code Formatting

cargo fmt

Linting

cargo clippy

Differences from Python Implementation

This Rust implementation is a port of the original Python MCP for Unity server. Key differences:

• Performance: Significantly lower memory usage and faster startup
• Single Binary: No Python interpreter or dependencies required
• Type Safety: Compile-time guarantees for protocol handling
• Same Protocol: Fully compatible with the Unity C# plugin

The Unity plugin does not need to be modified to work with this Rust server.

License

MIT