<< All versions
2. Use
5. Always Check
Skill v1.0.0
currentAutomated scan100/100coplaydev/unity-mcp/unity-mcp-skill
──Details
PublishedJune 27, 2026 at 05:11 PM
Content Hashsha256:a8fafae62ca87306...
Git SHAdccecd689072
──Files
Files (1 file, 14.1 KB)
SKILL.md14.1 KBactive
SKILL.md · 284 lines · 14.1 KB
version: "1.0.0" name: unity-mcp-orchestrator description: Orchestrate Unity Editor via MCP (Model Context Protocol) tools and resources. Use when working with Unity projects through MCP for Unity - creating/modifying GameObjects, editing scripts, managing scenes, running tests, or any Unity Editor automation. Provides best practices, tool schemas, and workflow patterns for effective Unity-MCP integration.
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.
1. Check editor state → mcpforunity://editor/state2. Understand the scene → mcpforunity://scene/gameobject-api3. Find what you need → find_gameobjects or resources4. 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
python
# 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 errorsread_console(types=["error"], count=10, include_stacktrace=True)
Why: Unity must compile scripts before they're usable. create_script and script_apply_edits already trigger import and compilation automatically — calling refresh_unity afterward is redundant.
2. Use batch_execute for Multiple Operations
python
# 10-100x faster than sequential callsbatch_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.
Tip: Also use batch_execute for discovery — batch multiple find_gameobjects calls instead of calling them one at a time:
python
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
python
# 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 payloadsmanage_camera(action="screenshot", camera="MainCamera", include_image=True, max_resolution=512)# Batch surround: captures front/back/left/right/top/bird_eye around the scenemanage_camera(action="screenshot", batch="surround", max_resolution=256)# Batch surround centered on a specific objectmanage_camera(action="screenshot", batch="surround", view_target="Player", max_resolution=256)# Positioned screenshot: place a temp camera and capture in one callmanage_camera(action="screenshot", view_target="Player", view_position=[0, 10, -10], max_resolution=512)# Scene View screenshot: capture what the developer sees in the editormanage_camera(action="screenshot", capture_source="scene_view", include_image=True)# Scene View framed on a specific objectmanage_camera(action="screenshot", capture_source="scene_view", view_target="Canvas", include_image=True)
Best practices for AI scene understanding:
- Use
include_image=Truewhen 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_positionto 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_resolutionat 256–512 to balance quality vs. token cost.
python
# Agentic camera loop: point, shoot, analyzemanage_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
python
read_console(action="get",types=["error", "warning"], # Focus on problemscount=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] # Listposition="[1.0, 2.0, 3.0]" # JSON string
Booleans
python
# Both forms accepted:include_inactive=True # Booleaninclude_inactive="true" # String
Colors
python
# Auto-detected format:color=[255, 0, 0, 255] # 0-255 rangecolor=[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, validate_script | C# code management (auto-refreshes on create/edit) | |
| Assets | manage_asset, manage_prefabs | Asset operations. Prefab instantiation is done via manage_gameobject(action="create", prefab_path="..."), not manage_prefabs. | |
| Editor | manage_editor, execute_menu_item, read_console | Editor control, package deployment (deploy_package/restore_package actions) | |
| Testing | run_tests, get_test_job | Unity Test Framework | |
| Batch | batch_execute | Parallel/bulk operations | |
| Camera | manage_camera | Camera management (Unity Camera + Cinemachine). Tier 1 (always available): create, target, lens, priority, list, screenshot. Tier 2 (requires com.unity.cinemachine): brain, body/aim/noise pipeline, extensions, blending, force/release. 7 presets: follow, third_person, freelook, dolly, static, top_down, side_scroller. Resource: mcpforunity://scene/cameras. Use ping to check Cinemachine availability. See tools-reference.md. | |
| Graphics | manage_graphics | Rendering and post-processing management. 33 actions across 5 groups: Volume (create/configure volumes and effects, URP/HDRP), Bake (lightmaps, light probes, reflection probes, Edit mode only), Stats (draw calls, batches, memory), Pipeline (quality levels, pipeline settings), Features (URP renderer features: add, remove, toggle, reorder). Resources: mcpforunity://scene/volumes, mcpforunity://rendering/stats, mcpforunity://pipeline/renderer-features. Use ping to check pipeline status. See tools-reference.md. | |
| Packages | manage_packages | Install, remove, search, and manage Unity packages and scoped registries. Query actions: list installed, search registry, get info, ping, poll status. Mutating actions: add/remove packages, embed for editing, add/remove scoped registries, force resolve. Validates identifiers, warns on git URLs, checks dependents before removal (force=true to override). See tools-reference.md. | |
| Physics | manage_physics | Manage 3D and 2D physics (21 actions). Settings, collision matrix, materials, joints (14 types). Queries: raycast, raycast_all, linecast, shapecast (sphere/box/capsule sweep), overlap. Forces: apply_force (AddForce/AddTorque/AddExplosionForce with ForceMode). Rigidbody: get_rigidbody, configure_rigidbody (mass, drag, gravity, constraints, collision detection). Validation: scene-wide checks. Simulation: simulate_step in edit mode. See tools-reference.md. | |
| ProBuilder | manage_probuilder | 3D modeling, mesh editing, complex geometry. When `com.unity.probuilder` is installed, prefer ProBuilder shapes over primitive GameObjects for editable geometry, multi-material faces, or complex shapes. Supports 12 shape types, face/edge/vertex editing, smoothing, and per-face materials. See ProBuilder Guide. | |
| UI | manage_ui, batch_execute with manage_gameobject + manage_components | UI Toolkit: Use manage_ui to create UXML/USS files, attach UIDocument, inspect visual trees. uGUI (Canvas): Use batch_execute for Canvas, Panel, Button, Text, Slider, Toggle, Input Field. Read `mcpforunity://project/info` first to detect uGUI/TMP/Input System/UI Toolkit availability. (see UI workflows) | |
| Docs | unity_reflect, unity_docs | API verification and documentation lookup. `unity_reflect` inspects live C# APIs via reflection (requires Unity connection): search types across assemblies, get_type for member summary, get_member for full signatures. `unity_docs` fetches official docs from docs.unity3d.com (no Unity connection needed): get_doc (ScriptReference), get_manual (Manual pages), get_package_doc (package docs), lookup (parallel search all sources + project assets). Trust hierarchy: reflection > project assets > docs. Workflow: unity_reflect search -> get_type -> get_member -> unity_docs lookup. See tools-reference.md. |
Common Workflows
Creating a New Script and Using It
python
# 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 errorsread_console(types=["error"], count=10)# 4. Only then attach to GameObjectmanage_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 IDmanage_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 completionresult = 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 = 0all_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"):breakcursor = result["data"]["next_cursor"]
Multi-Instance Workflow
When multiple Unity Editors are running:
python
# 1. List instances via resource: mcpforunity://instances# 2. Set active instanceset_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](references/tools-reference.md): Complete tool documentation with all parameters
- [resources-reference.md](references/resources-reference.md): All available resources and their data
- [workflows.md](references/workflows.md): Extended workflow examples and patterns