---

name: unity-mcp description: Expert guidance for Unity development using Unity MCP server. Use when making C# script changes, working with GameObjects, components, scenes, or Unity editor operations. Provides safe workflows for compilation monitoring, asset management, and error handling.

Unity MCP Skill

Expert guidance for interacting with Unity Editor via the Unity MCP server.

When to Use This Skill

This skill is automatically invoked when working with Unity projects. It provides best practices for:

• Making script changes and monitoring compilation
• Working with GameObjects, components, and scenes
• Querying Unity state efficiently
• Avoiding common pitfalls with Unity MCP

Before Making Changes

1. Check Editor State

Always verify Unity isn't compiling before making changes:

CopyRead resource: mcpforunity://editor/state
Check: isCompiling field
If true: Wait before proceeding

2. Check for Existing Errors

IMPORTANT: The console may contain stale data. Always refresh before reading:

Copyrefresh_unity(scope="scripts", compile="request", wait_for_ready=true)
read_console(action="get", types=["error"])

This ensures you see current compilation errors, not cached/stale results.

3. Verify Scene Context

Check which scene is active:

Copymanage_scene(action="get_active")

After Script Changes

Refresh and Wait for Compilation

After editing scripts, trigger a refresh with wait_for_ready=true:

Copyrefresh_unity(scope="scripts", compile="request", wait_for_ready=true)

This call will:

• Trigger asset refresh
• Request compilation
• Wait until Unity is ready before returning

Check Console for Errors

After refresh completes, check for compilation errors:

Copyread_console(action="get", types=["error", "warning"])

Why refresh before read_console? The Unity console is not automatically updated when files change on disk. Without calling refresh_unity first, read_console may return stale/cached results.

Workflow

✅ Correct approach:

CopyEdit script...
refresh_unity(scope="scripts", compile="request", wait_for_ready=true)
read_console(action="get", types=["error", "warning"])

The wait_for_ready=true parameter ensures Unity has finished compiling before the call returns.

Resource vs Tool Usage

Golden Rule: Read with resources, modify with tools

Resources (Read-Only)

• mcpforunity://editor/state - Check compilation status, play mode, etc.
• mcpforunity://project/info - Project name, paths, Unity version
• mcpforunity://custom-tools - Project-specific custom tools (check this FIRST!)
• mcpforunity://scene/hierarchy - Scene hierarchy
• mcpforunity://instances - Active Unity instances

Tools (Modifications)

• manage_script - Create, read, delete scripts
• manage_gameobject - GameObject CRUD operations
• manage_components - Add/remove/modify components
• manage_scene - Scene operations
• manage_asset - Asset operations
• read_console - Check Unity console messages

Performance Best Practices

Use Paging for Large Queries

Scene Hierarchy:

Copymanage_scene(
    action="get_hierarchy",
    page_size=50,
    cursor=0
)
// Follow next_cursor until null

GameObject Components:

Copymanage_gameobject(
    action="get_components",
    target="12345",
    search_method="by_id",
    include_properties=false,  // Start with metadata only
    page_size=10
)

Asset Searches:

Copymanage_asset(
    action="search",
    path="Assets",
    page_size=25,
    generate_preview=false  // IMPORTANT: Avoid large base64 payloads
)

Recommended Page Sizes

• Components with properties: 3-10 items
• Components without properties: 10-25 items
• Scene hierarchy: 50 items
• Asset searches: 25-50 items

Always Disable Previews

Set generate_preview=false in asset searches unless you explicitly need thumbnails (they add large base64 blobs to responses).

GameObject Targeting

Prefer instance ID (most reliable):

Copytarget="12345"
search_method="by_id"

Hierarchy path (good for known structures):

Copytarget="Player/Hand/Weapon"
search_method="by_path"

By name (finds first match):

Copytarget="Player"
search_method="by_name"

By tag:

Copytarget="Enemy"
search_method="by_tag"

By component type:

Copytarget="Rigidbody"
search_method="by_component"

Component Workflow

Safe Component Modification Pattern

1. Check if component exists:

Copymanage_gameobject(
    action="get_components",
    target="12345",
    search_method="by_id",
    include_properties=false
)

1. Add component if needed:

