Percy MCP. Pinpoint pixel-level UI breaks across all browsers.

This MCP server connects your agent directly to Percy's Visual Testing API. You use it to programmatically verify that your UI hasn't gone sideways—or worse, broken visually—when new code gets merged. It tracks pixel differences (diffs) against an approved baseline for specific components across multiple browsers and viewports. This lets you check if a component broke after a change, approve snapshots, or inspect the status of any build using your AI client.

Discovering Your Projects and Setup

You can start by listing all projects managed by Percy using list_projects. This tool returns names, slugs, and tells you what browser settings are configured for each project. To get specific info on a single setup, call get_project_details; it gives you the core name, default branch, and whether auto-approval is even turned on.

You can also check which browsers Percy supports at all times by running list_browsers, which returns every browser family and OS combination available for cross-browser testing.

Tracking Builds Over Time

To see what's been happening with your code, you use list_builds. This shows a list of builds associated with the project, giving you build IDs, their current state (like 'processing' or 'failed'), and how many snapshots were generated. When you need the full lowdown on one specific attempt, get_build_details retrieves that information.

It gives you the complete status—whether it passed or failed—the total number of snapshots included in that build, and the commit SHA used for the run.

Inspecting Snapshot Details and Comparisons

When a build runs, it creates snapshots. You can view all those available snapshots using list_snapshots, which shows their review state (if they're 'unreviewed' or already 'approved') alongside their difference percentages. For deep metrics on one specific snapshot, you call get_snapshot_details. This gives you the review status, component widths, and how many comparisons were run against the baseline.

If you suspect a visual issue, running list_comparisons shows all the individual visual checks for that snapshot, including actual diff images, precise percentage differences, and which browser generated the comparison.

Controlling the Baseline (Approving Changes)

If everything looks good visually, you need to update your baseline. You can mark a single snapshot as correct by calling approve_snapshot. This action tells Percy that the detected visual state is right for future comparisons and updates the official baseline. If you're confident in the entire build—meaning all components look fine together—you use approve_build to approve all unreviewed snapshots at once, marking the whole build as visually cleared for deployment.

How It All Works Together

You can see a list of builds using list_builds, then pull the full status with get_build_details. If you spot something weird, you check list_snapshots to see which ones are unreviewed. You dive into those suspicious snapshots by running get_snapshot_details and checking out every single comparison via list_comparisons to pinpoint exactly what broke—whether it's a color shift or a layout collapse.

Once you verify the fix, you run approve_snapshot for that component or approve_build if the whole system is good to go.