image-diff — Claude Code MCP server: pixel diff and visual comparison
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.
claude mcp add image-diff -- npx -y @pulsemcp/image-diff-mcp-serverWhat image-diff 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.
What it helps with
- 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 for the agent
- Compare
design/home.pngwithshots/home-actual.pngand list the regions that differ - Diff
mock.pngagainstbuild.pngat threshold 0.05 and show me the clusters - Generate a heatmap of the differences between these two screenshots
How to install image-diff
Platform CLI
claude mcp add image-diff -- npx -y @pulsemcp/image-diff-mcp-serverPlatform CLI
codex mcp add image-diff -- npx -y @pulsemcp/image-diff-mcp-serverConfig file
{
"mcpServers": {
"image-diff": {
"command": "npx",
"args": [
"-y",
"@pulsemcp/image-diff-mcp-server"
]
}
}
}Config file
{
"servers": {
"image-diff": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@pulsemcp/image-diff-mcp-server"
]
}
}
}Platform CLI
gemini mcp add image-diff npx -y @pulsemcp/image-diff-mcp-serverStep by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about image-diff
How do I install image-diff in Claude Code?
Run claude mcp add image-diff -- npx -y @pulsemcp/image-diff-mcp-server. That registers the server with Claude and launches it through npx.
What does image-diff do?
It diffs two images at pixel level, groups the differing spots into spatial clusters with severity ratings, and writes a heatmap plus a composite over the reference image.
Which image formats are supported?
PNG, JPEG, WebP and TIFF, addressed by local absolute paths. Dimensions may differ: the smaller image is aligned inside the larger using OpenCV ZNCC.
