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

Option	Environment Variable	Default	Description
--transport	UNITY_MCP_TRANSPORT	stdio	Transport mode: stdio or http
--http-url	UNITY_MCP_HTTP_URL	http://localhost:8080	HTTP server URL
--http-host	UNITY_MCP_HTTP_HOST	localhost	HTTP server bind host
--http-port	UNITY_MCP_HTTP_PORT	8080	HTTP server port
--default-instance	UNITY_MCP_DEFAULT_INSTANCE	-	Default Unity instance to target
--log-level	UNITY_MCP_LOG_LEVEL	info	Log level: trace, debug, info, warn, error
--pidfile	-	-	Path to write PID file
--skip-startup-connect	UNITY_MCP_SKIP_STARTUP_CONNECT	false	Skip initial Unity connection

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):

Endpoint	Description
/mcp	MCP protocol (streamable HTTP) - for MCP clients
/health	Health check - returns JSON status
/hub/plugin	WebSocket for Unity plugin connection
/plugin/sessions	List active plugin sessions
/tools/:name	Direct tool execution (legacy)
/resources/*uri	Direct resource reading (legacy)
/register-tools	Custom tool registration

Available Tools

The server exposes these MCP tools for Unity interaction:

Tool	Description
manage_scene	Scene operations (create, load, save, get_hierarchy, screenshot)
manage_gameobject	GameObject CRUD and transforms
manage_components	Add, remove, modify components
manage_asset	Asset operations (import, create, search)
manage_material	Material and shader properties
manage_prefabs	Prefab stage operations
manage_script	C# script management
manage_editor	Editor state (play/pause/stop)
run_tests	Execute Unity tests
read_console	Read Unity console logs
And more...

Available Resources

Resource URI	Description
mcpforunity://editor_state	Current editor state and settings
mcpforunity://project_info	Project metadata and paths
mcpforunity://instances	Connected Unity instances
mcpforunity://custom-tools	Project-registered custom tools

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