Squint MCP: Catch Visual Bugs by Checking Pixels Against DOM and CSS

What is Squint?

It is an MCP server that examines a rendered web page by crossing what the browser reports in its DOM and CSS with what is actually painted on screen, and reports the visual problems it finds without needing a baseline to compare against.

It is built for coding agents that have just produced a UI and need to know whether the page actually looks right: which element is broken, and what the evidence is. It drives a real Chromium browser through Playwright.

What changes in an agent's output

• ping confirms the connection and returns the server name and version before anything else runs.
• inspect_element returns one element's computed styles, box model, sampled colors and a crop, so a single suspect element can be checked directly.
• detect_visual_bugs runs five checks across one or more viewports and returns findings ordered by severity, with crops as evidence.
• extract_tokens reads the colors, typography, spacing, radii and shadows a page actually uses, grouped into families with how many elements use each one.

The five visual bug checks

• text-clipped: text cut off by its own box.
• low-contrast-real: text contrast against the background sampled from the painted pixels, below WCAG 2.2 SC 1.4.3, so it is correct even over images and gradients.
• offscreen-overflow: the element making the page scroll horizontally.
• overlap: text another element is painted over, with how much is hidden and which element covers it.
• font-fallback: a declared web font that did not load, with how many elements render in a fallback font instead.

How the setup works

1. Install uv first; it installs Python 3.12 for you if it is missing.
2. Run uvx --from squint-mcp playwright install chromium to fetch the exact Chromium build Squint's Playwright expects.
3. Run uvx squint-mcp to start the server, or register it directly in your MCP client's config.
4. Call ping once connected to confirm the server responds before running a check.

Who Squint is for

Best for

• Checking UI an agent just produced for clipped text, overlap, real contrast failures and font fallback, with evidence crops attached.
• Pulling the colors, type and spacing a rendered page actually uses, without reading the underlying source.

Not for

• Measuring a built page against an existing reference page's own layout contract property by property, a check pixelpact MCP Server runs instead of a baseline-free scan.
• Running a live mobile or desktop session to return contrast, touch target and overflow findings as plain text, a job uisight MCP Server already does for an exact selector fix.
• Comparing a rendered page against its own Figma frame using tokens and geometry rather than painted pixels, which Designfit MCP already covers with its own fix list.
• Taking a screenshot of a running site at several widths and fixing layout issues directly in source code, work Web Design Reviewer Skill takes on beyond flagging a bug.

Requirements

• Needs uv, which installs Python 3.12 automatically if it is missing.
• Needs Playwright's Chromium build, installed with uvx --from squint-mcp playwright install chromium; on Linux, add --with-deps for the system libraries Chromium needs.
• The server speaks MCP over stdio and waits for a client; started by hand it just sits idle.

Connect Squint MCP: Catch Visual Bugs by Checking Pixels Against DOM and CSS to your AI client

uvx --from squint-mcp playwright install chromium
uvx squint-mcp

1. Install uv

   Squint requires uv. It installs Python 3.12 on its own if that is missing, so no separate Python setup is needed first.

2. Install the matching Chromium build

   Run uvx --from squint-mcp playwright install chromium so the Chromium downloaded is the exact one Squint's Playwright dependency expects. uv's warning that playwright comes from a dependency is expected. On Linux, add --with-deps to also install the system libraries Chromium needs.

3. Start or register the server

   Run uvx squint-mcp to start it by hand, where it waits silently for a client over stdio, or add the config above to your MCP client directly.

4. Register it in Claude Code

   Run claude mcp add squint -- uvx squint-mcp.

5. Confirm the connection

   Call ping once the server is registered; it returns the server name, version and the message you sent.

Client configuration

{"mcpServers": {"squint": {"command": "uvx", "args": ["squint-mcp"]}}}

What you can do with it

• No baseline neededCrosses what the browser reports in DOM and CSS with what is actually painted, so a visual bug is found without comparing against a prior screenshot.
• Five visual bug checkstext-clipped, low-contrast-real, offscreen-overflow, overlap and font-fallback, each returned with severity and evidence.
• Contrast measured on real pixelslow-contrast-real samples the painted background instead of reading computed styles, so it is correct over images and gradients, checked against WCAG 2.2 SC 1.4.3.
• Single element inspectioninspect_element returns one element's computed styles, box model, sampled colors and a crop, for checking one suspect element directly.
• Design token extractionextract_tokens returns colors, typography, spacing, radii and shadows grouped into eight families, each value with how many elements use it.
• Shadow DOM aware scopingextract_tokens's scope selector reaches into open shadow roots, narrowing the reading to its matches and everything under them.
• Multi-viewport checksdetect_visual_bugs can run across several viewports in one call, with stabilization and crops reported per viewport.
• Built on PlaywrightDrives a real Chromium browser through Playwright rather than a headless rendering approximation, requiring Playwright's own Chromium build to be installed first.

Tools it exposes

Frequently asked questions