Copymanage_components(
    action="add",
    target="12345",
    search_method="by_id",
    component_type="Rigidbody"
)

1. Set component properties:

Copymanage_components(
    action="set_property",
    target="12345",
    search_method="by_id",
    component_type="Rigidbody",
    property="mass",
    value=10.0
)

Scene Management

Creating New Scenes

Always include essential components:

Copy1. Create scene
2. Add Main Camera
3. Add Directional Light
4. Save scene

Before Major Operations

Save the scene:

Copymanage_scene(action="save")

Visual Verification

Take screenshots to verify results:

Copymanage_scene(
    action="screenshot",
    screenshot_file_name="verification.png"
)

Script Management Workflow

1. Create Script

Copycreate_script(
    path="Assets/Scripts/MyScript.cs",
    contents="using UnityEngine;\n\npublic class MyScript : MonoBehaviour\n{\n    // Implementation\n}"
)

2. Trigger Refresh and Wait for Compilation

Copyrefresh_unity(scope="scripts", compile="request", wait_for_ready=true)

3. Check for Compilation Errors

Copyread_console(action="get", types=["error"])
If errors exist: Fix them and repeat from step 1

4. Proceed with Next Step

Only after compilation succeeds and no errors exist.

Custom Tools

ALWAYS check custom tools first:

CopyRead resource: mcpforunity://custom-tools

Projects may register custom tools for specific workflows. These take precedence over generic MCP tools.

Common Patterns

Finding GameObjects by Criteria

Copyfind_gameobjects(
    search_method="by_name",
    search_term="Player",
    include_inactive=false,
    page_size=10
)

Batch Operations

Use batch_execute for multiple operations (10-100x faster):

Copybatch_execute(
    commands=[
        {"tool": "manage_gameobject", "params": {...}},
        {"tool": "manage_components", "params": {...}},
        {"tool": "manage_components", "params": {...}}
    ]
)

Safe Property Access

Always verify properties exist before setting:

Copy1. Get component with include_properties=true
2. Check if property exists in properties dictionary
3. Set property value

Error Handling

Compilation Errors

Copy1. Call refresh_unity(scope="scripts", compile="request", wait_for_ready=true)
2. Read console: read_console(action="get", types=["error"])
3. Identify the error message and file
4. Fix the error in the script
5. Repeat steps 1-2 to verify the fix

IMPORTANT: Always refresh before reading console! Without refresh, the console may show outdated errors.

Missing Components

Copy1. Check if component exists on GameObject
2. If missing, add component first
3. Then set properties

Asset Not Found

Copy1. Use manage_asset(action="search") to find asset
2. Verify path is correct
3. Check if asset exists in project

Multiple Unity Instances

If multiple Unity editors are running:

1. List instances:

CopyRead resource: mcpforunity://instances

1. Set active instance:

Copyset_active_instance(instance="ProjectName@hash")

Best Practices Summary

DO:

• Check mcpforunity://custom-tools first
• Read mcpforunity://editor/state before making changes
• Use wait_for_ready=true when refreshing
• Use paging for large queries
• Disable previews in asset searches
• Target by instance ID when possible
• Always call refresh_unity BEFORE read_console
• Verify no errors before proceeding
• Use batch_execute for multiple operations

DON'T:

• Make changes while Unity is compiling
• Call read_console without refresh_unity first (console may be stale!)
• Use large page sizes (causes token bloat)
• Enable previews unless needed
• Proceed without checking for errors
• Assume compilation succeeded
• Target by name when ID is available
• Skip checking custom tools

Example: Complete Script Modification Workflow

Copy1. Check existing state (optional but recommended)
   → read_console(action="get", types=["error"])
   → Verify no pre-existing errors

2. Read script content
   → Read("Assets/Scripts/MyScript.cs")

3. Modify script
   → Edit(...) or script_apply_edits(...)

4. Refresh and wait for compilation
   → refresh_unity(scope="scripts", compile="request", wait_for_ready=true)

5. Check console for results
   → read_console(action="get", types=["error", "warning"])
   → If errors exist, fix them and repeat from step 2

6. Proceed to next task
   → Only after confirming no errors

This workflow ensures safe, reliable Unity development via MCP.