Image Diff

image-diff MCP Server

A Model Context Protocol (MCP) server for programmatic image comparison and visual diff generation. Compares two images pixel-by-pixel, identifies clusters of visual differences, and generates heatmap visualizations.

Designed for comparing design mock screenshots against actual UI implementations.

How It Works

1. Pixel comparison using YIQ NTSC perceptual color distance (accounts for how humans perceive color differences)
2. Anti-aliasing detection to filter out false positives from font smoothing and rounded corners
3. Connected Component Labeling to group adjacent diff pixels into spatial clusters
4. Natural-breaks clustering to auto-compute an optimal cluster_gap using nearest-neighbor distance analysis, merging nearby clusters into meaningful groups
5. Heatmap generation with yellow-to-red intensity gradient showing severity of differences
6. Automatic alignment for different-sized images using OpenCV ZNCC template matching

Tools

get_diff_of_images

Compare two images and get structured diff results.

Parameters:

Returns:

• identical: boolean indicating if images match
• summary: overall diff statistics (pixel counts, percentages, cluster count)
• clusters: array of diff regions with bounding boxes, severity ratings, and intensity metrics
• clustering: gap used, whether it was auto-computed, and suggested alternative gap values
• alignment (when images differ in size): position coordinates, confidence score, strategy used, and timing
• dimensions: width and height of the compared region
• heatmapPath: file path to the generated heatmap image
• compositePath: file path to the heatmap overlaid on the source image

Requirements:

• Images must be accessible as local file paths
• Supports PNG, JPEG, WebP, TIFF input formats
• Images can have different dimensions — the smaller image is automatically aligned within the larger one

Tool Call Shape

MCP tool call input (minimal — just the two required paths):

{

"name": "get_diff_of_images", "arguments": { "source_image": "/path/to/design-mock.png", "target_image": "/path/to/screenshot.png" } }

MCP tool call input (with all optional parameters):

{

"name": "get_diff_of_images", "arguments": { "source_image": "/path/to/design-mock.png", "target_image": "/path/to/screenshot.png", "threshold": 0.05, "include_aa": true, "min_cluster_size": 10, "cluster_gap": 15 } }

MCP response (same-size images with differences):

{

"content": [ { "type": "text", "text": "{\n \"identical\": false,\n \"summary\": {\n \"totalPixels\": 480000,\n \"diffPixels\": 737,\n \"diffPercentage\": 0.154,\n \"antiAliasedPixels\": 1034,\n \"matchingPixels\": 478229,\n \"clusterCount\": 11,\n \"description\": \"0.15% of pixels differ across 11 cluster(s). Severity breakdown: 5 major, 5 minor, 1 trivial.\"\n },\n \"clustering\": {\n \"gapUsed\": 4,\n \"autoGap\": true,\n \"suggestedSmallerGap\": 3,\n \"suggestedLargerGap\": 5\n },\n \"clusters\": [ ... ],\n \"heatmapPath\": \"/tmp/image-diff-output/heatmap-1234567890.png\",\n \"compositePath\": \"/tmp/image-diff-output/composite-1234567890.png\",\n \"dimensions\": { \"width\": 800, \"height\": 600 }\n}" } ] }

The text field contains the full JSON result as a string. When parsed, the full response shape looks like this:

Full parsed response shape (same-size images, with differences)

{

"identical": false, "summary": { "totalPixels": 480000, "diffPixels": 737, "diffPercentage": 0.154, "antiAliasedPixels": 1034, "matchingPixels": 478229, "clusterCount": 11, "description": "0.15% of pixels differ across 11 cluster(s). Severity breakdown: 5 major, 5 minor, 1 trivial." }, "clustering": { "gapUsed": 4, "autoGap": true, "suggestedSmallerGap": 3, "suggestedLargerGap": 5 }, "clusters": [ { "id": 1, "left": 444, "top": 157, "right": 504, "bottom": 165, "width": 61, "height": 9, "pixelCount": 170, "totalImagePixels": 480000, "areaPercentage": 0.035, "meanIntensity": 0.111, "maxIntensity": 0.343, "severity": "minor" } ], "heatmapPath": "/tmp/image-diff-output/heatmap-1234567890.png", "compositePath": "/tmp/image-diff-output/composite-1234567890.png", "dimensions": { "width": 800, "height": 600 } }

Full parsed response shape (identical images)

