unity-editor

bigdra50's avatarfrom bigdra50

Comprehensive Unity Editor operations using unity-mcp-client CLI via uvx. Covers daily workflows (refresh, console, build verification), asset management, scene/object manipulation, and debugging. This skill should be used when users request Unity Editor operations, error analysis, log review, asset refresh, test execution, or after making script/asset modifications.

⭐0stars🔀0forks📁View on GitHub🕐Updated Dec 20, 2025
[Developer Tools]

When & Why to Use This Skill

The Unity Editor Operations skill enables seamless integration between Claude and the Unity Editor via the unity-mcp-client. It empowers developers to automate complex game development workflows, including real-time build verification, console log analysis, and scene hierarchy manipulation. By providing a bridge to the Unity environment, this skill facilitates rapid debugging, automated testing, and efficient asset management directly through natural language commands, significantly reducing context switching for game developers.

Use Cases

  • Automated Debugging: Automatically retrieve and analyze Unity console errors or warnings after script modifications to identify and fix bugs instantly.
  • Build Verification: Run comprehensive project validations (refresh, clear, and verify) to ensure the project compiles correctly after pulling updates or editing .asmdef files.
  • Scene & Object Manipulation: Create, find, or modify GameObjects and materials using text commands, streamlining the process of setting up scenes or prototyping levels.
  • Test Execution: Trigger EditMode and PlayMode tests directly from the chat interface to validate game logic and maintain high code quality.
  • Play Mode Management: Control the Unity Editor's play state and monitor real-time logs to debug runtime exceptions and performance issues.
nameunity-editor
descriptionUnity Editor operations via unity-mcp-client CLI. Handles build verification, console logs, tests, scene/object manipulation. Use after script edits or for debugging.
- Bash(uvx*)
contextfork
agentgeneral-purpose
- matcher"Bash"
- typecommand
command"uvx --from git+https://github.com/bigdra50/unity-mcp-client unity-mcp console --types error --count 5 2>/dev/null || true"
oncetrue

Unity Editor Operations

Quick Reference

# Define alias for brevity (all examples below use this)
alias umcp='uvx --from git+https://github.com/bigdra50/unity-mcp-client unity-mcp'

Commands Overview

Command Purpose
verify Full validation (refresh→clear→wait→console)
refresh Refresh asset database
state Get editor state (isCompiling, isPlaying)
console Get console logs
clear Clear console
play / stop Enter/Exit Play Mode
tests <mode> Run tests (EditMode/PlayMode)
config Show/initialize configuration
scene <action> Scene operations
gameobject <action> GameObject operations
material <action> Material operations

See references/mcp-commands.md for detailed options.

Global Options

Option Description Default
--port MCP server port Auto-detect (macOS)
--host MCP server host localhost
--timeout Max wait for compilation (verify) 5s
--connection-timeout TCP connection timeout (verify) 30s
--retry Max connection retry attempts (verify) 3
--types Log types (error, warning, log) error warning
--count Number of logs to retrieve 20

Core Workflows

1. Build Verification (Post-Edit)

After editing C# scripts, shaders, or .asmdef files:

umcp verify                        # Standard verification
umcp verify --timeout 120          # Extended timeout for large projects
umcp verify --types error warning log  # Include all log types

Workflow:

Edit Script → verify → Fix if Errors → Repeat

2. Console Log Analysis

umcp console --types error         # Errors only
umcp console                       # Errors and warnings (default)
umcp console --types error warning log --count 50  # All logs

3. Test Execution

umcp tests EditMode                # Run EditMode tests
umcp tests PlayMode                # Run PlayMode tests

4. Configuration

umcp config                        # Show current configuration
umcp config init                   # Generate .unity-mcp.toml
umcp config init --output my.toml  # Custom output path
umcp config init --force           # Overwrite existing

5. Scene Operations

umcp scene active                  # Get active scene info
umcp scene hierarchy               # Get scene hierarchy
umcp scene build-settings          # Get scenes in build
umcp scene load --name MainScene   # Load by name
umcp scene load --path Assets/Scenes/Level1.unity
umcp scene load --build-index 0    # Load by build index
umcp scene save                    # Save current scene
umcp scene create --name NewScene --path Assets/Scenes

6. GameObject Operations

umcp gameobject find "Main Camera"
umcp gameobject create --name "MyCube" --primitive Cube --position 0,1,0
umcp gameobject modify --name "MyCube" --position 5,0,0 --rotation 0,45,0
umcp gameobject delete --name "MyCube"

Options: --name, --primitive, --position, --rotation, --scale, --parent, --search-method

7. Material Operations

umcp material info --path Assets/Materials/Default.mat
umcp material create --path Assets/Materials/New.mat --shader Standard
umcp material set-color --path Assets/Materials/New.mat --color 1,0,0,1
umcp material assign --path Assets/Materials/New.mat --target "MyCube"

8. Play Mode Control

umcp play                          # Enter Play Mode
umcp stop                          # Exit Play Mode
umcp state                         # Check current state

Error Resolution

Error Type Identification Priority
Compilation (CS####) CS error codes Critical
Assembly Reference Missing .asmdef refs Critical
Runtime Exception NullReference, Missing High
Deprecation Warning Obsolete API usage Medium

Process:

  1. Parse error message (file/line/type)
  2. Classify (compilation vs runtime)
  3. Apply targeted fix
  4. Run verify to confirm
  5. Iterate until resolved

After 3 failed attempts, ask user for guidance.

Troubleshooting

Connection Failures:

  1. Verify Unity Editor is running
  2. Check Tools → MCP for Unity → Settings
  3. Use --retry for transient failures
  4. Try --port 6400 if auto-detection fails

Timeout Issues:

  1. Increase: --timeout 120 --connection-timeout 60
  2. Check Unity for blocking dialogs

Usage Triggers

Use this skill when:

  • User reports Unity errors or compilation problems
  • After script or asset modifications
  • User requests log analysis or debugging
  • Before running Unity tests
  • Scene or GameObject operations needed