Compara dos imágenes píxel a píxel, agrupa las diferencias visuales y genera superposiciones de mapas de calor para detectar cambios en la interfaz de usuario.
También conocido como pulsemcp/mcp-servers, @pulsemcp/image-diff-mcp-server
- Stars
- 81
- Herramientas
- 14
- Descargas, 30 días
- —
- Última versión
- 0.1.3
- Último commit
- 9 oct 2026
- Licencia
- MIT
¿Qué es image-diff MCP?
image-diff es un MCP server. Compara dos imágenes píxel a píxel, agrupa las diferencias visuales y genera superposiciones de mapas de calor para detectar cambios en la interfaz de usuario. Expone 14 herramientas, como source_image, target_image, threshold.
Resumen generado a partir del README del proyecto
Acerca del MCP server de image-diff
Esta herramienta permite a desarrolladores e ingenieros de QA comparar maquetas de diseño con capturas de pantalla reales de la interfaz de usuario. Al proporcionar rutas de archivos locales absolutas para una imagen de origen y una de destino, la herramienta get_diff_of_images realiza un análisis píxel a píxel para identificar discrepancias visuales. Admite formatos PNG, JPEG, WebP y TIFF, y puede manejar imágenes de diferentes dimensiones mediante alineación automática con OpenCV ZNCC template matching.
El servidor utiliza la distancia de color perceptual YIQ NTSC para tener en cuenta la visión humana e incluye detección de anti-aliasing para evitar falsos positivos causados por el suavizado de fuentes. Agrupa las diferencias adyacentes en clusters espaciales mediante connected component labeling y natural-breaks clustering. Los usuarios reciben datos estructurados que incluyen un resumen del recuento de píxeles, niveles de severidad para cada cluster y las rutas de los archivos de mapas de calor e imágenes compuestas generados. Puedes ajustar la comparación modificando el umbral (threshold), el tamaño mínimo del cluster o el parámetro de separación de clusters (cluster gap).
Qué puedes hacer con él
- 1Verificar la implementación de la UI frente a los diseñosCompara una maqueta de diseño con una captura de pantalla en vivo para encontrar regresiones visuales.
- 2Detectar cambios en texto y valoresIdentifica cuándo han cambiado números específicos o cadenas de texto dentro de un dashboard.
- 3Analizar cambios en el renderizado de fuentesDetermina cómo un cambio de fuente afecta al diseño y a la alineación de píxeles de una página.
- 4Visualizar la severidad de las diferenciasGenera mapas de calor para ver exactamente dónde han ocurrido los cambios visuales más significativos.
Escrito a partir del README del proyecto. Cada caso de uso se verifica con una cita del mismo.
Cómo instalar image-diff MCP
Formatos verificados el 10 nov 2026Añadir a CursorAñadir a GooseInstalar image-diff MCP en Claude Code
$ claude mcp add image-diff -- npx -y @pulsemcp/image-diff-mcp-serverInstalar image-diff MCP en Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"image-diff": {
"command": "npx",
"args": [
"-y",
"@pulsemcp/image-diff-mcp-server"
]
}
}
}Instalar image-diff MCP en VS Code
.vscode/mcp.json
{
"servers": {
"image-diff": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@pulsemcp/image-diff-mcp-server"
]
}
}
}Instalar image-diff MCP en VS Code CLI
$ code --add-mcp '{"name":"image-diff","type":"stdio","command":"npx","args":["-y","@pulsemcp/image-diff-mcp-server"]}'Instalar image-diff MCP en Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"image-diff": {
"command": "npx",
"args": [
"-y",
"@pulsemcp/image-diff-mcp-server"
]
}
}
}Instalar image-diff MCP en Codex
$ codex mcp add image-diff -- npx -y @pulsemcp/image-diff-mcp-serverInstalar image-diff MCP en Codex config.toml
~/.codex/config.toml
[mcp_servers.image-diff] command = "npx" args = ["-y", "@pulsemcp/image-diff-mcp-server"]
Instalar image-diff MCP en Gemini CLI
$ gemini mcp add -s user image-diff npx -- -y @pulsemcp/image-diff-mcp-serverInstalar image-diff MCP en Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"image-diff": {
"command": "npx",
"args": [
"-y",
"@pulsemcp/image-diff-mcp-server"
]
}
}
}Herramientas de image-diff MCP 14
Detectado desde el 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 | — |
Mostrar las 14 herramientasMostrar menos herramientas
heatmapPathcompositePath
| heatmapPath | — | |
| compositePath | — |
Verificaciones automáticas
Ejecutado 12 nov 2026Informe completo →Pasó nuestras verificaciones automáticas. Esto no es una auditoría de seguridad: lee el código y dale al servidor el acceso más limitado que necesite. Cómo funcionan las verificaciones
- Repositorio de origen vinculado y accesibleAprobado
- Licencia de código abierto (OSI)Aprobado
- Commit o lanzamiento en el último añoAprobado
- El nombre del paquete no es similar a un paquete popularAprobado
- El endpoint remoto usa HTTPSNo verificado
- Las herramientas destructivas están etiquetadasAprobado
- Sin instrucciones ocultas para el modeloAprobado
- No hay avisos críticos en el paquete ni en sus dependenciasAprobado
README
Ver en 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):

Preguntas sobre image-diff MCP
¿Cómo agrego image-diff MCP a Claude Code?
Ejecuta claude mcp add image-diff -- npx -y @pulsemcp/image-diff-mcp-server en tu terminal. Añade --scope user para que esté disponible en todos los proyectos.
¿Cómo agrego image-diff MCP a Cursor?
Abre ~/.cursor/mcp.json y añade el servidor en mcpServers, usando la configuración de Cursor que se muestra en la sección de instalación de arriba.
¿Qué herramientas proporciona image-diff MCP?
Expone 14 herramientas, incluidas source_image, target_image, threshold, include_aa, min_cluster_size.
¿Qué compara image-diff?
Compara dos imágenes píxel a píxel utilizando la distancia de color perceptual, agrupa los píxeles diferentes en clusters y produce visualizaciones mediante mapas de calor.
¿Puede image-diff comparar imágenes de diferentes tamaños?
Sí, cuando las imágenes tienen tamaños distintos, la imagen más pequeña se alinea automáticamente dentro de la más grande mediante template matching.
¿Qué formatos de imagen admite image-diff?
Soporta archivos PNG, JPEG, WebP y TIFF proporcionados como rutas de archivos locales.
¿Qué herramientas ofrece image-diff?
Expone una única herramienta, get_diff_of_images, que recibe las rutas de la imagen de referencia y la de comparación, además de parámetros de ajuste opcionales.
¿Puede image-diff ignorar las diferencias de anti-aliasing?
Sí, la detección de anti-aliasing está activada por defecto para filtrar falsos positivos, y el parámetro include_aa te permite contarlos en su lugar.