{

"identical": true, "summary": { "totalPixels": 480000, "diffPixels": 0, "diffPercentage": 0, "antiAliasedPixels": 0, "matchingPixels": 480000, "clusterCount": 0, "description": "Images are identical (no differences detected)." }, "clustering": { "gapUsed": 0, "autoGap": true, "suggestedSmallerGap": null, "suggestedLargerGap": null }, "clusters": [], "heatmapPath": "/tmp/image-diff-output/heatmap-1234567890.png", "compositePath": "/tmp/image-diff-output/composite-1234567890.png", "dimensions": { "width": 800, "height": 600 } }

Full parsed response shape (different-size images — auto-alignment)

{

"identical": false, "summary": { "totalPixels": 108800, "diffPixels": 9031, "diffPercentage": 8.301, "antiAliasedPixels": 329, "matchingPixels": 99440, "clusterCount": 7, "description": "8.30% of pixels differ across 7 cluster(s). Severity breakdown: 1 major, 3 moderate, 3 minor." }, "clustering": { "gapUsed": 4, "autoGap": true, "suggestedSmallerGap": 1, "suggestedLargerGap": 6 }, "clusters": [ { "id": 1, "left": 20, "top": 185, "right": 299, "bottom": 215, "width": 280, "height": 31, "pixelCount": 8372, "totalImagePixels": 108800, "areaPercentage": 7.695, "meanIntensity": 0.242, "maxIntensity": 0.244, "severity": "major" } ], "alignment": { "x": 680, "y": 212, "confidence": 0.993, "strategy": "opencv-zncc-hybrid", "alignmentTimeMs": 89, "templateImage": "target", "originalDimensions": { "source": { "width": 1024, "height": 768 }, "target": { "width": 320, "height": 340 } } }, "heatmapPath": "/tmp/image-diff-output/heatmap-1234567890.png", "compositePath": "/tmp/image-diff-output/composite-1234567890.png", "dimensions": { "width": 320, "height": 340 } }

Note: The alignment field only appears when images have different dimensions. The dimensions field reflects the size of the compared region (the template size after alignment, not the full scene). The compositePath field is optional in the interface but always present when called via the MCP tool.

---

Examples

All examples below use this dashboard as the source image (800x600):

---

Example 1: Identical Images — No Differences

When two images are pixel-identical, the engine short-circuits and returns immediately.

The composite overlay shows the source image with no heatmap highlights — because there are no differences.

Structured output

{

"identical": true, "summary": { "totalPixels": 480000, "diffPixels": 0, "diffPercentage": 0, "antiAliasedPixels": 0, "matchingPixels": 480000, "clusterCount": 0, "description": "Images are identical (no differences detected)." }, "clustering": { "gapUsed": 0, "autoGap": true, "suggestedSmallerGap": null, "suggestedLargerGap": null } }

---

Example 2: Color & Value Changes

The target has updated stat values ("12,847" -> "13,205", "$48,290" -> "$52,180") and different percentage text. The engine finds 11 clusters (auto gap=4) across the changed text and numbers.

The standalone heatmap shows only the diff pixels on a transparent background — yellow means lower intensity, red means higher intensity. The composite overlay blends the heatmap onto the source image so you can see exactly where differences occur in context.

Structured output (11 clusters, top 3 shown)

{

"identical": false, "summary": { "totalPixels": 480000, "diffPixels": 737, "diffPercentage": 0.154, "antiAliasedPixels": 1034, "matchingPixels": 478229, "clusterCount": 11, "description": "0.15% of pixels differ across 11 cluster(s). Severity breakdown: 5 major, 5 minor, 1 trivial." }, "clustering": { "gapUsed": 4, "autoGap": true, "suggestedSmallerGap": 3, "suggestedLargerGap": 5 }, "clusters": [ { "id": 1, "left": 444, "top": 157, "right": 504, "bottom": 165, "width": 61, "height": 9, "pixelCount": 170, "areaPercentage": 0.035, "meanIntensity": 0.111, "maxIntensity": 0.343, "severity": "minor" }, { "id": 2, "left": 450, "top": 125, "right": 478, "bottom": 142, "width": 29, "height": 18, "pixelCount": 112, "areaPercentage": 0.023, "meanIntensity": 0.677, "maxIntensity": 0.738, "severity": "major" }, { "id": 3, "left": 284, "top": 126, "right": 308, "bottom": 142, "width": 25, "height": 17, "pixelCount": 91, "areaPercentage": 0.019, "meanIntensity": 0.682, "maxIntensity": 0.738, "severity": "major" } ] }

_8 more clusters omitted._

---

Example 3: Font Change (sans-serif -> serif)

The entire page is re-rendered with a serif font (Georgia). Every text element shifts slightly, producing many glyph-level differences. With the default auto-gap, the engine computes an optimal `c