# Unity-MCP Tools Reference
Complete reference for all MCP tools. Each tool includes parameters, types, and usage examples.
> **Template warning:** Examples in this file are skill templates and may be inaccurate for some Unity versions, packages, or project setups. Validate parameters and payload shapes against your active tool schema and runtime behavior.
## Table of Contents
- [Infrastructure Tools](#infrastructure-tools)
- [Scene Tools](#scene-tools)
- [GameObject Tools](#gameobject-tools)
- [Script Tools](#script-tools)
- [Asset Tools](#asset-tools)
- [Material & Shader Tools](#material--shader-tools)
- [UI Tools](#ui-tools)
- [Editor Control Tools](#editor-control-tools)
- [Testing Tools](#testing-tools)
---
## Project Info Resource
Read `mcpforunity://project/info` to detect project capabilities before making assumptions about UI, input, or rendering setup.
**Returned fields:**
| Field | Type | Description |
|-------|------|-------------|
| `projectRoot` | string | Absolute path to project root |
| `projectName` | string | Project folder name |
| `unityVersion` | string | e.g. `"2022.3.20f1"` |
| `platform` | string | Active build target e.g. `"StandaloneWindows64"` |
| `assetsPath` | string | Absolute path to Assets folder |
| `renderPipeline` | string | `"BuiltIn"`, `"Universal"`, `"HighDefinition"`, or `"Custom"` |
| `activeInputHandler` | string | `"Old"`, `"New"`, or `"Both"` |
| `packages.ugui` | bool | `com.unity.ugui` installed (Canvas, Image, Button, etc.) |
| `packages.textmeshpro` | bool | `com.unity.textmeshpro` installed (TMP_Text, TMP_InputField) |
| `packages.inputsystem` | bool | `com.unity.inputsystem` installed (InputAction, PlayerInput) |
| `packages.uiToolkit` | bool | Always `true` for Unity 2021.3+ (UIDocument, VisualElement, UXML/USS) |
| `packages.screenCapture` | bool | `com.unity.modules.screencapture` enabled (ScreenCapture API for screenshots) |
**Key decision points:**
- **UI system**: If `packages.uiToolkit` is true (always for Unity 2021+), use `manage_ui` for UI Toolkit workflows (UXML/USS). If `packages.ugui` is true, use Canvas + uGUI components via `batch_execute`. UI Toolkit is preferred for new UI — it uses a frontend-like workflow (UXML for structure, USS for styling).
- **Text**: If `packages.textmeshpro` is true, use `TextMeshProUGUI` instead of legacy `Text`.
- **Input**: Use `activeInputHandler` to decide EventSystem module — `StandaloneInputModule` (Old) vs `InputSystemUIInputModule` (New). See [workflows.md — Input System](workflows.md#input-system-old-vs-new).
- **Shaders**: Use `renderPipeline` to pick correct shader names — `Standard` (BuiltIn) vs `Universal Render Pipeline/Lit` (URP) vs `HDRP/Lit` (HDRP).
---
## Infrastructure Tools
### batch_execute
Execute multiple MCP commands in a single batch (10-100x faster).
```python
batch_execute(
commands=[ # list[dict], required, max 25
{"tool": "tool_name", "params": {...}},
...
],
parallel=False, # bool, optional - advisory only (Unity may still run sequentially)
fail_fast=False, # bool, optional - stop on first failure
max_parallelism=None # int, optional - max parallel workers
)
```
`batch_execute` is not transactional: earlier commands are not rolled back if a later command fails.
### set_active_instance
Route commands to a specific Unity instance (multi-instance workflows).
```python
set_active_instance(
instance="ProjectName@abc123" # str, required - Name@hash or hash prefix
)
```
### refresh_unity
Refresh asset database and trigger script compilation.
```python
refresh_unity(
mode="if_dirty", # "if_dirty" | "force"
scope="all", # "assets" | "scripts" | "all"
compile="none", # "none" | "request"
wait_for_ready=True # bool - wait until editor ready
)
```
---
## Scene Tools
### manage_scene
Scene CRUD operations, hierarchy queries, screenshots, and scene view control.
```python
# Get hierarchy (paginated)
manage_scene(
action="get_hierarchy",
page_size=50, # int, default 50, max 500
cursor=0, # int, pagination cursor
parent=None, # str|int, optional - filter by parent
include_transform=False # bool - include local transforms
)
# Screenshot (file only — saves to Assets/)
manage_scene(action="screenshot")
# Screenshot with inline image (base64 PNG returned to AI)
manage_scene(
action="screenshot",
camera="MainCamera", # str, optional - camera name, path, or instance ID
include_image=True, # bool, default False - return base64 PNG inline
max_resolution=512 # int, optional - downscale cap (default 640)
)
# Batch surround (6 angles around scene bounds, no file saved)
manage_scene(
action="screenshot",
batch="surround", # str - "surround" for 6-angle capture
max_resolution=256 # int - keep low for batch (6 images)
)
# Returns: front, back, left, right, top, bird_eye views
# Batch surround centered on a specific target
manage_scene(
action="screenshot",
batch="surround",
look_at="Player", # str|int|list[float] - center surround on this target
max_resolution=256
)
# Positioned screenshot (temp camera at viewpoint, no file saved)
manage_scene(
action="screenshot",
look_at="Enemy", # str|int|list[float] - target to aim at
view_position=[0, 10, -10], # list[float], optional - camera position
view_rotation=[45, 0, 0], # list[float], optional - euler angles (overrides look_at aim)
max_resolution=512
)
# Frame scene view on target
manage_scene(
action="scene_view_frame",
scene_view_target="Player" # str|int - GO name, path, or instance ID to frame
)
# Other actions
manage_scene(action="get_active") # Current scene info
manage_scene(action="get_build_settings") # Build settings
manage_scene(action="create", name="NewScene", path="Assets/Scenes/")
manage_scene(action="load", path="Assets/Scenes/Main.unity")
manage_scene(action="save")
```
### find_gameobjects
Search for GameObjects (returns instance IDs only).
```python
find_gameobjects(
search_term="Player", # str, required
search_method="by_name", # "by_name"|"by_tag"|"by_layer"|"by_component"|"by_path"|"by_id"
include_inactive=False, # bool|str
page_size=50, # int, default 50, max 500
cursor=0 # int, pagination cursor
)
# Returns: {"ids": [12345, 67890], "next_cursor": 50, ...}
```
---
## GameObject Tools
### manage_gameobject
Create, modify, delete, duplicate GameObjects.
```python
# Create
manage_gameobject(
action="create",
name="MyCube", # str, required
primitive_type="Cube", # "Cube"|"Sphere"|"Capsule"|"Cylinder"|"Plane"|"Quad"
position=[0, 1, 0], # list[float] or JSON string "[0,1,0]"
rotation=[0, 45, 0], # euler angles
scale=[1, 1, 1],
components_to_add=["Rigidbody", "BoxCollider"],
save_as_prefab=False,
prefab_path="Assets/Prefabs/MyCube.prefab"
)
# Modify
manage_gameobject(
action="modify",
target="Player", # name, path, or instance ID
search_method="by_name", # how to find target
position=[10, 0, 0],
rotation=[0, 90, 0],
scale=[2, 2, 2],
set_active=True,
layer="Player",
components_to_add=["AudioSource"],
components_to_remove=["OldComponent"],
component_properties={ # nested dict for property setting
"Rigidbody": {
"mass": 10.0,
"useGravity": True
}
}
)
# Delete
manage_gameobject(action="delete", target="OldObject")
# Duplicate
manage_gameobject(
action="duplicate",
target="Player",
new_name="Player2",
offset=[5, 0, 0] # position offset from original
)
# Move relative
manage_gameobject(
action="move_relative",
target="Player",
reference_object="Enemy", # optional reference
direction="left", # "left"|"right"|"up"|"down"|"forward"|"back"
distance=5.0,
world_space=True
)
# Look at target (rotates GO to face a point or another GO)
manage_gameobject(
action="look_at",
target="MainCamera", # the GO to rotate
look_at_target="Player", # str (GO name/path) or list[float] world position
look_at_up=[0, 1, 0] # optional up vector, default [0,1,0]
)
```
### manage_components
Add, remove, or set properties on components.
```python
# Add component
manage_components(
action="add",
target=12345, # instance ID (preferred) or name
component_type="Rigidbody",
search_method="by_id"
)
# Remove component
manage_components(
action="remove",
target="Player",
component_type="OldScript"
)
# Set single property
manage_components(
action="set_property",
target=12345,
component_type="Rigidbody",
property="mass",
value=5.0
)
# Set multiple properties
manage_components(
action="set_property",
target=12345,
component_type="Transform",
properties={
"position": [1, 2, 3],
"localScale": [2, 2, 2]
}
)
# Set object reference property (reference another GameObject by name)
manage_components(
action="set_property",
target="GameManager",
component_type="GameManagerScript",
property="targetObjects",
value=[{"name": "Flower_1"}, {"name": "Flower_2"}, {"name": "Bee_1"}]
)
# Object reference formats supported:
# - {"name": "ObjectName"} → Find GameObject in scene by name
# - {"instanceID": 12345} → Direct instance ID reference
# - {"guid": "abc123..."} → Asset GUID reference
# - {"path": "Assets/..."} → Asset path reference
# - "Assets/Prefabs/My.prefab" → String shorthand for asset paths
# - "ObjectName" → String shorthand for scene name lookup
# - 12345 → Integer shorthand for instanceID
```
---
## Script Tools
### create_script
Create a new C# script.
```python
create_script(
path="Assets/Scripts/MyScript.cs", # str, required
contents='''using UnityEngine;
public class MyScript : MonoBehaviour
{
void Start() { }
void Update() { }
}''',
script_type="MonoBehaviour", # optional hint
namespace="MyGame" # optional namespace
)
```
### script_apply_edits
Apply structured edits to C# scripts (safer than raw text edits).
```python
script_apply_edits(
name="MyScript", # script name (no .cs)
path="Assets/Scripts", # folder path
edits=[
# Replace entire method
{
"op": "replace_method",
"methodName": "Update",
"replacement": "void Update() { transform.Rotate(Vector3.up); }"
},
# Insert new method
{
"op": "insert_method",
"afterMethod": "Start",
"code": "void OnEnable() { Debug.Log(\"Enabled\"); }"
},
# Delete method
{
"op": "delete_method",
"methodName": "OldMethod"
},
# Anchor-based insert
{
"op": "anchor_insert",
"anchor": "void Start()",
"position": "before", # "before" | "after"
"text": "// Called before Start\n"
},
# Regex replace
{
"op": "regex_replace",
"pattern": "Debug\\.Log\\(",
"text": "Debug.LogWarning("
},
# Prepend/append to file
{"op": "prepend", "text": "// File header\n"},
{"op": "append", "text": "\n// File footer"}
]
)
```
### apply_text_edits
Apply precise character-position edits (1-indexed lines/columns).
```python
apply_text_edits(
uri="mcpforunity://path/Assets/Scripts/MyScript.cs",
edits=[
{
"startLine": 10,
"startCol": 5,
"endLine": 10,
"endCol": 20,
"newText": "replacement text"
}
],
precondition_sha256="abc123...", # optional, prevents stale edits
strict=True # optional, stricter validation
)
```
### validate_script
Check script for syntax/semantic errors.
```python
validate_script(
uri="mcpforunity://path/Assets/Scripts/MyScript.cs",
level="standard", # "basic" | "standard"
include_diagnostics=True # include full error details
)
```
### get_sha
Get file hash without content (for preconditions).
```python
get_sha(uri="mcpforunity://path/Assets/Scripts/MyScript.cs")
# Returns: {"sha256": "...", "lengthBytes": 1234, "lastModifiedUtc": "..."}
```
### delete_script
Delete a script file.
```python
delete_script(uri="mcpforunity://path/Assets/Scripts/OldScript.cs")
```
---
## Asset Tools
### manage_asset
Asset operations: search, import, create, modify, delete.
```python
# Search assets (paginated)
manage_asset(
action="search",
path="Assets", # search scope
search_pattern="*.prefab", # glob or "t:MonoScript" filter
filter_type="Prefab", # optional type filter
page_size=25, # keep small to avoid large payloads
page_number=1, # 1-based
generate_preview=False # avoid base64 bloat
)
# Get asset info
manage_asset(action="get_info", path="Assets/Prefabs/Player.prefab")
# Create asset
manage_asset(
action="create",
path="Assets/Materials/NewMaterial.mat",
asset_type="Material",
properties={"color": [1, 0, 0, 1]}
)
# Duplicate/move/rename
manage_asset(action="duplicate", path="Assets/A.prefab", destination="Assets/B.prefab")
manage_asset(action="move", path="Assets/A.prefab", destination="Assets/Prefabs/A.prefab")
manage_asset(action="rename", path="Assets/A.prefab", destination="Assets/B.prefab")
# Create folder
manage_asset(action="create_folder", path="Assets/NewFolder")
# Delete
manage_asset(action="delete", path="Assets/OldAsset.asset")
```
### manage_prefabs
Headless prefab operations.
```python
# Get prefab info
manage_prefabs(action="get_info", prefab_path="Assets/Prefabs/Player.prefab")
# Get prefab hierarchy
manage_prefabs(action="get_hierarchy", prefab_path="Assets/Prefabs/Player.prefab")
# Create prefab from scene GameObject
manage_prefabs(
action="create_from_gameobject",
target="Player", # GameObject in scene
prefab_path="Assets/Prefabs/Player.prefab",
allow_overwrite=False
)
# Modify prefab contents (headless)
manage_prefabs(
action="modify_contents",
prefab_path="Assets/Prefabs/Player.prefab",
target="ChildObject", # object within prefab
position=[0, 1, 0],
components_to_add=["AudioSource"]
)
```
---
## Material & Shader Tools
### manage_material
Create and modify materials.
```python
# Create material
manage_material(
action="create",
material_path="Assets/Materials/Red.mat",
shader="Standard",
properties={"_Color": [1, 0, 0, 1]}
)
# Get material info
manage_material(action="get_material_info", material_path="Assets/Materials/Red.mat")
# Set shader property
manage_material(
action="set_material_shader_property",
material_path="Assets/Materials/Red.mat",
property="_Metallic",
value=0.8
)
# Set color
manage_material(
action="set_material_color",
material_path="Assets/Materials/Red.mat",
property="_BaseColor",
color=[0, 1, 0, 1] # RGBA
)
# Assign to renderer
manage_material(
action="assign_material_to_renderer",
target="MyCube",
material_path="Assets/Materials/Red.mat",
slot=0 # material slot index
)
# Set renderer color directly
manage_material(
action="set_renderer_color",
target="MyCube",
color=[1, 0, 0, 1],
mode="create_unique" # Creates a unique .mat asset per object (persistent)
# Other modes: "property_block" (default, not persistent),
# "shared" (mutates shared material — avoid for primitives),
# "instance" (runtime only, not persistent)
)
```
### manage_texture
Create procedural textures.
```python
manage_texture(
action="create",
path="Assets/Textures/Checker.png",
width=64,
height=64,
fill_color=[255, 255, 255, 255] # or [1.0, 1.0, 1.0, 1.0]
)
# Apply pattern
manage_texture(
action="apply_pattern",
path="Assets/Textures/Checker.png",
pattern="checkerboard", # "checkerboard"|"stripes"|"dots"|"grid"|"brick"
palette=[[0,0,0,255], [255,255,255,255]],
pattern_size=8
)
# Apply gradient
manage_texture(
action="apply_gradient",
path="Assets/Textures/Gradient.png",
gradient_type="linear", # "linear"|"radial"
gradient_angle=45,
palette=[[255,0,0,255], [0,0,255,255]]
)
```
---
## UI Tools
### manage_ui
Manage Unity UI Toolkit elements: UXML documents, USS stylesheets, UIDocument components, and visual tree inspection.
```python
# Create a UXML file
manage_ui(
action="create",
path="Assets/UI/MainMenu.uxml",
contents='<ui:UXML xmlns:ui="UnityEngine.UIElements"><ui:Label text="Hello" /></ui:UXML>'
)
# Create a USS stylesheet
manage_ui(
action="create",
path="Assets/UI/Styles.uss",
contents=".title { font-size: 32px; color: white; }"
)
# Read a UXML/USS file
manage_ui(
action="read",
path="Assets/UI/MainMenu.uxml"
)
# Returns: {"success": true, "data": {"contents": "...", "path": "..."}}
# Update an existing file
manage_ui(
action="update",
path="Assets/UI/Styles.uss",
contents=".title { font-size: 48px; color: yellow; -unity-font-style: bold; }"
)
# Attach UIDocument to a GameObject
manage_ui(
action="attach_ui_document",
target="UICanvas", # GameObject name or path
source_asset="Assets/UI/MainMenu.uxml",
panel_settings="Assets/UI/Panel.asset", # optional, auto-creates if omitted
sort_order=0 # optional, default 0
)
# Create PanelSettings asset
manage_ui(
action="create_panel_settings",
path="Assets/UI/Panel.asset",
scale_mode="ScaleWithScreenSize", # optional: "ConstantPixelSize"|"ConstantPhysicalSize"|"ScaleWithScreenSize"
reference_resolution={"width": 1920, "height": 1080} # optional, for ScaleWithScreenSize
)
# Inspect the visual tree of a UIDocument
manage_ui(
action="get_visual_tree",
target="UICanvas", # GameObject with UIDocument
max_depth=10 # optional, default 10
)
# Returns: hierarchy of VisualElements with type, name, classes, styles, text, children
```
**UI Toolkit workflow:**
1. Create UXML (structure, like HTML) and USS (styling, like CSS) files
2. Create a PanelSettings asset (or let `attach_ui_document` auto-create one)
3. Create an empty GameObject and attach UIDocument with the UXML source
4. Use `get_visual_tree` to inspect the result
---
## Editor Control Tools
### manage_editor
Control Unity Editor state.
```python
manage_editor(action="play") # Enter play mode
manage_editor(action="pause") # Pause play mode
manage_editor(action="stop") # Exit play mode
manage_editor(action="set_active_tool", tool_name="Move") # Move/Rotate/Scale/etc.
manage_editor(action="add_tag", tag_name="Enemy")
manage_editor(action="remove_tag", tag_name="OldTag")
manage_editor(action="add_layer", layer_name="Projectiles")
manage_editor(action="remove_layer", layer_name="OldLayer")
```
### execute_menu_item
Execute any Unity menu item.
```python
execute_menu_item(menu_path="File/Save Project")
execute_menu_item(menu_path="GameObject/3D Object/Cube")
execute_menu_item(menu_path="Window/General/Console")
```
### read_console
Read or clear Unity console messages.
```python
# Get recent messages
read_console(
action="get",
types=["error", "warning", "log"], # or ["all"]
count=10, # max messages (ignored with paging)
filter_text="NullReference", # optional text filter
page_size=50,
cursor=0,
format="detailed", # "plain"|"detailed"|"json"
include_stacktrace=True
)
# Clear console
read_console(action="clear")
```
---
## Testing Tools
### run_tests
Start async test execution.
```python
result = run_tests(
mode="EditMode", # "EditMode"|"PlayMode"
test_names=["MyTests.TestA", "MyTests.TestB"], # specific tests
group_names=["Integration*"], # regex patterns
category_names=["Unit"], # NUnit categories
assembly_names=["Tests"], # assembly filter
include_failed_tests=True, # include failure details
include_details=False # include all test details
)
# Returns: {"job_id": "abc123", ...}
```
### get_test_job
Poll test job status.
```python
result = get_test_job(
job_id="abc123",
wait_timeout=60, # wait up to N seconds
include_failed_tests=True,
include_details=False
)
# Returns: {"status": "complete"|"running"|"failed", "results": {...}}
```
---
## Search Tools
### find_in_file
Search file contents with regex.
```python
find_in_file(
uri="mcpforunity://path/Assets/Scripts/MyScript.cs",
pattern="public void \\w+", # regex pattern
max_results=200,
ignore_case=True
)
# Returns: line numbers, content excerpts, match positions
```
---
## Custom Tools
### execute_custom_tool
Execute project-specific custom tools.
```python
execute_custom_tool(
tool_name="my_custom_tool",
parameters={"param1": "value", "param2": 42}
)
```
Discover available custom tools via `mcpforunity://custom-tools` resource.
