DOCSEARCHbyAlgolia
Submit Docs

MCP for Unity

repository·beta·Indexed 11 days ago

https://github.com/coplaydev/unity-mcp

A bridge connecting AI assistants (such as Claude Code, Cursor, and VS Code) to the Unity Editor via the Model Context Protocol (MCP). Version 10.1.3-beta.4 allows developers to control the editor, manage assets, edit scripts, and automate workflows using natural language through 47 focused tool entrypoints. Supports Unity 2021.3 LTS through 6.x and provides options for stdio or HTTP transport, including a remote-hosted mode with API key authentication.

Tokens
151.5K
Snippets
422
Records
649
Agent score
90%

What's inside MCP for Unity

  1. Overview of MCP for Unity capabilities

    beta

    MCP for Unity provides 47 focused MCP tool entrypoints that allow LLMs to interact directly with the Unity Editor. This enables AI assistants to perform tasks such as:

    • Scene Management: Create scenes and GameObjects.
    • Scripting: Edit C# scripts and perform Roslyn script validation.
    • Asset Management: Manage project assets.
    • Workflow Automation: Run tests, profile the application, and trigger builds.

    This project is free and open-source under the MIT license.

  2. Overview of the manage_physics MCP tool

    beta
    The manage_physics MCP tool provides AI assistants with full control over Unity's 3D and 2D physics systems. It includes 21 distinct actions organized into 9 functional categories, allowing for the manipulation of settings, collision matrices, materials, joints, queries, forces, rigidbodies, validation, and simulation. The tool is designed with auto-dimension detection, meaning it automatically determines whether to use 2D or 3D physics based on the presence of Rigidbody or Rigidbody2D components, though users can provide an optional dimension override.

  3. Overview of MCP for Unity Tool Domains

    beta

    The MCP for Unity server exposes a wide range of tools categorized into functional domains. These tools allow an AI agent or client to interact directly with the Unity Editor, manage assets, generate content, and control runtime systems.

    Available Tool Domains:

    • animation: Animator control and AnimationClip creation.
    • asset_gen: AI-driven generation of audio, images, and 3D models (requires external API keys).
    • core: Essential tools for scene management, scripting, asset manipulation, and editor control (enabled by default).
    • docs: Access to official Unity documentation and live C# API reflection.
    • probuilder: 3D modeling via the ProBuilder package.
    • profiling: Control over the Unity Profiler and Frame Debugger.
    • scripting_ext: Advanced scripting via arbitrary C# execution and ScriptableObject management.
    • testing: Asynchronous Unity test execution and job polling.
    • ui: Management of UI Toolkit elements (UXML, USS, UIDocument).
    • vfx: Management of shaders, procedural textures, and VFX components (ParticleSystem, VisualEffect, etc.).

  4. Overview of MCP for Unity

    beta

    MCP for Unity is a bridge between AI assistants (such as Claude, Codex, VS Code, and local LLMs) and the Unity Editor using the Model Context Protocol (MCP). It enables LLMs to interact directly with your Unity project by providing tools to manage assets, control scenes, edit scripts, run tests, and automate workflows.

    Key Capabilities

    • Unity Editor Tools: Over 40 tools are exposed via MCP, including manage_scene, manage_script, manage_gameobject, manage_material, manage_physics, and run_tests.
    • State Introspection: Over 25 read-only resources allow the AI to inspect the project state, such as editor_state, gameobject_components, project_info, and unity_instances.
    • Multi-instance Support: You can control multiple Unity Editor instances from a single MCP session using the set_active_instance tool.
    • Transport Options: Supports both HTTP (the default, optimized for multi-agent workflows) and stdio (legacy, for single-agent workflows).

  5. Use `asset_gen` tools for AI asset generation

    beta

    The asset_gen tool group provides Model Context Protocol (MCP) capabilities for generating and importing AI-driven assets directly into a Unity project. This includes 3D model generation/import, 2D image generation, and audio generation. Note that most generation tools require a 'bring-your-own-key' approach for the underlying AI providers.

    Available tools in this group:

    • generate_audio: Generates sound effects or background music using fal.ai models and imports them as AudioClips.
    • generate_image: Generates 2D images via providers like fal.ai or OpenRouter and imports them as textures or sprites.
    • generate_model: Generates 3D models using providers like Tripo or Meshy and imports them into the project.
    • import_model: Imports 3D models specifically from the Sketchfab marketplace.
    • import_model_file: Imports existing local 3D model files (e.g., FBX, OBJ, glTF) from disk into the Unity project.

  7. Use VFX tools for shader, texture, and component management

    beta
    The vfx tool group provides MCP (Model Context Protocol) capabilities for managing visual effects within Unity. This group includes tools for manipulating shader scripts, generating procedural textures, and managing various Unity VFX components like Particle Systems and Visual Effect Graph components.

  8. Manage cameras with `manage_camera`

    beta

    The manage_camera tool (module services.tools.manage_camera) allows you to manage Unity Cameras and Cinemachine components. It supports basic Unity Camera functionality and unlocks advanced features like presets, pipelines, and blending when Cinemachine is installed.

    Key Capabilities:

    • Setup: Check Cinemachine availability (ping), ensure a CinemachineBrain exists (ensure_brain), and check brain status (get_brain_status).
    • Creation: Create cameras with presets like third_person, freelook, follow, dolly, static, top_down, or side_scroller (create_camera).
    • Configuration: Set targets (set_target), priority (set_priority), lens settings (set_lens), Body components (set_body), Aim components (set_aim), and Noise (set_noise).
    • Extensions: Add or remove Cinemachine extensions like CinemachineConfiner2D or CinemachineImpulseListener (add_extension, remove_extension).
    • Control: Configure blending (set_blend), force a specific camera (force_camera), or list all cameras (list_cameras).
    • Capture: Take screenshots of the Game View or Scene View, including batch modes and inline base64 images (screenshot).

  9. Use animation tools for Animator control and AnimationClip creation

    beta

    The animation tool group in MCP for Unity provides capabilities for managing Unity animations. This includes controlling the Animator component and creating new AnimationClip assets.

    To perform specific animation tasks, use the following tool:

    • manage_animation: Use this tool to handle Animator state control and the generation of AnimationClips.

  11. Identify Unity Editors using Instance Identifiers

    beta

    An instance identifier follows the format ProjectName@Hash.

    • Project Name: The name of the project folder.
    • Hash: A SHA1 hash of the absolute path to the Assets folder (Application.dataPath), hex-encoded and truncated.

    Warning on Portability: The hash is path-dependent. Moving the project folder or checking it out on a different machine will change the hash and invalidate any existing pins or references to the old identifier.

    Transport-Specific Hash Lengths:

    • stdio: Truncates to 8 characters (e.g., MyGame@a1b2c3d4).
    • HTTP: Truncates to 16 characters (e.g., MyGame@a1b2c3d4e5f6a7b8).

    Note: Do not attempt to compare or cache identifiers across different transports, as they will not match due to different truncation lengths.

  12. Understand tool dependencies in Unity MCP

    beta

    Several Unity MCP tools have specific package dependencies. When planning automation or setup, note the following requirements:

    • manage_input requires com.unity.inputsystem.
    • manage_netcode requires com.unity.netcode.gameobjects.
    • manage_addressables requires com.unity.addressables.
    • manage_xr requires 3-6 specific packages.
    • manage_navigation optionally requires com.unity.ai.navigation.
    • manage_timeline is usually pre-installed.

    Tools such as manage_packages, manage_physics, manage_terrain, manage_build, and manage_optimization have no package dependencies.

    manage_packages (Tier 1)
    |
    +---> manage_input (requires com.unity.inputsystem)
    +---> manage_netcode (requires com.unity.netcode.gameobjects)
    +---> manage_addressables (requires com.unity.addressables)
    +---> manage_xr (requires 3-6 packages)
    +---> manage_timeline (usually pre-installed)
    +---> manage_navigation (optional com.unity.ai.navigation)

No package dependency:
manage_physics, manage_terrain, manage_build,
manage_optimization, QoL extensions, manage_tilemap (core)