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.
code
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, capture_screenshot (in manage_scene), resources
Critical Best Practices
1. After Writing/Editing Scripts: Always Refresh and Check Console
python
# After create_script or script_apply_edits: refresh_unity(mode="force", scope="scripts", compile="request", wait_for_ready=True) read_console(types=["error"], count=10, include_stacktrace=True)
Why: Unity must compile scripts before they're usable. Compilation errors block all tool execution.
2. Use batch_execute for Multiple Operations
python
# 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.
3. Use screenshot in manage_scene to Verify Visual Results
python
# Via manage_scene manage_scene(action="screenshot") # Returns base64 image # After creating/modifying objects, verify visually: # 1. Create objects # 2. capture screenshot # 3. Analyze if result matches intent
4. Check Console After Major Changes
python
read_console(
action="get",
types=["error", "warning"], # Focus on problems
count=10,
format="detailed"
)
5. Always Check editor_state Before Complex Operations
python
# 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)
python
# Both forms accepted: position=[1.0, 2.0, 3.0] # List position="[1.0, 2.0, 3.0]" # JSON string
Booleans
python
# Both forms accepted: include_inactive=True # Boolean include_inactive="true" # String
Colors
python
# 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
python
# 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, refresh_unity | C# code management |
| Assets | manage_asset, manage_prefabs | Asset operations |
| Editor | manage_editor, execute_menu_item, read_console | Editor control |
| Testing | run_tests, get_test_job | Unity Test Framework |
| Batch | batch_execute | Parallel/bulk operations |
| UI | batch_execute with manage_gameobject + manage_components | Canvas, Panel, Button, Text, Slider, Toggle, Input Field (see UI workflows) |
Common Workflows
Creating a New Script and Using It
python
# 1. Create the script
create_script(
path="Assets/Scripts/PlayerController.cs",
contents="using UnityEngine;\n\npublic class PlayerController : MonoBehaviour\n{\n void Update() { }\n}"
)
# 2. CRITICAL: Refresh and wait for compilation
refresh_unity(mode="force", scope="scripts", compile="request", wait_for_ready=True)
# 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
python
# 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
python
# 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:
python
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:
python
# 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