UnityMCP Rs
Interact with Unity through a MCP server, create game objects and materials, browse in-project assets
Ask AI about UnityMCP Rs
Powered by Claude ยท Grounded in docs
I know everything about UnityMCP Rs. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
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
- 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):
| 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
