Unity MCP Workflows

Use this skill when interacting with the Unity Editor from Claude Code via MCP tools, including scene manipulation, script management, test execution, and asset operations.

Setup

UnityMCP is configured in .mcp.json at the project root:

json
1{
2  "mcpServers": {
3    "UnityMCP": {
4      "command": "npx",
5      "args": ["-y", "@anthropic/unity-mcp@latest"]
6    }
7  }
8}

Prerequisites:

• Unity Editor must be open with the project loaded
• The corresponding Unity package/addon must be installed in the project
• Node.js/npx available on PATH

Additional UnityMCP Tools

The following UnityMCP tools are available but not covered in detail above:

Use run_tests after script changes to verify nothing broke. Use batch_execute when you need to create multiple GameObjects or modify multiple components in sequence -- it reduces round-trips.

Workflow Best Practices

1. Always Check Compilation After Script Changes

Step 1: manage_script action:"modify" (or create)
Step 2: read_console log_type:"error"
Step 3: If errors → fix and repeat
Step 4: If clean → proceed

2. Use Paging for Large Scenes

Step 1: manage_scene action:"get_hierarchy" page_size:50
Step 2: Check if there's a cursor for next page
Step 3: Continue paging until all objects are retrieved (or you found what you need)

3. Properties Query Strategy

Step 1: manage_gameobject action:"get_components" include_properties:false
        → See which components exist (lightweight response)
Step 2: manage_gameobject action:"get_components" include_properties:true
        → Only when you need actual property values

4. Check Editor State Before Proceeding

Before performing operations that depend on compilation:

Step 1: Check editor_state.isCompiling in responses
Step 2: If compiling, wait and re-check
Step 3: Only proceed when compilation is complete

5. Use Resources for Reads, Tools for Mutations

• Reading scene hierarchy, component data, file contents → use resource endpoints when available (faster, cached)
• Modifying objects, creating assets, changing properties → use tool endpoints (these modify state)

6. Use batch_execute for Multiple Operations

When you need to create multiple GameObjects or modify multiple components in sequence, use batch_execute to reduce round-trips:

batch_execute:
  calls:
    - tool: manage_gameobject
      params: { action: "set_component_property", ... }
    - tool: manage_gameobject
      params: { action: "set_component_property", ... }

UnityMCP Tool Selection Guide

Troubleshooting

Topic Pages

• UnityMCP Tools