Compare deux images pixel par pixel, regroupe les différences visuelles par clusters et génère des superpositions de cartes thermiques (heatmaps) pour repérer les changements d'interface utilisateur (UI).
Aussi connu sous pulsemcp/mcp-servers, @pulsemcp/image-diff-mcp-server
- Étoiles
- 81
- Outils
- 14
- Téléchargements, 30 jours
- —
- Dernière version
- 0.1.3
- Dernier commit
- 9 oct. 2026
- Licence
- MIT
Qu'est-ce que image-diff MCP ?
image-diff est un serveur MCP. Compare deux images pixel par pixel, regroupe les différences visuelles par clusters et génère des superpositions de cartes thermiques (heatmaps) pour repérer les changements d'interface utilisateur (UI). Il expose 14 outils, comme source_image, target_image, threshold.
Résumé généré à partir du README du projet
À propos du MCP server image-diff
Cet outil permet aux développeurs et aux ingénieurs QA de comparer des maquettes de conception avec des captures d'écran d'UI réelles. En fournissant des chemins de fichiers locaux absolus pour une image source et une image cible, l'outil get_diff_of_images effectue une analyse pixel par pixel pour identifier les écarts visuels. Il prend en charge les formats PNG, JPEG, WebP et TIFF et peut gérer des images de dimensions différentes grâce à un alignement automatique via le template matching OpenCV ZNCC.
Le serveur utilise la distance de couleur perceptuelle YIQ NTSC pour tenir compte de la vision humaine et inclut une détection de l'anti-aliasing pour éviter les faux positifs liés au lissage des polices. Il regroupe les différences adjacentes en clusters spatiaux en utilisant le connected component labeling et le clustering natural-breaks. Les utilisateurs reçoivent des données structurées incluant un résumé du nombre de pixels, des niveaux de sévérité pour chaque cluster, ainsi que les chemins vers les fichiers de cartes thermiques et d'images composites générés. Vous pouvez affiner la comparaison en ajustant le seuil (threshold), la taille minimale du cluster ou le paramètre de gap entre les clusters.
Ce que vous pouvez faire avec
- 1Vérifier l'implémentation de l'UI par rapport aux designsComparez une maquette de design à une capture d'écran en direct pour trouver des régressions visuelles.
- 2Détecter les changements de texte et de valeursIdentifiez quand des chiffres spécifiques ou des chaînes de caractères ont changé au sein d'un tableau de bord.
- 3Analyser les décalages de rendu de policeDéterminez comment un changement de police affecte la mise en page et l'alignement des pixels d'une page.
- 4Visualiser la sévérité des différencesGénérez des cartes thermiques pour voir exactement où les changements visuels les plus significatifs se sont produits.
Extrait du README du projet. Chaque cas d'utilisation est vérifié par rapport à une citation du document.
Comment installer image-diff MCP
Formats vérifiés le 10 nov. 2026Ajouter à CursorAjouter à GooseInstaller image-diff MCP dans Claude Code
$ claude mcp add image-diff -- npx -y @pulsemcp/image-diff-mcp-serverInstaller image-diff MCP dans Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"image-diff": {
"command": "npx",
"args": [
"-y",
"@pulsemcp/image-diff-mcp-server"
]
}
}
}Installer image-diff MCP dans VS Code
.vscode/mcp.json
{
"servers": {
"image-diff": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@pulsemcp/image-diff-mcp-server"
]
}
}
}Installer image-diff MCP dans VS Code CLI
$ code --add-mcp '{"name":"image-diff","type":"stdio","command":"npx","args":["-y","@pulsemcp/image-diff-mcp-server"]}'Installer image-diff MCP dans Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"image-diff": {
"command": "npx",
"args": [
"-y",
"@pulsemcp/image-diff-mcp-server"
]
}
}
}Installer image-diff MCP dans Codex
$ codex mcp add image-diff -- npx -y @pulsemcp/image-diff-mcp-serverInstaller image-diff MCP dans Codex config.toml
~/.codex/config.toml
[mcp_servers.image-diff] command = "npx" args = ["-y", "@pulsemcp/image-diff-mcp-server"]
Installer image-diff MCP dans Gemini CLI
$ gemini mcp add -s user image-diff npx -- -y @pulsemcp/image-diff-mcp-serverInstaller image-diff MCP dans Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"image-diff": {
"command": "npx",
"args": [
"-y",
"@pulsemcp/image-diff-mcp-server"
]
}
}
}Outils MCP image-diff 14
Détectés depuis le READMEsource_imagetarget_imagethresholdinclude_aamin_cluster_sizecluster_gapidenticalsummaryclustersclusteringalignmentdimensions
| source_image | — | |
| target_image | — | |
| threshold | — | |
| include_aa | — | |
| min_cluster_size | — | |
| cluster_gap | — | |
| identical | — | |
| summary | — | |
| clusters | — | |
| clustering | — | |
| alignment | — | |
| dimensions | — |
Afficher les 14 outilsAfficher moins d'outils
heatmapPathcompositePath
| heatmapPath | — | |
| compositePath | — |
Vérifications automatisées
Exécuté le 12 nov. 2026Rapport complet →A passé nos vérifications automatisées. Il ne s'agit pas d'un audit de sécurité : lisez le code et donnez au serveur l'accès le plus restreint dont il a besoin. Fonctionnement des vérifications
- Dépôt source lié et accessibleRéussi
- Licence open source (OSI)Réussi
- Commit ou version publiée au cours de l'année écouléeRéussi
- Nom du package non proche d'un package populaireRéussi
- L'endpoint distant utilise HTTPSNon vérifié
- Les outils destructifs sont étiquetésRéussi
- Aucune instruction cachée destinée au modèleRéussi
- Aucun avis critique dans le package ou ses dépendancesRéussi
README
Voir sur GitHubimage-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
- Pixel comparison using YIQ NTSC perceptual color distance (accounts for how humans perceive color differences)
- Anti-aliasing detection to filter out false positives from font smoothing and rounded corners
- Connected Component Labeling to group adjacent diff pixels into spatial clusters
- Natural-breaks clustering to auto-compute an optimal
cluster_gapusing nearest-neighbor distance analysis, merging nearby clusters into meaningful groups - Heatmap generation with yellow-to-red intensity gradient showing severity of differences
- 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:
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
source_image |
string | Yes | - | Absolute path to the reference image |
target_image |
string | Yes | - | Absolute path to the comparison image |
threshold |
number | No | 0.1 | Color matching sensitivity (0-1, lower = more sensitive) |
include_aa |
boolean | No | false | Count anti-aliased pixels as differences |
min_cluster_size |
number | No | 4 | Minimum connected pixels to form a cluster |
cluster_gap |
number | No | auto | Max pixel gap to merge nearby clusters. When omitted, an optimal gap is auto-computed using nearest-neighbor distance analysis with natural breaks. Set to 0 for no merging, or any positive integer for manual control. |
Returns:
identical: boolean indicating if images matchsummary: overall diff statistics (pixel counts, percentages, cluster count)clusters: array of diff regions with bounding boxes, severity ratings, and intensity metricsclustering: gap used, whether it was auto-computed, and suggested alternative gap valuesalignment(when images differ in size): position coordinates, confidence score, strategy used, and timingdimensions: width and height of the compared regionheatmapPath: file path to the generated heatmap imagecompositePath: 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:
{
"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
}
}
{
"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
}
}
{
"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.
| Source | Target | Composite |
|---|---|---|
![]() |
![]() |
![]() |
The composite overlay shows the source image with no heatmap highlights — because there are no differences.
{
"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.
| Source | Target |
|---|---|
![]() |
![]() |
| Standalone Heatmap | Composite Overlay |
|---|---|
![]() |
![]() |
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.
{
"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 cluster_gap=10 and merges these into 40 clusters representing distinct text blocks and UI regions.
| Source | Target |
|---|---|
![]() |
![]() |
| Standalone Heatmap | Composite Overlay |
|---|---|
![]() |
![]() |
The heatmap lights up across every text region — headers, stat values, table content, sidebar labels. Auto-gap merges nearby glyph fragments into meaningful groups.
{
"identical": false,
"summary": {
"totalPixels": 480000,
"diffPixels": 11671,
"diffPercentage": 2.431,
"antiAliasedPixels": 8326,
"matchingPixels": 460003,
"clusterCount": 40,
"description": "2.43% of pixels differ across 40 cluster(s). Severity breakdown: 26 moderate, 14 minor."
},
"clustering": {
"gapUsed": 10,
"autoGap": true,
"suggestedSmallerGap": 9,
"suggestedLargerGap": 11
},
"clusters": [
{
"id": 1,
"left": 434,
"top": 125,
"right": 550,
"bottom": 166,
"width": 117,
"height": 42,
"pixelCount": 912,
"severity": "moderate"
},
{
"id": 2,
"left": 246,
"top": 125,
"right": 372,
"bottom": 166,
"width": 127,
"height": 42,
"pixelCount": 883,
"severity": "moderate"
},
{
"id": 3,
"left": 625,
"top": 125,
"right": 733,
"bottom": 166,
"width": 109,
"height": 42,
"pixelCount": 716,
"severity": "moderate"
}
]
}
37 more clusters omitted. Note: same diff pixels, same percentage — only the grouping changes.
What Auto-Gap Saves You From: cluster_gap=0
Without auto-gap, each glyph fragment becomes its own cluster. Setting cluster_gap=0 explicitly disables merging:
cluster_gap |
Clusters | What Happens |
|---|---|---|
| auto (default) | 40 | Auto-computed gap=10 merges fragments into text blocks |
| 0 (no merging) | 331 | Every glyph fragment is a separate cluster |
With cluster_gap=0, the 40 meaningful groups explode into 331 raw clusters — one for every individual character difference. This is what auto-gap saves you from.
{
"identical": false,
"summary": {
"totalPixels": 480000,
"diffPixels": 11671,
"diffPercentage": 2.431,
"antiAliasedPixels": 8326,
"matchingPixels": 460003,
"clusterCount": 331,
"description": "2.43% of pixels differ across 331 cluster(s). Severity breakdown: 61 major, 161 moderate, 105 minor, 4 trivial."
},
"clustering": {
"gapUsed": 0,
"autoGap": false,
"suggestedSmallerGap": null,
"suggestedLargerGap": 1
},
"clusters": [
{
"id": 1,
"left": 65,
"top": 88,
"right": 110,
"bottom": 98,
"width": 46,
"height": 11,
"pixelCount": 221,
"severity": "moderate"
},
{
"id": 2,
"left": 555,
"top": 317,
"right": 597,
"bottom": 329,
"width": 43,
"height": 13,
"pixelCount": 213,
"severity": "moderate"
},
{
"id": 3,
"left": 555,
"top": 391,
"right": 597,
"bottom": 403,
"width": 43,
"height": 13,
"pixelCount": 213,
"severity": "moderate"
}
]
}
328 more clusters omitted. Note: same diff pixels, same percentage — only the grouping changes.
Example 4: Missing Elements (Badges Removed)
The target has status badges ("Complete", "Active") removed from the table — replaced with plain text. The engine detects 19 clusters (auto gap=4) precisely locating each removed badge.
| Source | Target |
|---|---|
![]() |
![]() |
| Standalone Heatmap | Composite Overlay |
|---|---|
![]() |
![]() |
The heatmap highlights each badge position where the colored pill was replaced with plain text.
{
"identical": false,
"summary": {
"totalPixels": 480000,
"diffPixels": 4506,
"diffPercentage": 0.939,
"antiAliasedPixels": 2283,
"matchingPixels": 473211,
"clusterCount": 19,
"description": "0.94% of pixels differ across 19 cluster(s). Severity breakdown: 18 moderate, 1 minor."
},
"clustering": {
"gapUsed": 4,
"autoGap": true,
"suggestedSmallerGap": 3,
"suggestedLargerGap": 5
},
"clusters": [
{
"id": 1,
"left": 369,
"top": 426,
"right": 487,
"bottom": 439,
"width": 119,
"height": 14,
"pixelCount": 516,
"areaPercentage": 0.108,
"severity": "moderate"
},
{
"id": 2,
"left": 369,
"top": 352,
"right": 462,
"bottom": 365,
"width": 94,
"height": 14,
"pixelCount": 442,
"areaPercentage": 0.092,
"severity": "moderate"
},
{
"id": 3,
"left": 657,
"top": 427,
"right": 723,
"bottom": 439,
"width": 67,
"height": 13,
"pixelCount": 311,
"areaPercentage": 0.065,
"severity": "moderate"
}
]
}
16 more clusters omitted.
Example 5: Layout Shift (Padding Change)
The target has increased padding and gaps on the stat cards — everything shifts down slightly. This produces 18 clusters (auto gap=18) because the auto-gap merges the many edge-level fragments caused by content repositioning.
| Source | Target |
|---|---|
![]() |
![]() |
| Standalone Heatmap | Composite Overlay |
|---|---|
![]() |
![]() |
Layout shifts light up the heatmap everywhere content has repositioned. The auto-gap merges the ripple effect into cohesive regions representing each shifted element.
{
"identical": false,
"summary": {
"totalPixels": 480000,
"diffPixels": 11136,
"diffPercentage": 2.32,
"antiAliasedPixels": 10938,
"matchingPixels": 457926,
"clusterCount": 18,
"description": "2.32% of pixels differ across 18 cluster(s). Severity breakdown: 18 moderate."
},
"clustering": {
"gapUsed": 18,
"autoGap": true,
"suggestedSmallerGap": 17,
"suggestedLargerGap": 19
},
"clusters": [
{
"id": 1,
"left": 434,
"top": 105,
"right": 550,
"bottom": 195,
"width": 117,
"height": 91,
"pixelCount": 1531,
"areaPercentage": 0.319,
"severity": "moderate"
},
{
"id": 2,
"left": 369,
"top": 315,
"right": 490,
"bottom": 448,
"width": 122,
"height": 134,
"pixelCount": 1490,
"areaPercentage": 0.31,
"severity": "moderate"
},
{
"id": 3,
"left": 245,
"top": 103,
"right": 372,
"bottom": 195,
"width": 128,
"height": 93,
"pixelCount": 1473,
"areaPercentage": 0.307,
"severity": "moderate"
}
]
}
15 more clusters omitted.
Auto-Alignment: Comparing Different-Sized Images
When the source and target have different dimensions, the engine automatically finds where the smaller image (the "template") best matches within the larger one (the "scene"), crops that region, and runs the standard pixel-level comparison. No configuration needed.
How it works:
- Coarse search — OpenCV ZNCC (Zero-mean Normalized Cross-Correlation) template matching at downscaled resolution for fast candidate detection
- Fine refinement — Pixel-level ZNCC at full resolution around the coarse match for sub-pixel accuracy
- Crop & compare — The matched region is cropped from the scene and compared pixel-by-pixel against the template
This enables comparing a Figma component mock against a full-page screenshot directly — no manual cropping needed.
All alignment examples below use this dashboard as the source (scene) image (1024x768):

Questions sur image-diff MCP
Comment ajouter image-diff MCP à Claude Code ?
Exécutez claude mcp add image-diff -- npx -y @pulsemcp/image-diff-mcp-server dans votre terminal. Ajoutez --scope user pour le rendre disponible dans tous les projets.
Comment ajouter image-diff MCP à Cursor ?
Ouvrez ~/.cursor/mcp.json et ajoutez le serveur sous mcpServers, avec la configuration Cursor indiquée dans la section d'installation ci-dessus.
Quels outils image-diff MCP fournit-il ?
Il expose 14 outils, dont source_image, target_image, threshold, include_aa, min_cluster_size.
Que compare image-diff ?
Il compare deux images pixel par pixel en utilisant la distance de couleur perceptuelle, regroupe les pixels divergents en clusters et produit des visualisations sous forme de cartes thermiques.
image-diff peut-il comparer des images de tailles différentes ?
Oui, lorsque les images diffèrent par leur taille, l'image la plus petite est automatiquement alignée à l'intérieur de la plus grande grâce au template matching.
Quels formats d'image image-diff prend-il en charge ?
Il prend en charge les fichiers PNG, JPEG, WebP et TIFF fournis via des chemins de fichiers locaux.
Quels outils image-diff propose-t-il ?
Il expose un outil unique, get_diff_of_images, qui prend les chemins des images de référence et de comparaison ainsi que des paramètres de réglage optionnels.
image-diff peut-il ignorer les différences d'anti-aliasing ?
Oui, la détection de l'anti-aliasing est activée par défaut pour filtrer les faux positifs, et le paramètre include_aa vous permet de les comptabiliser à la place.













