Layout Debug

What the Layout Debug MCP server does

Layout Debug MCP server connects a local inspection window to an MCP-compatible coding agent and a running UI. It supports two targets:

• Web pages served by a development server, including React, Vue, and plain HTML.
• Android apps running on a device or emulator through adb, including Jetpack Compose and Compose Multiplatform interfaces.

The window lets you hover and select layers, move between parent and child elements, and inspect wrappers or containers that may not have accessibility metadata. Each selected element has its own chat thread. A request includes the user’s text along with information such as the element’s box, parent chain, siblings, text, classes, IDs, test IDs, and available source location.

For layout experiments, the Layout Debug MCP server applies live changes before code is edited. Dragging an element produces a measured offset, while resizing or hiding an element creates a corresponding temporary override. Web changes use inline styles; Android changes apply to the running composition. When the agent responds, the window refreshes the frame and restores the current selection and other live edits.

How it works

The agent starts the local window by calling open_window. The developer then selects an element, optionally drags or resizes it, types a request, and submits it. The request reaches the agent through wait_for_message as plain text with the captured UI context and measured changes. After making or considering a code change, the agent uses reply_in_window with a response and a completion or error status, then continues listening.

The tool sends facts rather than prescribing an implementation. For example, an offset may indicate that an element moved 16 CSS pixels or density-independent pixels, but the agent decides whether the source code should use a margin, a different flex arrangement, reordered children, or another change. On the web, source locations are available when the build supplies data-source-loc; otherwise, the agent can use other anchors such as test IDs, IDs, and class strings. Android source locations come from the Compose compiler.

Setup and configuration

Node.js 22.12 or newer is supported, and Node.js 20.19 or newer also works. Install the server in an MCP client with the equivalent of:

{ "command": "npx", "args": ["-y", "layout-debug-mcp"] }

Claude Code can add it with claude mcp add --transport stdio --scope user layout-debug -- npx -y layout-debug-mcp. The README also provides installation links for Cursor and VS Code. To preview the interface without an agent or project, run npx -y layout-debug-mcp window; this opens the bundled demo page, or a configured target URL when one is set.

A browser such as Chrome, Edge, Firefox, or another current browser is required for the window. Android inspection additionally requires adb on PATH, a debug build, and the project’s on-device agent setup.

Tools and capabilities

The Layout Debug MCP server provides:

• Element selection with hover highlighting, breadcrumbs, and child details.
• Per-element conversations with the connected MCP agent.
• Live movement, resizing, hiding, and showing of UI layers.
• Layout context including boxes, anchors, hierarchy, siblings, and source locations when available.
• An inbox showing queued, active, completed, and failed requests.
• Automatic frame refresh after an agent response.
• English and Russian interface options.

Limitations and notes

The server runs locally, including its window, server, and MCP process. The README states that it does not use a cloud service, while anonymous usage counts may leave the machine unless disabled through the project’s telemetry setting. Screenshots and layout trees are sent to the connected agent, so the tool should not inspect screens containing information that should not be provided to that agent.

The server reports measurements in CSS pixels for web targets and density-independent pixels for Android targets. Live changes are temporary inspection overrides; the agent still needs to determine and edit the project’s source code. Web source locations are not automatic unless the build adds the supported source-location attribute.