Unity MCP Tools
Expert knowledge for coordinating Unity MCP operations, including tool enablement, agent orchestration, and direct MCP tool usage.
Quick Start: MCP Workflow
1. Inspect First (Always Available)
CRITICAL: The MCP Resource is ALWAYS enabled and never disabled - no tool enablement needed. This is the primary way agents inspect Unity.
How to Access (works for all agents including subagents):
Tool: ReadMcpResourceTool
Server: ai-game-developer
URI: unity://gameobject/{scene}/{path}
Example:
{
"server": "ai-game-developer",
"uri": "unity://gameobject/GameplayScene/TileManager"
}
Returns: Transform, components, properties, children
Resource vs Tools Decision Table:
| Need |
Use |
| Inspect scene structure |
MCP Resource (always available) |
| Read component values |
MCP Resource (always available) |
| Create/modify objects |
MCP Tools (require enablement) |
| Run tests |
MCP Tools (require enablement) |
Most agents should use this resource for read operations before enabling any tools.
2. Enable Tools When Modification Needed
Run /unity-mcp-enable [groups] before instructing agents that need MCP to fulfill a task.
3. Spawn Agent with Skills
Include unity-mcp-tools skill for agents doing MCP work:
| Task |
Enable Groups |
Spawn Agent |
| Create/modify GameObjects |
gameobject, component |
scene-builder |
| Add UI elements |
gameobject, component |
ui-ux-developer |
| Run tests |
testing |
test-engineer |
| Work with scripts |
script |
code-architect |
| Create prefabs |
prefab, gameobject |
scene-builder |
| Deploy build |
(none) |
deployment-specialist |
4. Cleanup After MCP Work
Run /unity-mcp-reset to disable tools and save context.
Commands Reference
Subagents cannot use these commands, but claude code can trigger them or ask the user to use them.
| Command |
Purpose |
/unity-mcp-status |
Show enabled groups |
/unity-mcp-enable [groups] |
Enable tool groups |
/unity-mcp-enable-all |
Enable all tools |
/unity-mcp-reset |
Disable all tools |
/unity-mcp-scene-info [path] |
Query scene via Resource |
When to Consult mcp-advisor
Spawn the mcp-advisor advisory agent when:
- Unsure which tool groups are needed
- MCP tools returning errors
- Complex multi-step Unity operations
- Need troubleshooting help
Example prompt: "What MCP tool groups do I need to add a health bar UI?"
The mcp-advisor returns recommendations - it does not execute commands.
Agent Skill Assignments
When spawning agents, include these skills:
| Agent |
Skills to Include |
| scene-builder |
unity-mcp-tools, layout-sizing, visual-style-guide |
| test-engineer |
unity-mcp-tools, unity-testing |
| ui-ux-developer |
layout-sizing, visual-style-guide |
| input-developer |
board-sdk, unity-mcp-tools |
| code-architect |
project-architecture |
| game-designer |
zero-day-rules |
| deployment-specialist |
(none - uses Bash) |
| project-producer |
documentation |
| mcp-advisor |
unity-mcp-tools |
Subagent MCP Access
Subagents can use MCP tools directly when:
- Tools are enabled in
AI-Game-Developer-Config.json
- Agent inherits tools (omit
tools: field in frontmatter)
To give MCP access, omit the tools field:
---
name: scene-builder
skills: unity-mcp-tools, layout-sizing
# No tools field = inherits ALL including MCP
---
Subagent Constraints
| CAN Do |
CANNOT Do |
| Use MCP Resource anytime (always available) |
Run /unity-mcp-enable commands |
| Use MCP Tools when enabled by orchestrator |
Run /unity-mcp-reset commands |
| Request orchestrator enable specific groups |
Enable or disable tools for themselves |
If MCP tools aren't working: Report to orchestrator which tool groups you need enabled (e.g., "Need gameobject and component groups").
Tool Groups Reference
Use /unity-mcp-enable [group] to enable. Multiple: /unity-mcp-enable gameobject component
Core Groups and Tools (11 total)
| Group |
Tools |
Use Case |
| scene-read |
scene-get-data, scene-list-opened, console-get-logs |
Inspect scene hierarchy |
| scene-write |
scene-create, scene-save, scene-open, scene-set-active, scene-unload, console-get-logs |
Modify scenes |
| gameobject |
gameobject-create, gameobject-find, gameobject-modify, gameobject-destroy, gameobject-duplicate, gameobject-set-parent, scene-save, console-get-logs |
GameObject operations |
| component |
gameobject-component-add, gameobject-component-get, gameobject-component-modify, gameobject-component-destroy, component-list, scene-save, console-get-logs |
Component operations |
| script |
script-read, script-update-or-create, script-delete, script-execute, assets-refresh, editor-application-get-state, console-get-logs |
Script operations |
| prefab |
assets-prefab-create, assets-prefab-instantiate, assets-prefab-open, assets-prefab-save, assets-prefab-close, assets-refresh, editor-application-get-state, console-get-logs |
Prefab operations |
| assets |
assets-find, assets-create-folder, assets-copy, assets-move, assets-delete, assets-get-data, assets-modify, assets-refresh, assets-material-create, assets-shader-list-all, console-get-logs |
Asset management |
| testing |
tests-run, editor-application-get-state, console-get-logs |
Run Unity tests |
| editor |
editor-application-get-state, editor-application-set-state, console-get-logs, editor-selection-get, editor-selection-set |
Full editor control |
| packages |
package-list, package-add, package-remove, package-search, console-get-logs |
Package management |
| reflection |
reflection-method-find, reflection-method-call, console-get-logs |
Advanced operations |
Cross-cutting Utilities (Auto-included)
| Tool |
Auto-included with |
| console-get-logs |
ALL groups |
| editor-application-get-state |
script, testing, prefab |
| assets-refresh |
script, prefab |
| scene-save |
gameobject, component |
Common Patterns
Create GameObject with Components
- Enable:
/unity-mcp-enable gameobject component
- Use
gameobject-create to create object
- Use
gameobject-component-add to add components
- Use
gameobject-component-modify to configure
Run Tests After Code Changes
- Enable:
/unity-mcp-enable testing
- Use
tests-run with testMode: "EditMode" or "PlayMode"
- Check results, fix failures
Inspect Before Modifying
Always use MCP Resource first (no enablement):
/unity-mcp-scene-info {path} to understand structure- Then enable tools only if modification needed
Configuration
Config file: Assets/Resources/AI-Game-Developer-Config.json
Structure:
{
"tools": [{ "name": "tool-name", "enabled": true/false }],
"resources": [{ "name": "GameObject from Current Scene by Path", "enabled": true }]
}
The MCP Resource is always enabled. Tools default to disabled.
Reference Files
This skill's references/ folder contains complete MCP documentation organized for efficient navigation.
Main Guides (4 files)
| File |
Contains |
Read When |
mcp-setup.md |
MCP server startup, connection verification |
Setting up or troubleshooting MCP |
tool-groups.md |
11 tool groups with JSON definitions |
Understanding group configurations |
tool-reference.md |
All 49 MCP tools organized by category |
Need specific tool usage details |
troubleshooting.md |
Connection issues, tool errors, common fixes |
MCP not working as expected |
Tool Parameter Reference (11 files in tool-parameters/)
Detailed parameters and examples for each tool category:
| File |
Tools Covered |
scene-tools.md |
scene-get-data, scene-create, scene-save, etc. |
gameobject-tools.md |
gameobject-create, gameobject-find, gameobject-modify |
component-tools.md |
component-add, component-get, component-modify |
script-tools.md |
script-read, script-update-or-create, script-execute |
asset-tools.md |
assets-find, assets-copy, assets-move, assets-delete |
prefab-tools.md |
prefab-create, prefab-instantiate, prefab-open |
editor-tools.md |
editor-application-get-state, editor-selection |
testing-tools.md |
tests-run with testMode, filters, options |
package-tools.md |
package-list, package-add, package-remove |
reflection-tools.md |
reflection-method-find, reflection-method-call |
material-shader-tools.md |
assets-material-create, assets-shader-list-all |
Related Documentation
- Documentation/Unity-MCP-Documentation.md - Full MCP setup guide
- .mcp.json - Connection configuration
- Assets/Resources/AI-Game-Developer-Config.json - Tool enablement config
1---2name: unity-mcp-tools3description: This skill should be used when the user asks about "MCP tools", "Unity MCP", "enable tool groups", "which MCP tools", "create GameObject", "add component", "run Unity tests", "check scene hierarchy", "spawn agent for Unity", "MCP not working", or needs to coordinate Unity Editor operations via MCP.4---5
6# Unity MCP Tools
7
8Expert knowledge for coordinating Unity MCP operations, including tool enablement, agent orchestration, and direct MCP tool usage.
9
10## Quick Start: MCP Workflow
11
12### 1. Inspect First (Always Available)
13
14**CRITICAL:** The MCP Resource is ALWAYS enabled and never disabled - no tool enablement needed. This is the primary way agents inspect Unity.
15
16**How to Access** (works for all agents including subagents):
17
18```text
19Tool: ReadMcpResourceTool
20Server: ai-game-developer
21URI: unity://gameobject/{scene}/{path}
22```
23
24**Example**:
25
26```json
27{
28 "server": "ai-game-developer",
29 "uri": "unity://gameobject/GameplayScene/TileManager"
30}
31```
32
33**Returns**: Transform, components, properties, children
34
35**Resource vs Tools Decision Table**:
36
37| Need | Use |
38| ----------------------- | ------------------------------- |
39| Inspect scene structure | MCP Resource (always available) |
40| Read component values | MCP Resource (always available) |
41| Create/modify objects | MCP Tools (require enablement) |
42| Run tests | MCP Tools (require enablement) |
43
44Most agents should use this resource for read operations before enabling any tools.
45
46### 2. Enable Tools When Modification Needed
47
48Run `/unity-mcp-enable [groups]` before instructing agents that need MCP to fulfill a task.
49
50### 3. Spawn Agent with Skills
51
52Include `unity-mcp-tools` skill for agents doing MCP work:
53
54| Task | Enable Groups | Spawn Agent |
55| ------------------------- | --------------------- | --------------------- |
56| Create/modify GameObjects | gameobject, component | scene-builder |
57| Add UI elements | gameobject, component | ui-ux-developer |
58| Run tests | testing | test-engineer |
59| Work with scripts | script | code-architect |
60| Create prefabs | prefab, gameobject | scene-builder |
61| Deploy build | (none) | deployment-specialist |
62
63### 4. Cleanup After MCP Work
64
65Run `/unity-mcp-reset` to disable tools and save context.
66
67## Commands Reference
68
69Subagents cannot use these commands, but claude code can trigger them or ask the user to use them.
70
71| Command | Purpose |
72| ------------------------------ | ------------------------ |
73| `/unity-mcp-status` | Show enabled groups |
74| `/unity-mcp-enable [groups]` | Enable tool groups |
75| `/unity-mcp-enable-all` | Enable all tools |
76| `/unity-mcp-reset` | Disable all tools |
77| `/unity-mcp-scene-info [path]` | Query scene via Resource |
78
79## When to Consult mcp-advisor
80
81Spawn the `mcp-advisor` advisory agent when:
82
83- Unsure which tool groups are needed
84- MCP tools returning errors
85- Complex multi-step Unity operations
86- Need troubleshooting help
87
88Example prompt: "What MCP tool groups do I need to add a health bar UI?"
89
90The `mcp-advisor` returns recommendations - it does not execute commands.
91
92## Agent Skill Assignments
93
94When spawning agents, include these skills:
95
96| Agent | Skills to Include |
97| --------------------- | -------------------------------------------------- |
98| scene-builder | unity-mcp-tools, layout-sizing, visual-style-guide |
99| test-engineer | unity-mcp-tools, unity-testing |
100| ui-ux-developer | layout-sizing, visual-style-guide |
101| input-developer | board-sdk, unity-mcp-tools |
102| code-architect | project-architecture |
103| game-designer | zero-day-rules |
104| deployment-specialist | (none - uses Bash) |
105| project-producer | documentation |
106| mcp-advisor | unity-mcp-tools |
107
108## Subagent MCP Access
109
110Subagents can use MCP tools directly when:
111
1121. Tools are enabled in `AI-Game-Developer-Config.json`
1132. Agent inherits tools (omit `tools:` field in frontmatter)
114
115To give MCP access, omit the tools field:
116
117```yaml
118---
119name: scene-builder
120skills: unity-mcp-tools, layout-sizing
121# No tools field = inherits ALL including MCP
122---
123```
124
125### Subagent Constraints
126
127| CAN Do | CANNOT Do |
128| ------------------------------------------- | -------------------------------------- |
129| Use MCP Resource anytime (always available) | Run `/unity-mcp-enable` commands |
130| Use MCP Tools when enabled by orchestrator | Run `/unity-mcp-reset` commands |
131| Request orchestrator enable specific groups | Enable or disable tools for themselves |
132
133**If MCP tools aren't working**: Report to orchestrator which tool groups you need enabled (e.g., "Need gameobject and component groups").
134
135## Tool Groups Reference
136
137Use `/unity-mcp-enable [group]` to enable. Multiple: `/unity-mcp-enable gameobject component`
138
139### Core Groups and Tools (11 total)
140
141| Group | Tools | Use Case |
142| ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- |
143| scene-read | scene-get-data, scene-list-opened, console-get-logs | Inspect scene hierarchy |
144| scene-write | scene-create, scene-save, scene-open, scene-set-active, scene-unload, console-get-logs | Modify scenes |
145| gameobject | gameobject-create, gameobject-find, gameobject-modify, gameobject-destroy, gameobject-duplicate, gameobject-set-parent, scene-save, console-get-logs | GameObject operations |
146| component | gameobject-component-add, gameobject-component-get, gameobject-component-modify, gameobject-component-destroy, component-list, scene-save, console-get-logs | Component operations |
147| script | script-read, script-update-or-create, script-delete, script-execute, assets-refresh, editor-application-get-state, console-get-logs | Script operations |
148| prefab | assets-prefab-create, assets-prefab-instantiate, assets-prefab-open, assets-prefab-save, assets-prefab-close, assets-refresh, editor-application-get-state, console-get-logs | Prefab operations |
149| assets | assets-find, assets-create-folder, assets-copy, assets-move, assets-delete, assets-get-data, assets-modify, assets-refresh, assets-material-create, assets-shader-list-all, console-get-logs | Asset management |
150| testing | tests-run, editor-application-get-state, console-get-logs | Run Unity tests |
151| editor | editor-application-get-state, editor-application-set-state, console-get-logs, editor-selection-get, editor-selection-set | Full editor control |
152| packages | package-list, package-add, package-remove, package-search, console-get-logs | Package management |
153| reflection | reflection-method-find, reflection-method-call, console-get-logs | Advanced operations |
154
155### Cross-cutting Utilities (Auto-included)
156
157| Tool | Auto-included with |
158| ---------------------------- | ----------------------- |
159| console-get-logs | ALL groups |
160| editor-application-get-state | script, testing, prefab |
161| assets-refresh | script, prefab |
162| scene-save | gameobject, component |
163
164## Common Patterns
165
166### Create GameObject with Components
167
1681. Enable: `/unity-mcp-enable gameobject component`
1692. Use `gameobject-create` to create object
1703. Use `gameobject-component-add` to add components
1714. Use `gameobject-component-modify` to configure
172
173### Run Tests After Code Changes
174
1751. Enable: `/unity-mcp-enable testing`
1762. Use `tests-run` with testMode: "EditMode" or "PlayMode"
1773. Check results, fix failures
178
179### Inspect Before Modifying
180
181Always use MCP Resource first (no enablement):
182
183- `/unity-mcp-scene-info {path}` to understand structure
184- Then enable tools only if modification needed
185
186## Configuration
187
188Config file: `Assets/Resources/AI-Game-Developer-Config.json`
189
190Structure:
191
192```json
193{
194 "tools": [{ "name": "tool-name", "enabled": true/false }],
195 "resources": [{ "name": "GameObject from Current Scene by Path", "enabled": true }]
196}
197```
198
199The MCP Resource is always enabled. Tools default to disabled.
200
201## Reference Files
202
203This skill's `references/` folder contains complete MCP documentation organized for efficient navigation.
204
205### Main Guides (4 files)
206
207| File | Contains | Read When |
208| -------------------- | -------------------------------------------- | ---------------------------------- |
209| `mcp-setup.md` | MCP server startup, connection verification | Setting up or troubleshooting MCP |
210| `tool-groups.md` | 11 tool groups with JSON definitions | Understanding group configurations |
211| `tool-reference.md` | All 49 MCP tools organized by category | Need specific tool usage details |
212| `troubleshooting.md` | Connection issues, tool errors, common fixes | MCP not working as expected |
213
214### Tool Parameter Reference (11 files in `tool-parameters/`)
215
216Detailed parameters and examples for each tool category:
217
218| File | Tools Covered |
219| -------------------------- | ----------------------------------------------------- |
220| `scene-tools.md` | scene-get-data, scene-create, scene-save, etc. |
221| `gameobject-tools.md` | gameobject-create, gameobject-find, gameobject-modify |
222| `component-tools.md` | component-add, component-get, component-modify |
223| `script-tools.md` | script-read, script-update-or-create, script-execute |
224| `asset-tools.md` | assets-find, assets-copy, assets-move, assets-delete |
225| `prefab-tools.md` | prefab-create, prefab-instantiate, prefab-open |
226| `editor-tools.md` | editor-application-get-state, editor-selection |
227| `testing-tools.md` | tests-run with testMode, filters, options |
228| `package-tools.md` | package-list, package-add, package-remove |
229| `reflection-tools.md` | reflection-method-find, reflection-method-call |
230| `material-shader-tools.md` | assets-material-create, assets-shader-list-all |
231
232### Related Documentation
233
234- **Documentation/Unity-MCP-Documentation.md** - Full MCP setup guide
235- **.mcp.json** - Connection configuration
236- **Assets/Resources/AI-Game-Developer-Config.json** - Tool enablement config
majiayu000