unity-mcp

Implements a three-tier Model Context Protocol (MCP) architecture where a Python FastMCP server translates AI assistant requests into Unity Editor commands via a C# bridge package. Uses HTTP/SSE as the default transport with stdio fallback, routing commands through a service locator pattern in the Unity Editor that dispatches cross-thread to the main editor thread. The system maintains session state and instance management to support multiple concurrent Unity projects from a single server.

Exposes 32+ pre-built tools through a decorator-based registration system (@mcp_for_unity_tool) in the Python FastMCP server, covering script management, GameObject manipulation, asset operations, scene control, material/shader editing, test execution, and prefab management. Tools are dynamically registered at server startup and support custom tool extensions through a plugin architecture. Each tool includes schema validation, parameter marshalling, and error handling with detailed feedback to the AI client.

Exposes 12+ resource providers that supply AI with contextual information about the project, including project structure, available assets, scene contents, component types, and editor configuration. Resources are registered through a decorator-based system (@mcp_for_unity_resource) and support pagination for large datasets. Provides both static metadata (project structure) and dynamic state (current scene contents).

Manages multiple concurrent Unity Editor instances through a session-aware architecture that tracks active instances, their project paths, and connection status. Implements instance discovery through port scanning and configuration files, allowing a single MCP server to coordinate commands across multiple projects. Maintains session state including active scene, play mode status, and unsaved changes for each instance.

Implements a pluggable transport layer that abstracts communication between the Python MCP server and Unity Editor instances, supporting HTTP/SSE (default), stdio, and WebSocket transports. Each transport is implemented as a separate backend with a unified interface, allowing deployment flexibility across Windows, macOS, and Linux. HTTP/SSE uses FastAPI for server implementation with automatic endpoint management.

Supports batch execution of multiple commands in a single request, with atomic semantics and error handling. Implements rollback mechanisms for operations that modify editor state, allowing partial batch failures to be handled gracefully. Includes transaction-like semantics for related operations (e.g., create GameObject, add components, configure properties).

Implements a custom serialization system that maps C# component types to JSON-serializable representations, handling both built-in Unity components and custom user scripts. Uses reflection to discover serializable fields and properties, with special handling for Unity types (Vector3, Quaternion, etc.). Supports bidirectional serialization (C# to JSON and JSON to C#) with type validation.

Exposes editor preferences and project settings through tools that read and write EditorPrefs and ProjectSettings. Supports both global editor preferences and project-specific settings, with type-safe access to configuration values. Includes validation to prevent invalid configuration states.

Implements optional telemetry collection that tracks tool usage, command execution patterns, and error rates. Includes privacy controls to allow users to opt-out of telemetry collection. Telemetry data is used to improve tool recommendations and identify common workflows.

Provides automatic configuration discovery and setup for MCP-compatible AI clients (Claude Desktop, Cursor, VS Code, Windsurf) through client-specific configurators. Detects installed clients and generates appropriate configuration files (claude_desktop_config.json, etc.) with correct server endpoints and transport settings. Supports both automatic and manual configuration workflows.

Provides AI-driven C# script generation, editing, and validation through tools that create new scripts, modify existing code, and trigger Unity's compilation pipeline. Integrates with Unity's domain reload system to handle script recompilation events, maintaining command state across reloads. Supports batch script operations and includes error reporting from the C# compiler back to the AI client for iterative code refinement.

Enables AI-driven creation, modification, and querying of GameObjects and their components through tools that instantiate prefabs, add/remove components, set properties, and traverse the scene hierarchy. Uses a component resolution system to map component types to their serializable properties, supporting both built-in Unity components and custom user scripts. Implements cross-thread dispatch to ensure all GameObject operations execute on the main editor thread.

Provides tools for discovering, importing, and exporting assets (textures, models, audio, animations) through the Unity asset database. Supports batch asset operations, asset path resolution, and metadata queries. Integrates with Unity's AssetDatabase API to ensure proper asset serialization and dependency tracking. Includes paging support for large asset collections to manage payload sizes.

Exposes tools for loading/unloading scenes, saving editor state, and controlling editor playback (play/pause/stop). Implements editor state management through a service architecture that tracks dirty scenes and unsaved changes. Supports multi-scene editing workflows and includes safeguards to prevent data loss through confirmation prompts and state validation.

Provides tools for creating and modifying materials, setting shader properties, and editing Visual Effect Graph assets. Supports property validation based on shader type, batch material operations, and VFX parameter configuration. Integrates with Unity's material serialization system to ensure changes persist correctly.

Exposes Unity Test Framework (UTF) test execution through tools that discover, run, and report on unit tests and integration tests. Supports filtering tests by name, category, or assembly, and returns detailed test results including pass/fail status, execution time, and error messages. Integrates with Unity's test runner to execute tests in the editor context.

Provides tools for discovering prefabs, instantiating them with specific parameters, and configuring their components. Supports prefab variant creation, component override management, and batch instantiation. Integrates with Unity's prefab system to ensure proper serialization and maintain prefab-instance relationships.

Exposes Unity Editor menu items as callable tools through a menu item registry that discovers and executes menu commands. Supports both built-in Unity menu items and custom user-defined menu items. Implements command dispatch through the editor's menu system, ensuring proper context and state management.