# image-diff

Compares two images pixel by pixel, groups the differences into clusters and renders a heatmap. Handy for checking a UI screenshot against its design mock.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 81
- Author: pulsemcp
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/pulsemcp/mcp-servers/tree/HEAD/productionized/image-diff
- Updated: 2026-10-09
- HTML: https://affpapa.org/en/nevibecode/mcp/image-diff

## What it does

One tool, `get_diff_of_images`. You pass two absolute file paths and get back JSON: whether the images match, how many pixels diverged, each differing region with its box and severity, plus paths to a heatmap and to the heatmap laid over the reference.

Colour distance is measured with the YIQ NTSC metric, which follows how people actually see colour. Anti-aliased pixels from font smoothing and rounded corners get filtered so they do not inflate the result. Adjacent diff pixels form connected clusters. Leave `cluster_gap` unset and the server picks the gap itself by nearest-neighbour analysis; set it to 0 to disable merging. When the two files have different dimensions, the smaller one is positioned inside the larger with OpenCV ZNCC.

Default `threshold` is 0.1, and anti-aliasing does not count as a difference unless you flip `include_aa`. Input can be PNG, JPEG, WebP or TIFF, and only local paths work. Alignment of differently sized images depends on OpenCV, so that step fails in an environment without it.

## Requirements
- Needs: Node.js (commands run via npx)

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add image-diff -- npx -y @pulsemcp/image-diff-mcp-server
```

### Codex

**Platform CLI**
```bash
codex mcp add image-diff -- npx -y @pulsemcp/image-diff-mcp-server
```

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "image-diff": {
            "command": "npx",
            "args": [
                "-y",
                "@pulsemcp/image-diff-mcp-server"
            ]
        }
    }
}
```

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "image-diff": {
            "type": "stdio",
            "command": "npx",
            "args": [
                "-y",
                "@pulsemcp/image-diff-mcp-server"
            ]
        }
    }
}
```

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add image-diff npx -y @pulsemcp/image-diff-mcp-server
```

## When to use it
- check a finished screen against the design mock
- locate which part of the layout drifted
- produce a heatmap of differences for a report
- drop false positives caused by font smoothing
- compare screenshots of different resolutions with automatic alignment

## Example prompts
- Compare `design/home.png` with `shots/home-actual.png` and list the regions that differ
- Diff `mock.png` against `build.png` at threshold 0.05 and show me the clusters
- Generate a heatmap of the differences between these two screenshots

## Similar
- [Front-End Checklist](https://affpapa.org/en/nevibecode/mcp/front-end-checklist.md) — MCP server · ★ 74559
- [Keploy](https://affpapa.org/en/nevibecode/mcp/keploy.md) — MCP server · ★ 18727
- [SeleniumBase MCP](https://affpapa.org/en/nevibecode/mcp/seleniumbase-mcp.md) — MCP server · ★ 13169
- [mobile-mcp](https://affpapa.org/en/nevibecode/mcp/mobile-mcp.md) — MCP server · ★ 9946
- [e2e](https://affpapa.org/en/nevibecode/mcp/e2e.md) — MCP server · ★ 11912
- [mockserver](https://affpapa.org/en/nevibecode/mcp/mockserver.md) — MCP server · ★ 4996

From the same set: [pulsemcp/mcp-servers](https://affpapa.org/en/nevibecode/by/pulsemcp/mcp-servers.md) — 9 cards

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md