unity-mcp

Unity MCP

Essential guidance for using MCP for Unity tools effectively.

Resource-First Workflow ⭐

Always read resources before using tools - prevents errors and provides context.

1. Check state   → mcpforunity://editor/state (ready_for_tools?)
2. Understand   → Resources (scene, gameobject, prefab, etc.)
3. Find target  → find_gameobjects or resource queries
4. Act          → Tools (manage_gameobject, create_script, etc.)
5. Verify       → read_console, check resources

Why: Tools fail if Unity is compiling or wrong instance active. Resources show current state before modification.

Quick Reference

Domain	Tools	Resources
gameobjects	find, manage, components	gameobject/{id}
scripts	create, edit, validate	editor/state
scene	manage_scene	scene/hierarchy
materials	manage_material	project/tags, layers
prefabs	manage_prefabs	prefab/{path}
testing	run_tests, console	tests
editor	play, menu, tags	editor/selection
assets	manage_asset	assets/all
advanced	texture, VFX, shader	custom-tools

Standalone: batch_execute (10-100x faster,use when executing many commands)

Critical Patterns

Targeting Priority

1. Instance ID (most reliable):
   manage_gameobject(action="modify", target=-24152, search_method="by_id", position=[1,2,3])

2. Exact name (by_name is exact match):
   manage_gameobject(action="modify", target="MyObject", position=[1,2,3])

3. Tag/component search:
   find_gameobjects(search_term="Enemy", search_method="by_tag")

After Script Operations

1. create_script(...) or script_apply_edits(...)
2. Poll mcpforunity://editor/state until:
   - external_changes_dirty = false
   - is_compiling = false
   - last_domain_reload_after_unix_ms set
3. read_console(types=["error"]) - check for errors
4. manage_components(action="add", target=..., component_type="NewScript")

Batch Operations ⭐

⚠️ CRITICAL: Always use batch_execute for multi-object creation. Prevents hierarchy corruption.

# ✅ Complete scene setup in ONE atomic operation
batch_execute(commands=[
    {tool: "manage_gameobject", params: {action: "create", name: "Ground", primitive_type: "Plane", scale: [10,1,10]}},
    {tool: "manage_gameobject", params: {action: "create", name: "Player", primitive_type: "Capsule", position: [0,1,0], parent: "Ground", components_to_add: ["Rigidbody"]}},
    {tool: "manage_components", params: {action: "add", target: "Player", component_type: "BoxCollider"}}
])
# Returns: All created successfully OR all failed → consistent state

# ❌ BAD: Sequential calls (corruption risk!)
manage_gameobject(action="create", name="Parent")  # Created
manage_gameobject(action="create", name="Child", parent="Parent")  # Interrupted here!
# Result: Orphaned Parent, broken hierarchy

Benefits: Atomic (all-or-nothing), 10-100x faster, prevents inconsistent state.

See: batch_execute for full documentation.

Common Issues

Issue	Solution
GameObject not found	by_name is exact match. Use exact name or by_tag
Component not found	Script not compiled. Wait for domain_reload_after
Tools fail	State stale (>60s). Poll mcpforunity://editor/state
Operations timeout	Use page_size on queries
"busy" response	Unity compiling. Wait for is_compiling=false

Best Practices

✅ DO:

• Check editor/state before operations
• Use batch_execute for multi-object ops
• Target by instance ID when possible
• Poll editor state after script changes
• Use page_size on large queries

❌ DON'T:

• Use tools while is_compiling=true
• Create objects one-by-one in loops
• Assume by_name does partial matching
• Skip checking console after scripts

Coverage

✅ 27 tools | 17 resources | 100% documented

See workflows.md for practical examples.