# Unity MCP

> Expert guide for MCP for Unity tools. Resource-first workflow, domain-organized reference, and practical patterns for Unity automation through MCP.

- Skill: `whatevertogo/unity-mcp` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add whatevertogo/unity-mcp`
- Raw SKILL.md: https://api.skillmd.com/api/skills/whatevertogo/unity-mcp/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: whatevertogo (https://skillmd.com/u/whatevertogo)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/whatevertogo/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](domains/gameobjects.md) | find, manage, components | gameobject/{id} |
| [scripts](domains/scripts.md) | create, edit, validate | editor/state |
| [scene](domains/scene.md) | manage_scene | scene/hierarchy |
| [materials](domains/materials.md) | manage_material | project/tags, layers |
| [prefabs](domains/prefabs.md) | manage_prefabs | prefab/{path} |
| [testing](domains/testing.md) | run_tests, console | tests |
| [editor](domains/editor.md) | play, menu, tags | editor/selection |
| [assets](domains/assets.md) | manage_asset | assets/all |
| [advanced](domains/advanced.md) | texture, VFX, shader | custom-tools |

**Standalone**: [batch_execute](tools/batch_execute.md) (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.

```python
# ✅ 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](tools/batch_execute.md) 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](workflows.md) for practical examples.