Unity3D MCP Server

📖 Installation Guide — quick start, manual setup, and troubleshooting

FastMCP 3.2.0+ Compliant - Comprehensive Unity 3D automation with VRM avatar pipeline and VRChat integration.

• Competitive Analysis
• Roadmap (Phases 1–5)

Tool surface (verified against src/unity3d_mcp/server.py, 2026-07-18)

This table is the single source of truth for this server's tools. Any
other tool names you see elsewhere in this README below this point, or
inferred from src/unity3d_mcp/app.py (unused dead code — not imported by
__main__.py or referenced in pyproject.toml; the real entry point is
server.py), are stale. See the housekeeping note at the bottom of this
section.

15 portmanteau tools (one tool, operation argument selects behavior —
this is the real, current tool-count-reduction pattern this server uses):

2 standalone tools (dual-mode/agentic, registered directly, not via a
manager class):

Cleaned up 2026-07-18 (previously flagged here as known duplication,
now actually removed — see TODO.md for the full record):

• The 9 flat platform-helper tools (list_vr_platforms,
  check_platform_sdk, check_cck_installed, setup_cvr_avatar,
  validate_for_chilloutvr, prepare_for_resonite,
  check_resonite_compatibility, check_cluster_kit,
  prepare_for_cluster) are gone. Use multiplatform(operation=...).
• The 11 flat api_* tools (api_execute_method, api_get_scene_objects,
  etc.) and their backing _api_* stub methods on the server class are
  gone. Use unity_api(operation=...) — the real implementation, which
  actually works for get_scene_objects/modify_object via the live
  bridge (the flat versions unconditionally returned "not implemented",
  even for those).
• unity3d_bridge_status and unity3d_editor_api are gone, folded into
  unity_bridge. The one operation unity3d_editor_api had that
  unity_bridge didn't — capture_game_view — is now a unity_bridge
  operation too. Use unity_bridge(operation="status") and
  unity_bridge(operation=...) instead.

Still real, still unregistered (not part of this pass — a bigger,
separate task if ever done): motor control (api_add_motor etc.), generic
asset export/import (export_fbx, import_asset_package, batch_import),
and dedicated VRM-Unity-rigging tools (import_vrm_to_unity,
setup_unity_avatar_rigging, etc.) are not exposed as MCP tools at
all — the underlying manager classes exist (motor_manager.py,
import_export_manager.py, vrm_avatar_manager.py) but nothing in
server.py registers them. app.py (and its .bak twin) is dead code
containing a second, never-wired implementation of some of this — don't
trust it as a source of truth for what's callable.

Copy src/unity3d_mcp/resources/MCPBridge.cs to your project's Assets/Editor/ folder.

Webapp Agent Tools page: /agent-tools (mirror blender-mcp Agent Lab UI).

Dual mode (live GUI vs headless)

unity_bridge(operation='execution_mode') reports current mode. See docs/DUAL_MODE.md.

Observability (v1.5)

• Prometheus: http://127.0.0.1:9092/metrics and /api/v1/metrics on :10831
• JSON logs: UNITY3D_MCP_LOG_FORMAT=json
• Docker: docker compose --profile monitoring up -d — docs/MONITORING.md, docs/DOCKER.md

Fleet pipeline (Blender → Unity)

.\scripts\run-fleet-pipeline.ps1 -ProjectPath "D:\Unity\MyProject" -ModelPath "D:\exports\avatar.glb" -SkipBuild

See docs/FLEET_PIPELINE.md.

blender-mcp export GLB/VRM → unity_import import_blender → unity_vision_refine review_bundle → VRChat/build
worldlabs Marble → worldlabs assemble_review → agent fixes → unity_jobs build

One-shot automation: docs/FLEET_PIPELINE.md — scripts/run-fleet-pipeline.ps1

git clone https://github.com/sandraschi/unity3d-mcp
cd unity3d-mcp
just

This opens an interactive dashboard showing all available commands. Run just bootstrap to install dependencies, then just serve or just dev to start.

Manual Setup

If you don't have just installed:

Features

Core Unity Automation

• Unity Editor Management: Launch, control, and automate Unity Editor
• Project Operations: Create, configure, and manage Unity projects
• Scene Management: Create and manipulate Unity scenes
• Build Pipeline: Automated builds for multiple platforms

Avatar & VRM Pipeline

• VRM Import: Import and configure VRM avatars for Unity
• Avatar Optimization: Optimize avatars for VRChat compatibility
• Animation System: Setup animator controllers and animation clips
• Performance Profiling: Analyze and optimize avatar performance

Asset Management

• Package Import: Import Unity asset packages
• Texture Optimization: Platform-specific texture optimization
• Material Management: Create and convert materials for VRChat
• Asset Organization: Automated asset organization and versioning

VRChat Integration

