unity-mcp-patterns

name	unity-mcp-patterns
description	How to use unity-mcp tools effectively — batch_execute for speed, read_console for verification, resource queries for project state, tool organization patterns.
alwaysApply	true

Unity MCP Patterns

The unity-mcp server gives Claude Code direct control over the Unity Editor. These patterns ensure you use it efficiently and safely.

Rule 1: batch_execute for Everything

Individual MCP calls have network overhead. batch_execute bundles multiple operations into one call — 10-100x faster.

// BAD — 5 separate calls, 5 round trips
manage_gameobject → create Player
manage_components → add Rigidbody2D to Player
manage_components → add BoxCollider2D to Player
manage_components → add SpriteRenderer to Player
manage_components → configure Rigidbody2D

// GOOD — 1 batch call
batch_execute → [
  create Player,
  add Rigidbody2D,
  add BoxCollider2D,
  add SpriteRenderer,
  configure Rigidbody2D
]

Always batch when doing 2+ operations.

Rule 2: read_console After Every Change

After writing scripts, creating objects, or modifying components, always check the console:

1. Write/Edit C# file
2. read_console → check for compilation errors
3. If errors: fix and repeat
4. Continue with MCP operations
5. read_console → check for runtime warnings

The console is your feedback loop. Don't assume operations succeeded.

Rule 3: project_info Before Assumptions

Before making decisions about the project, read its state:

project_info resource → Unity version, platform, render pipeline

Don't assume:

• The project uses URP (might be Built-in or HDRP)
• The project targets PC (might be mobile)
• Certain packages are installed

Rule 4: Tool Selection Guide

Task	Tool	Key Actions
Create/load/save scene	manage_scene	create, load, save, validate
Create/modify GameObjects	manage_gameobject	create, modify, delete, find
Add/configure components	manage_components	add, remove, configure, get
Physics setup	manage_physics	settings, layers, materials, joints
Camera/Cinemachine	manage_camera	create, configure presets, extensions
Materials/Shaders	manage_material / manage_shader	create, assign, configure
Animation	manage_animation	clips, controllers, states
UI elements	manage_ui	create, layout, style
VFX	manage_vfx	particles, effects
Prefabs	manage_prefabs	create, instantiate, modify
ScriptableObjects	manage_scriptable_object	create, edit
Packages	manage_packages	install, remove, search
Builds	manage_build	configure, build, switch platform
Tests	run_tests	execute, get results
Profiling	manage_profiler	sessions, timing, memory
Graphics stats	manage_graphics	rendering stats, pipeline
Console output	read_console	errors, warnings, logs
API inspection	unity_reflect	live C# reflection
Documentation	unity_docs	official Unity docs
C# scripts	create_script / validate_script	create, validate

Rule 5: Scene Templates

When creating new scenes, use templates for quick setup:

manage_scene action:"create" template:"3d_basic"
// Creates scene with: Main Camera, Directional Light

manage_scene action:"create" template:"2d_basic"
// Creates scene with: Main Camera (orthographic)

Rule 6: Error Recovery

If an MCP operation fails:

1. read_console — get the error message
2. Fix the underlying issue (missing reference, wrong type, etc.)
3. Retry the operation
4. If the error persists, fall back to writing an Editor script

Rule 7: MCP vs File Editing

Operation	Use MCP	Use File Edit
Create GameObjects	Yes	Never
Edit scenes	Yes	Never
Edit prefabs	Yes	Never
Write C# scripts	Either	Preferred for complex scripts
Configure components	Yes	Never
Modify ProjectSettings	Yes	Never
Edit .shader/.hlsl files	No (Write tool)	Yes
Edit .uxml/.uss files	No (Write tool)	Yes
Edit .asmdef files	No (Write tool)	Yes

Rule 8: Multi-Instance

If the user has multiple Unity Editor instances:

unity_instances resource → list all running editors
set_active_instance → route commands to specific editor

Always check which instance is active before sending commands.