UI Toolkit MCP

An MCP server that lets AI agents inspect UI Toolkit screens while the Unity Editor remains open. It can examine the structure and appearance of UXML/USS files and capture screenshots without entering Play Mode or building a Player.

Key features:

• List UXML files and open UI Toolkit windows

• Inspect element trees, text, values, positions, sizes, and resolved styles

• Capture an entire screen or a selected element as a PNG image

• Automatically split long screens into tiles (up to 8192 px per image and 100 MP in total)

• Reimport UXML/USS files

• Compatibility tested with Unity 2022.3 LTS and Unity 6.3

Setup

1. Add the Unity package

In the Unity Editor, open Window > Package Manager, click the + button in the upper-left corner, and select Add package from git URL....

Enter the following URL:

https://github.com/adzukyat/ui-toolkit-mcp.git?path=/unity-package

The preview server starts automatically after Unity finishes script compilation. Keep the Unity Editor open while using it.

2. Register the MCP server

Node.js 20 or later is required. Example configuration for Codex:

[mcp_servers.ui_toolkit_mcp]
command = "npx"
args = [
  "-y",
  "ui-toolkit-mcp-server@latest",
  "mcp"
]

Related MCP server: Unity MCP Server

MCP tools

Start with ui_list_projects to find a project, then select it with ui_select_project. Next, use ui_list_targets to find the screen you want to inspect, followed by ui_inspect or ui_screenshot.

Preview configuration (optional)

Place a .ui-toolkit-mcp-preview.json file in the project root to define stable aliases, additional USS files, themes, and viewports. Copy and adapt the following example:

{
  "$schema": "./Packages/me.adzuki.ui-toolkit-mcp.preview-server/Schemas/ui-toolkit-mcp-preview.schema.json",
  "schemaVersion": 1,
  "previews": [
    {
      "alias": "settings",
      "document": "Assets/UI/Settings.uxml",
      "stylesheets": ["Assets/UI/Settings.uss"],
      "theme": "editor-dark",
      "selector": "#settings-root",
      "viewport": { "width": 480, "height": "full" }
    }
  ]
}

Supported themes are editor-dark, editor-light, and runtime. A panelSettings asset path can also be specified for the runtime theme.

Development and verification

npm test
npm run typecheck
npm run build
node scripts/mcp-smoke.mjs [project-id]

Unity EditMode tests are located in test-projects/2022.3 and test-projects/6000.3. Pixel-accurate verification requires a graphics device. Tree inspection works with -nographics, but PNG rendering does not, so perform final verification in a normally launched Unity Editor.

Current limitations

• The server primarily targets static UI states. For screens constructed later in C#, open the actual EditorWindow or prepare the required state in a preview UXML file.

• The Editor offscreen renderer calls internal UI Toolkit APIs through reflection. ui_status reports a warning for unsupported Unity versions.

• Open-window IDs are valid only for the current Unity session.

• Pseudo-state injection such as hover and focus, pointer/keyboard interaction, and fixed animation time are not yet supported.

• Fonts, icons, custom controls, and data bindings are rendered only when they can be resolved in the target project.