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"
]

MCP tools

Tool	Purpose
ui_list_projects	List open Unity projects that have the package installed
ui_select_project	Select the Unity project to work with
ui_status	Check the Unity version and connection status
ui_list_targets	List preview configurations, UXML files, and open EditorWindow instances
ui_inspect	Inspect the structure, position, size, and styles of UI elements
ui_screenshot	Capture the UI as a PNG image
ui_reload	Reload UXML/USS changes in Unity

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": { "width": 480, "height": "full" }
    }
  ]
}

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.

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.

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.