unity-mcp/unity-mcp-skill/references/resources-reference.md

Unity-MCP Resources Reference

Resources provide read-only access to Unity state. Use resources to inspect before using tools to modify.

Table of Contents

• Editor State Resources
• Scene & GameObject Resources
• Prefab Resources
• Project Resources
• Instance Resources
• Test Resources

---

URI Scheme

All resources use mcpforunity:// scheme:

mcpforunity://{category}/{resource_path}[?query_params]

Categories: editor, scene, prefab, project, menu-items, custom-tools, tests, instances

---

Editor State Resources

mcpforunity://editor/state

Purpose: Editor readiness snapshot - check before tool operations.

Returns:

{
  "unity_version": "2022.3.10f1",
  "is_compiling": false,
  "is_domain_reload_pending": false,
  "play_mode": {
    "is_playing": false,
    "is_paused": false
  },
  "active_scene": {
    "path": "Assets/Scenes/Main.unity",
    "name": "Main"
  },
  "ready_for_tools": true,
  "blocking_reasons": [],
  "recommended_retry_after_ms": null,
  "staleness": {
    "age_ms": 150,
    "is_stale": false
  }
}

Key Fields:

• ready_for_tools: Only proceed if true
• is_compiling: Wait if true
• blocking_reasons: Array explaining why tools might fail
• recommended_retry_after_ms: Suggested wait time

mcpforunity://editor/selection

Purpose: Currently selected objects.

Returns:

{
  "activeObject": "Player",
  "activeGameObject": "Player",
  "activeInstanceID": 12345,
  "count": 3,
  "gameObjects": ["Player", "Enemy", "Wall"],
  "assetGUIDs": []
}

mcpforunity://editor/active-tool

Purpose: Current editor tool state.

Returns:

{
  "activeTool": "Move",
  "isCustom": false,
  "pivotMode": "Center",
  "pivotRotation": "Global"
}

mcpforunity://editor/windows

Purpose: All open editor windows.

Returns:

{
  "windows": [
    {
      "title": "Scene",
      "typeName": "UnityEditor.SceneView",
      "isFocused": true,
      "position": {"x": 0, "y": 0, "width": 800, "height": 600}
    }
  ]
}

mcpforunity://editor/prefab-stage

Purpose: Current prefab editing context.

Returns:

{
  "isOpen": true,
  "assetPath": "Assets/Prefabs/Player.prefab",
  "prefabRootName": "Player",
  "isDirty": false
}

---

Scene & GameObject Resources

mcpforunity://scene/gameobject-api

Purpose: Documentation for GameObject resources (read this first).

mcpforunity://scene/gameobject/{instance_id}

Purpose: Basic GameObject data (metadata, no component properties).

Parameters:

• instance_id (int): GameObject instance ID from find_gameobjects

Returns:

{
  "instanceID": 12345,
  "name": "Player",
  "tag": "Player",
  "layer": 8,
  "layerName": "Player",
  "active": true,
  "activeInHierarchy": true,
  "isStatic": false,
  "transform": {
    "position": [0, 1, 0],
    "rotation": [0, 0, 0],
    "scale": [1, 1, 1]
  },
  "parent": {"instanceID": 0},
  "children": [{"instanceID": 67890}],
  "componentTypes": ["Transform", "Rigidbody", "PlayerController"],
  "path": "/Player"
}

mcpforunity://scene/gameobject/{instance_id}/components

Purpose: All components with full property serialization (paginated).

Parameters:

• instance_id (int): GameObject instance ID
• page_size (int): Default 25, max 100
• cursor (int): Pagination cursor
• include_properties (bool): Default true, set false for just types

Returns:

{
  "gameObjectID": 12345,
  "gameObjectName": "Player",
  "components": [
    {
      "type": "Transform",
      "properties": {
        "position": {"x": 0, "y": 1, "z": 0},
        "rotation": {"x": 0, "y": 0, "z": 0, "w": 1}
      }
    },
    {
      "type": "Rigidbody",
      "properties": {
        "mass": 1.0,
        "useGravity": true
      }
    }
  ],
  "cursor": 0,
  "pageSize": 25,
  "nextCursor": null,
  "hasMore": false
}

mcpforunity://scene/gameobject/{instance_id}/component/{component_name}

Purpose: Single component with full properties.

Parameters:

• instance_id (int): GameObject instance ID
• component_name (string): e.g., "Rigidbody", "Camera", "Transform"

Returns:

{
  "gameObjectID": 12345,
  "gameObjectName": "Player",
  "component": {
    "type": "Rigidbody",
    "properties": {
      "mass": 1.0,
      "drag": 0,
      "angularDrag": 0.05,
      "useGravity": true,
      "isKinematic": false
    }
  }
}

---

Prefab Resources

mcpforunity://prefab-api

Purpose: Documentation for prefab resources.

mcpforunity://prefab/{encoded_path}

Purpose: Prefab asset information.

Parameters:

• encoded_path (string): URL-encoded path, e.g., Assets%2FPrefabs%2FPlayer.prefab

