Unity-MCP Operator Guide

This skill helps you effectively use the Unity Editor with MCP tools and resources.

Template Notice

Examples in references/workflows.md and references/tools-reference.md are reusable templates. They may be inaccurate across Unity versions, package setups (UGUI/TMP/Input System), and project-specific conventions. Please check console, compilation errors, or use screenshot after implementation.

Before applying a template:

• Validate targets/components first via resources and find_gameobjects .

• Treat names, enum values, and property payloads as placeholders to adapt.

Quick Start: Resource-First Workflow

Always read relevant resources before using tools. This prevents errors and provides the necessary context.

1. Check editor state → mcpforunity://editor/state
2. Understand the scene → mcpforunity://scene/gameobject-api
3. Find what you need → find_gameobjects or resources
4. Take action → tools (manage_gameobject, create_script, script_apply_edits, apply_text_edits, validate_script, delete_script, get_sha, etc.)
5. Verify results → read_console, manage_camera(action="screenshot"), resources

Critical Best Practices

1. After Writing/Editing Scripts: Wait for Compilation and Check Console

After create_script or script_apply_edits:

Both tools already trigger AssetDatabase.ImportAsset + RequestScriptCompilation automatically.

No need to call refresh_unity — just wait for compilation to finish, then check console.

1. Poll editor state until compilation completes

Read mcpforunity://editor/state → wait until is_compiling == false

2. Check for compilation errors

read_console(types=["error"], count=10, include_stacktrace=True)

Why: Unity must compile scripts before they're usable. create_script and script_apply_edits already trigger import and compilation automatically — calling refresh_unity afterward is redundant.

2. Use batch_execute for Multiple Operations

10-100x faster than sequential calls

