unity-mcp: Skill for Claude Code

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/state
2. Understand the scene   → mcpforunity://scene/gameobject-api
3. Find what you need     → find_gameobjects or resources
4. 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

If a tool you need is not in your tool list, it is not necessarily missing. Check these before troubleshooting the connection:

• Project custom tools (C# [McpForUnityTool]): with project-scoped tools enabled on the server, they are not callable by name. List them via mcpforunity://custom-tools and run them with execute_custom_tool(tool_name="...", parameters={...}). With it disabled, they are registered as ordinary tools and appear in your list.
• Disabled tool groups: over HTTP, a session starts with only the core group enabled. Over stdio, all groups start enabled and are then synced to the tool toggles in the Unity editor, so a tool can still be hidden. manage_tools(action="list_groups") shows the groups, manage_tools(action="activate", group="...") enables one.

Critical Best Practices