Path Encoding:

Assets/Prefabs/Player.prefab → Assets%2FPrefabs%2FPlayer.prefab

Returns:

{
  "assetPath": "Assets/Prefabs/Player.prefab",
  "guid": "abc123...",
  "prefabType": "Regular",
  "rootObjectName": "Player",
  "rootComponentTypes": ["Transform", "PlayerController"],
  "childCount": 5,
  "isVariant": false,
  "parentPrefab": null
}

mcpforunity://prefab/{encoded_path}/hierarchy

Purpose: Full prefab hierarchy with nested prefab info.

Returns:

{
  "prefabPath": "Assets/Prefabs/Player.prefab",
  "total": 6,
  "items": [
    {
      "name": "Player",
      "instanceId": 12345,
      "path": "/Player",
      "activeSelf": true,
      "childCount": 2,
      "componentTypes": ["Transform", "PlayerController"]
    },
    {
      "name": "Model",
      "path": "/Player/Model",
      "isNestedPrefab": true,
      "nestedPrefabPath": "Assets/Prefabs/PlayerModel.prefab"
    }
  ]
}

---

Project Resources

mcpforunity://project/info

Purpose: Static project configuration.

Returns:

{
  "projectRoot": "/Users/dev/MyProject",
  "projectName": "MyProject",
  "unityVersion": "2022.3.10f1",
  "platform": "StandaloneWindows64",
  "assetsPath": "/Users/dev/MyProject/Assets"
}

mcpforunity://project/tags

Purpose: All tags defined in TagManager.

Returns:

["Untagged", "Respawn", "Finish", "EditorOnly", "MainCamera", "Player", "GameController", "Enemy"]

mcpforunity://project/layers

Purpose: All layers with indices (0-31).

Returns:

{
  "0": "Default",
  "1": "TransparentFX",
  "2": "Ignore Raycast",
  "4": "Water",
  "5": "UI",
  "8": "Player",
  "9": "Enemy"
}

mcpforunity://menu-items

Purpose: All available Unity menu items.

Returns:

[
  "File/New Scene",
  "File/Open Scene",
  "File/Save",
  "Edit/Undo",
  "Edit/Redo",
  "GameObject/Create Empty",
  "GameObject/3D Object/Cube",
  "Window/General/Console"
]

mcpforunity://custom-tools

Purpose: Custom tools available in the active Unity project.

Returns:

{
  "project_id": "MyProject",
  "tool_count": 3,
  "tools": [
    {
      "name": "capture_screenshot",
      "description": "Capture screenshots in Unity",
      "parameters": [
        {"name": "filename", "type": "string", "required": true},
        {"name": "width", "type": "int", "required": false},
        {"name": "height", "type": "int", "required": false}
      ]
    }
  ]
}

---

Instance Resources

mcpforunity://instances

Purpose: All running Unity Editor instances (for multi-instance workflows).

Returns:

{
  "transport": "http",
  "instance_count": 2,
  "instances": [
    {
      "id": "MyProject@abc123",
      "name": "MyProject",
      "hash": "abc123",
      "unity_version": "2022.3.10f1",
      "connected_at": "2024-01-15T10:30:00Z"
    },
    {
      "id": "TestProject@def456",
      "name": "TestProject",
      "hash": "def456",
      "unity_version": "2022.3.10f1",
      "connected_at": "2024-01-15T11:00:00Z"
    }
  ],
  "warnings": []
}

Use with: set_active_instance(instance="MyProject@abc123")

---

Test Resources

mcpforunity://tests

Purpose: All tests in the project.

Returns:

[
  {
    "name": "TestSomething",
    "full_name": "MyTests.TestSomething",
    "mode": "EditMode"
  },
  {
    "name": "TestOther",
    "full_name": "MyTests.TestOther",
    "mode": "PlayMode"
  }
]

mcpforunity://tests/{mode}

Purpose: Tests filtered by mode.

Parameters:

• mode (string): "EditMode" or "PlayMode"

Example: mcpforunity://tests/EditMode

---

Best Practices

1. Check Editor State First

# Before any complex operation:
# Read mcpforunity://editor/state
# Check ready_for_tools == true

2. Use Find Then Read Pattern

# 1. find_gameobjects to get IDs
result = find_gameobjects(search_term="Player")

# 2. Read resource for full data
# mcpforunity://scene/gameobject/{id}

3. Paginate Large Queries

# Start with include_properties=false for component lists
# mcpforunity://scene/gameobject/{id}/components?include_properties=false&page_size=25

# Then read specific components as needed
# mcpforunity://scene/gameobject/{id}/component/Rigidbody

4. URL-Encode Prefab Paths

# Wrong:
# mcpforunity://prefab/Assets/Prefabs/Player.prefab

# Correct:
# mcpforunity://prefab/Assets%2FPrefabs%2FPlayer.prefab

5. Multi-Instance Awareness

# Always check mcpforunity://instances when:
# - First connecting
# - Commands fail unexpectedly
# - Working with multiple projects