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

• Report elements that extend beyond their parent or the preview area

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

• Capture several widths in one request

• 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",
      "background": "#383838",
      "selector": "#settings-root",
      "viewport": { "widths": [360, 480], "height": "full" },
      "state": {
        "#advanced-toggle": { "value": true },
        "#advanced-fields": { "display": true },
        "#mode-custom": { "addClasses": ["selected"] },
        "#name": { "value": "Example" }
      }
    }
  ]
}

Supported themes are editor-dark, editor-light, and runtime. background accepts theme, #RRGGBB, or #RRGGBBAA. A panelSettings asset path can also be specified for the runtime theme.

Use viewport.width for one width or viewport.widths for several. state is keyed by element selector. Each element can set value, selectedIndex, text, display, visible, enabled, addClasses, and removeClasses. Existing configurations do not need changes.

ui_inspect returns overflows with the element and parent bounds, plus the amount outside each edge. ui_screenshot also accepts one width or an array such as [360, 768, 1280].

Screenshots use the selected theme's standard canvas color by default (#383838 for Editor Dark and #C8C8C8 for Editor Light). Pass #00000000 as background when a transparent PNG is required. Runtime previews remain transparent unless the UI itself paints a background.

When C# fills the screen

A UXML target loads the UXML and USS only. It does not call an EditorWindow's CreateGUI or other setup code. The target list marks these entries as uxml-only; open windows are marked as live.

If C# adds icons, text, or child elements, use either the open window target or a parent UXML that creates the custom control. Use state for values and visual states that do not require C# to create new elements.

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 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.