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

references/tools-reference.md

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

script_apply_edits

refresh_unity

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

Tip: Also use

batch_execute

find_gameobjects

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

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

manage_scene

find_gameobjects

3d_basic

2d_basic

empty

default

auto_repair

manage_build(action="scenes")

manage_gameobject

manage_components

create_script

script_apply_edits

validate_script

manage_asset

manage_prefabs

manage_gameobject(action="create", prefab_path="...")

manage_prefabs

manage_editor

execute_menu_item

read_console

deploy_package

restore_package

undo

redo

run_tests

get_test_job

batch_execute

manage_camera

com.unity.cinemachine

mcpforunity://scene/cameras

ping

manage_graphics

mcpforunity://scene/volumes

mcpforunity://rendering/stats

mcpforunity://pipeline/renderer-features

ping

manage_packages

force=true

manage_probuilder

com.unity.probuilder

manage_ui

batch_execute

manage_gameobject

manage_components

manage_ui

batch_execute

mcpforunity://project/info

unity_reflect

unity_docs

unity_reflect

search

get_type

get_member

unity_docs

get_doc

get_manual

get_package_doc

lookup

unity_reflect

unity_docs

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

editor_state

get_sha

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