Playwright Spatial Layout MCP

What playwright-spatial-layout-mcp does

playwright-spatial-layout-mcp MCP server gives an AI agent measurements from the rendered page rather than relying only on DOM structure or accessibility information. It opens a supplied URL with Playwright and reports spatial facts about selected elements, including their coordinates, dimensions, viewport status, and z-index.

This is useful for diagnosing layout problems that can make an otherwise present element difficult or impossible to use. Examples include a call-to-action below the mobile viewport, a cookie banner covering a checkout control, navigation colliding with a hero section, or an element moving after a CSS change.

How it works

Each tool request supplies a URL and the selectors or layout rules to inspect. Some requests also provide a viewport size or a list of viewport sizes. Playwright renders the page at those dimensions, reads the resulting element geometry, and returns structured results for the agent.

The server compares bounding rectangles to calculate physical intersections. It can also compare element positions and sizes between several viewport configurations, making it possible to identify responsive changes such as horizontal or vertical movement and width or height changes.

Tools and capabilities

The available tools are:

• extract_bounding_boxes: Returns the position, size, z-index, visibility, and viewport presence of one or more selected elements.
• detect_visual_occlusion: Checks two selected elements for physical overlap and reports whether occlusion exists, along with the intersection ratio and covered area in pixels.
• verify_spatial_relationships: Evaluates rules describing whether one element is left, right, above, or below another, whether one contains another, or whether two elements do not overlap. Each rule receives a pass/fail result and a human-readable reason.
• compute_viewport_reflow: Compares selected elements across multiple viewport sizes and reports whether they shifted, including maximum changes in x position, y position, width, and height.

The playwright-spatial-layout-mcp MCP server fits browser-layout checks, responsive UI investigation, and analysis of Playwright test failures where rendered geometry is relevant.

Setup and configuration

Run the package directly with:

npx playwright-spatial-layout-mcp

A global npm installation is also supported:

npm install -g playwright-spatial-layout-mcp
npx playwright install chromium

The documented Claude Desktop configuration starts the server through npx, passing the package name as its argument:

{
  "mcpServers": {
    "playwright-spatial-layout-mcp": {
      "command": "npx",
      "args": ["-y", "playwright-spatial-layout-mcp"]
    }
  }
}

Chromium must be installed when using the global-install path shown above. Requests identify the page with a URL and use CSS selectors for the elements under inspection.

Limitations and notes

The server reports geometry from the rendered page at the requested viewport sizes. It does not replace DOM or accessibility inspection; its purpose is to add spatial information that those representations may not expose. Results depend on the page state produced when Playwright loads the URL, including the layout at the selected viewport.

The documented relationship checks are limited to left_of, right_of, above, below, contains, and not_overlapping.