• SDK Automation: Automate VRChat SDK operations
• Avatar Upload: Upload avatars to VRChat platform
• OSC Communication: Real-time OSC parameter control
• Performance Validation: VRChat-specific performance validation
• Authentication: VRChat API auth with 2FA/TOTP support

Multi-Platform Social VR

• ChilloutVR: CCK detection, CVRAvatar setup, validation
• Resonite: Direct VRM/GLB import (no Unity needed!)
• Cluster: Japanese social VR with VRM support

Advanced Unity Editor API operations

Covered by the unity_api portmanteau tool (see the tool table above).
Every operation is real and bridge-dependent: it calls the MCPBridge.cs
Editor bridge (HTTP, localhost:10835) and requires Unity to be open with
that script installed and running. Two known, honestly-documented
limitations in the current bridge implementation:

• execute_method only supports public, static, parameterless Unity
  methods (the same constraint Unity's own -executeMethod CLI flag has).
  Passing parameters is accepted but explicitly reported back as
  ignored, not silently dropped or type-coerced.
• Path movement (move_along_path, follow_path_2d, follow_path_3d)
  approximates all path_type curve variants (bezier, spline,
  catmull_rom) as straight multi-segment linear interpolation — real
  curve math is not implemented.

This was verified by manual C# code review only (no dotnet/mono/csc
compiler was available in the environment this was built in), so treat it
as unverified against a live Unity Editor until you've smoke-tested it
yourself.

Not currently exposed as MCP tools at all (real code exists in
motor_manager.py, import_export_manager.py, and
vrm_avatar_manager.py, but nothing in server.py registers it):
motor control (attach/start/stop/configure motors on objects), generic
asset export/import (.unitypackage, standalone FBX/prefab export,
texture-specific import), and dedicated VRM-Unity-rigging tools separate
from unity_avatar's import_vrm/setup_animator. If you need any of
these, they'd need a portmanteau wrapper written and registered in
server.py first — that's real, scoped future work, not a documentation
fix. Tracked in TODO.md.

Agentic Sampling (SEP-1577)

FastMCP 3.2.0+ introduces Agentic Sampling, allowing the server to borrow the client's LLM to orchestrate complex workflows autonomously.

• unity3d_agentic_workflow: Execute a mission-based objective (e.g., "Setup a new VRChat project and import my avatar").

Contextual Discovery (Skills & Prompts)

This server provides expert instructions and pre-defined workflows via the SOTA Skill system.

Skills

Available via resource://unity3d/skills/:

• unity-editor-automation: Expert guide for editor control.
• vrc-avatar-pipeline: Guide for VRM to VRChat optimization.

Prompts

Registered SOTA prompts:

• unity_setup_workflow: Guide for project initialization.
• vrc_avatar_workflow: Instructions for the VRM optimization lifecycle.

Dual-Mode Operations

This server uniquely supports two distinct operational modes for maximum flexibility across development and CI/CD environments.

1. Hands-In (Active Session)

Real-time control of a running Unity Editor. Requires the MCPBridge.cs plugin.

• Tools: unity_bridge (operations: status, execution_mode, ping, get_hierarchy, create_object, delete_object, transform_object, capture_game_view)
• Use Case: Scene layout, live debugging, lighting setup, and real-time hierarchy manipulation.
• Port: 10835 (HTTP)
• Guide: Real-Time Editor Automation

2. Hands-Off (Disk Operations)

Direct manipulation of Unity assets on disk. Powered by UnityPy.

• Tools: unity3d_disk_api
• Use Case: CI/CD pipelines, batch asset auditing, texture extraction, and quick prefab fixes without launching Unity.
• Support: Serialized files (.unity, .prefab, .asset) + Unity YAML source files.
• Guide: Direct Disk Manipulation

Technical Documentation

A comprehensive technical suite is available in the Documentation Portal.

Core Concepts

• Architecture Deep Dive: Hands-In vs Hands-Off analysis.
• Complete API Reference: Details for all 50+ tools.

Specialized Pipeliens

• VRM-to-VRChat Guide: High-fidelity avatar optimization.
• Scene Automation Guide: Real-time Editor control.

Technical Standards

• FastMCP 3.2.0+: Latest MCP protocol implementation with ASGI/Uvicorn and SEP-1577 sampling.
• Agentic Workflows: Integrated autonomous orchestration using dual-mode intelligence.
• Modular Skills: Discoverable expert instructions for bridge installation and disk ops.
• Structured Logging: JSON-formatted logs via structlog.
• Security: CVE-2025-62801 and CVE-2025-62800 fixes applied.

World Labs Integration

• Marble Import: Import AI-generated 3D worlds from World Labs Marble
• Chisel Support: Works with Chisel-edited environments
• Gaussian Splatting: Install renderer for .ply/.splat files
• VRChat Optimization: Recommendations for VRChat world uploads
• Format Support: OBJ, FBX, GLB, GLTF meshes + Gaussian Splats

UniVRM Management

