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
- Copy the
MCPForUnityfolder to your Unity project'sAssetsdirectory, or install via Unity Package Manager - Open Unity and allow the plugin to compile
- 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
- Unity plugin starts and opens a WebSocket connection to the MCP server
- Plugin registers itself with project info (name, path, hash)
- MCP server can now send commands to Unity through this connection
- 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
