android-layout-inspector-mcp

Spatial inspection of a live Android UI for AI agents. Pulls the real view hierarchy off a device or emulator over adb + uiautomator, and reports layout problems as measured geometry — overlap area in px², touch targets in dp, clipped fractions — not as an opinion about a screenshot.

The Android counterpart of layout-inspector-mcp, which does the same job for web pages via Playwright.

Why

An agent that changes a layout has no way to know whether the result overlaps, clips, or leaves a control too small to tap. Screenshots are the obvious answer and the wrong one: judging a 4px collision by looking at pixels is guesswork, and legitimate overlays get reported as bugs.

This measures instead. Every node's bounds, cross-referenced for intersections, with the overlap area in px² and touch targets converted to dp against the device's real density. Deterministic and reproducible: it tells you which two nodes collide, not "something looks off". Use a screenshot afterwards to confirm a finding looks wrong to a human, not to find it.

No Android Studio required.

Related MCP server: Android Mobile MCP

Requirements

• Python 3.11+

• uv — used by the plugin launch path

• adb on PATH, or ADB_PATH, or ANDROID_HOME pointing at an SDK that contains platform-tools/adb

• A device with USB debugging on, or a running emulator

Install as a plugin

claude plugin install android-layout-inspector --marketplace Rixmerz/claude-plugins

Install as a plain MCP server

git clone https://github.com/Rixmerz/android-layout-inspector-mcp.git
cd android-layout-inspector-mcp
uv sync
claude mcp add android-layout-inspector -- uv run --project "$PWD" android-layout-inspector-mcp

Tools

Every analysis tool accepts xml_path instead of a device, so a saved uiautomator dump can be analysed in CI with no hardware attached.

What it detects

Jetpack Compose: the one thing you must do

By default a Compose screen collapses into a handful of anonymous android.view.View nodes. The geometry is real, but nothing can be selected by id, which makes every finding much harder to act on. Add this to your root composable:

@OptIn(ExperimentalComposeUiApi::class)
Surface(
    modifier = Modifier
        .fillMaxSize()
        .semantics { testTagsAsResourceId = true }
) { /* ... */ }

Then every Modifier.testTag("boton_sumar") shows up as resource-id="boton_sumar". detect_issues raises compose_not_inspectable when it sees a Compose tree that skipped this.

What this deliberately does not do

Three things are measurable on the web and are not recoverable from a uiautomator dump. They are left out rather than approximated:

Text truncation. uiautomator reports the full string even when the view ellipsized it — verified on both a classic TextView with android:ellipsize="end" and a Compose Text with TextOverflow.Ellipsis. There is no signal in the dump, so no check pretends to find one.

Fully off-screen nodes on a live device. Android drops them from the hierarchy before uiautomator ever sees them. The offscreen check still fires on saved dumps and on partially clipped nodes, which is the case that actually reaches the dump.

Real occlusion by opacity. Draw order and containment are known; alpha and elevation are not. occluded_interactive requires full geometric containment by a later sibling, which is conservative on purpose.

One more caveat worth knowing: Compose already expands every clickable to 48dp for accessibility, so small_touch_target mostly catches classic View layouts and code that overrides LocalMinimumInteractiveComponentSize.

Verified

uv run pytest — unit checks on crafted hierarchies plus a fixture captured from a real emulator.

End to end against a Pixel 8 AVD (API 36, 1080x2400 @ 420dpi): overlap (15211px², 74% of the smaller node), unlabeled_interactive on two Compose buttons, small_touch_target on a 24x24dp Button in a classic View layout, and compare_orientations correctly reading 1080x2400 in portrait and 2400x1080 in landscape.

License

MIT