• Package Detection: Check if UniVRM is installed
• Auto-Install: Install UniVRM 0.x or 1.0 via Package Manager
• Project Templates: Create projects with UniVRM pre-configured

Advanced Features

• Dual Interface: Both stdio and HTTP (ASGI/Uvicorn) interfaces.
• FastMCP 3.2.0: Modern MCP server architecture with sampling support.
• Comprehensive Logging: Structured logging with performance metrics.
• Platform Management: Multi-platform build and optimization.
• Path Resolution: Intelligent Unity installation detection.

Installation

Prerequisites

• uv installed (RECOMMENDED)
• Python 3.12+

Quick Start

Run immediately via uvx:

uvx unity3d-mcp

Claude Desktop Integration

Add to your claude_desktop_config.json:

"mcpServers": {
  "unity3d-mcp": {
    "command": "uv",
    "args": ["--directory", "D:/Dev/repos/unity3d-mcp", "run", "unity3d-mcp"]
  }
}

From PyPI (Recommended)

pip install unity3d-mcp

Packaging & Distribution

This repository is SOTA 2026 compliant and uses the officially validated @anthropic-ai/mcpb workflow for distribution.

Pack Extension

To generate a .mcpb distribution bundle with complete source code and automated build exclusions:

# SOTA 2026 standard pack command
mcpb pack . dist/unity3d-mcp.mcpb

From GitHub Releases

# Direct wheel download
pip install https://github.com/sandraschi/unity3d-mcp/releases/download/v1.2.0/unity3d_mcp-1.2.0-py3-none-any.whl

# Or from git
pip install git+https://github.com/sandraschi/unity3d-mcp.git

Configuration

Create a configuration file or use environment variables:

{
  "unity_editor_path": "C:/Program Files/Unity/Hub/Editor/2022.3.0f1/Editor/Unity.exe",
  "project_path": "D:/Unity Projects",
  "auto_detect_unity": true,
  "enable_http": true,
  "http_port": 8080,
  "log_level": "INFO"
}

Usage

Command Line

# Start in stdio mode
unity3d-mcp --mode stdio

# Start HTTP server
unity3d-mcp --mode http --port 8080

# Dual mode (stdio + HTTP)
unity3d-mcp --mode dual

MCP Tools

See Tool surface
near the top of this README for the complete, verified-against-source tool
list with real operation names. (An earlier revision of this README had a
second, incompatible tool list here using names like launch_unity_editor,
import_vrm_avatar, upload_vrchat_avatar — those aren't callable tools;
the real operations are unity_core(operation="launch_editor"),
unity_avatar(operation="import_vrm"),
vrchat(operation="upload_avatar"), etc. Removed 2026-07-18 to stop the
two lists drifting further apart — one source of truth from now on.)

Architecture

unity3d_mcp/
 core/           # Unity Editor automation, project management, UniVRM
 avatar/         # VRM avatar management
 assets/         # Asset import and optimization
 build/          # Build pipeline management
 vrchat/         # VRChat SDK integration + authentication
 worldlabs/      # World Labs Marble/Chisel integration
 utils/          # Shared utilities

Testing

# Run all tests
.\scripts\run-tests.ps1

# Run with coverage
.\scripts\run-tests.ps1 -Coverage

# Run E2E tests (requires Unity)
.\scripts\run-tests.ps1 -E2E

# Run specific test pattern
.\scripts\run-tests.ps1 -Pattern "test_worldlabs"

Requirements

• Python 3.8+
• Unity Editor (2019.4 LTS or newer)
• VRChat SDK (for VRChat features)
• Windows 10/11 (primary support)

Performance

Optimized for:

• VRChat avatar requirements
• Mobile VR platforms
• Multi-platform deployment
• Real-time OSC communication

🛡️ Industrial Quality Stack

This project adheres to SOTA 14.1 industrial standards for high-fidelity agentic orchestration:

• Python (Core): Ruff for linting and formatting. Zero-tolerance for print statements in core handlers (T201).
• Webapp (UI): Biome for sub-millisecond linting. Strict noConsoleLog enforcement.
• Protocol Compliance: Hardened stdout/stderr isolation to ensure crash-resistant JSON-RPC communication.
• Automation: Justfile recipes for all fleet operations (just lint, just fix, just dev).
• Security: Automated audits via bandit and safety.

License

MIT License - see LICENSE for details.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

Support

• Documentation: GitHub Wiki
• Issues: GitHub Issues
• Discussions: GitHub Discussions

Webapp Dashboard

This MCP server includes a premium SOTA web interface for monitoring and control.

Port Allocation (Standardized)

• Frontend: 10830 (Vite / React)
• Backend (API): 10831 (FastAPI / FastMCP)

To start the webapp:

1. Navigate to the web_sota directory.
2. Run start.bat (Windows) or ./start.ps1 (PowerShell).
3. The dashboard will automatically open at http://localhost:10830.