batch_execute( commands=[ {"tool": "manage_gameobject", "params": {"action": "create", "name": "Cube1", "primitive_type": "Cube"}}, {"tool": "manage_gameobject", "params": {"action": "create", "name": "Cube2", "primitive_type": "Cube"}}, {"tool": "manage_gameobject", "params": {"action": "create", "name": "Cube3", "primitive_type": "Cube"}} ], parallel=True # Hint only: Unity may still execute sequentially )

Max 25 commands per batch by default (configurable in Unity MCP Tools window, max 100). Use fail_fast=True for dependent operations.

Tip: Also use batch_execute for discovery — batch multiple find_gameobjects calls instead of calling them one at a time:

batch_execute(commands=[ {"tool": "find_gameobjects", "params": {"search_term": "Camera", "search_method": "by_component"}}, {"tool": "find_gameobjects", "params": {"search_term": "Player", "search_method": "by_tag"}}, {"tool": "find_gameobjects", "params": {"search_term": "GameManager", "search_method": "by_name"}} ])

3. Use Screenshots to Verify Visual Results

Basic screenshot (saves to Assets/, returns file path only)

manage_camera(action="screenshot")

Inline screenshot (returns base64 PNG directly to the AI)

manage_camera(action="screenshot", include_image=True)

Use a specific camera and cap resolution for smaller payloads

manage_camera(action="screenshot", camera="MainCamera", include_image=True, max_resolution=512)

Batch surround: captures front/back/left/right/top/bird_eye around the scene

manage_camera(action="screenshot", batch="surround", max_resolution=256)

Batch surround centered on a specific object

manage_camera(action="screenshot", batch="surround", view_target="Player", max_resolution=256)

Positioned screenshot: place a temp camera and capture in one call

manage_camera(action="screenshot", view_target="Player", view_position=[0, 10, -10], max_resolution=512)

Scene View screenshot: capture what the developer sees in the editor

manage_camera(action="screenshot", capture_source="scene_view", include_image=True)

Scene View framed on a specific object

manage_camera(action="screenshot", capture_source="scene_view", view_target="Canvas", include_image=True)

Best practices for AI scene understanding:

• Use include_image=True when you need to see the scene, not just save a file.

• Use batch="surround" for a comprehensive overview (6 angles, one command).

• Use view_target /view_position to capture from a specific viewpoint without needing a scene camera.

• Use capture_source="scene_view" to see the editor viewport (gizmos, wireframes, grid).

• Keep max_resolution at 256–512 to balance quality vs. token cost.

Agentic camera loop: point, shoot, analyze

manage_gameobject(action="look_at", target="MainCamera", look_at_target="Player") manage_camera(action="screenshot", camera="MainCamera", include_image=True, max_resolution=512)

→ Analyze image, decide next action

Multi-view screenshot (6-angle contact sheet)

manage_camera(action="screenshot_multiview", max_resolution=480)

Scene View for editor-level inspection (shows gizmos, debug overlays, etc.)

manage_camera(action="screenshot", capture_source="scene_view", view_target="Player", include_image=True)

4. Check Console After Major Changes

read_console( action="get", types=["error", "warning"], # Focus on problems count=10, format="detailed" )

5. Always Check editor_state Before Complex Operations

Read mcpforunity://editor/state to check:

- is_compiling: Wait if true

- is_domain_reload_pending: Wait if true

- ready_for_tools: Only proceed if true

- blocking_reasons: Why tools might fail

Parameter Type Conventions

These are common patterns, not strict guarantees. manage_components.set_property payload shapes can vary by component/property; if a template fails, inspect the component resource payload and adjust.

Vectors (position, rotation, scale, color)

Both forms accepted:

position=[1.0, 2.0, 3.0] # List position="[1.0, 2.0, 3.0]" # JSON string

Booleans

Both forms accepted:

include_inactive=True # Boolean include_inactive="true" # String

Colors

Auto-detected format:

color=[255, 0, 0, 255] # 0-255 range color=[1.0, 0.0, 0.0, 1.0] # 0.0-1.0 normalized (auto-converted)

Paths

Assets-relative (default):

path="Assets/Scripts/MyScript.cs"

URI forms:

uri="mcpforunity://path/Assets/Scripts/MyScript.cs" uri="file:///full/path/to/file.cs"

Core Tool Categories

Category Key Tools Use For

Scene manage_scene , find_gameobjects

Scene operations, finding objects

Objects manage_gameobject , manage_components

Creating/modifying GameObjects

Scripts create_script , script_apply_edits , validate_script

C# code management (auto-refreshes on create/edit)

Assets manage_asset , manage_prefabs

Asset operations. Prefab instantiation is done via manage_gameobject(action="create", prefab_path="...") , not manage_prefabs .

Editor manage_editor , execute_menu_item , read_console

Editor control, package deployment (deploy_package /restore_package actions)

Testing run_tests , get_test_job

Unity Test Framework

Batch batch_execute

Parallel/bulk operations

Camera manage_camera

Camera management (Unity Camera + Cinemachine). Tier 1 (always available): create, target, lens, priority, list, screenshot. Tier 2 (requires com.unity.cinemachine ): brain, body/aim/noise pipeline, extensions, blending, force/release. 7 presets: follow, third_person, freelook, dolly, static, top_down, side_scroller. Resource: mcpforunity://scene/cameras . Use ping to check Cinemachine availability. See tools-reference.md.

Graphics manage_graphics

Rendering and post-processing management. 33 actions across 5 groups: Volume (create/configure volumes and effects, URP/HDRP), Bake (lightmaps, light probes, reflection probes, Edit mode only), Stats (draw calls, batches, memory), Pipeline (quality levels, pipeline settings), Features (URP renderer features: add, remove, toggle, reorder). Resources: mcpforunity://scene/volumes , mcpforunity://rendering/stats , mcpforunity://pipeline/renderer-features . Use ping to check pipeline status. See tools-reference.md.

Packages manage_packages

Install, remove, search, and manage Unity packages and scoped registries. Query actions: list installed, search registry, get info, ping, poll status. Mutating actions: add/remove packages, embed for editing, add/remove scoped registries, force resolve. Validates identifiers, warns on git URLs, checks dependents before removal (force=true to override). See tools-reference.md.

ProBuilder manage_probuilder

3D modeling, mesh editing, complex geometry. When com.unity.probuilder is installed, prefer ProBuilder shapes over primitive GameObjects for editable geometry, multi-material faces, or complex shapes. Supports 12 shape types, face/edge/vertex editing, smoothing, and per-face materials. See ProBuilder Guide.

UI manage_ui , batch_execute with manage_gameobject

• manage_components

UI Toolkit: Use manage_ui to create UXML/USS files, attach UIDocument, inspect visual trees. uGUI (Canvas): Use batch_execute for Canvas, Panel, Button, Text, Slider, Toggle, Input Field. Read mcpforunity://project/info first to detect uGUI/TMP/Input System/UI Toolkit availability. (see UI workflows)

Common Workflows

Creating a New Script and Using It

1. Create the script (automatically triggers import + compilation)

create_script( path="Assets/Scripts/PlayerController.cs", contents="using UnityEngine;\n\npublic class PlayerController : MonoBehaviour\n{\n void Update() { }\n}" )

2. Wait for compilation to finish

Read mcpforunity://editor/state → wait until is_compiling == false

3. Check for compilation errors

read_console(types=["error"], count=10)

4. Only then attach to GameObject

manage_gameobject(action="modify", target="Player", components_to_add=["PlayerController"])

Finding and Modifying GameObjects

1. Find by name/tag/component (returns IDs only)

result = find_gameobjects(search_term="Enemy", search_method="by_tag", page_size=50)

2. Get full data via resource

mcpforunity://scene/gameobject/{instance_id}

3. Modify using the ID

manage_gameobject(action="modify", target=instance_id, position=[10, 0, 0])

Running and Monitoring Tests

1. Start test run (async)

result = run_tests(mode="EditMode", test_names=["MyTests.TestSomething"]) job_id = result["job_id"]

2. Poll for completion

result = get_test_job(job_id=job_id, wait_timeout=60, include_failed_tests=True)

Pagination Pattern

Large queries return paginated results. Always follow next_cursor :

cursor = 0 all_items = [] while True: result = manage_scene(action="get_hierarchy", page_size=50, cursor=cursor) all_items.extend(result["data"]["items"]) if not result["data"].get("next_cursor"): break cursor = result["data"]["next_cursor"]

Multi-Instance Workflow

When multiple Unity Editors are running:

1. List instances via resource: mcpforunity://instances

2. Set active instance

set_active_instance(instance="MyProject@abc123")

3. All subsequent calls route to that instance

Error Recovery

Symptom Cause Solution

Tools return "busy" Compilation in progress Wait, check editor_state

"stale_file" error File changed since SHA Re-fetch SHA with get_sha , retry

Connection lost Domain reload Wait ~5s, reconnect

Commands fail silently Wrong instance Check set_active_instance

Reference Files

For detailed schemas and examples:

• tools-reference.md: Complete tool documentation with all parameters

• resources-reference.md: All available resources and their data

• workflows.md: Extended workflow examples and patterns