Compara duas imagens pixel a pixel, agrupa diferenças visuais e gera sobreposições de heatmap para identificar mudanças na UI.
Também conhecido como pulsemcp/mcp-servers, @pulsemcp/image-diff-mcp-server
- Stars
- 81
- Ferramentas
- 14
- Downloads, 30 dias
- —
- Versão mais recente
- 0.1.3
- Último commit
- 9 de out. de 2026
- Licença
- MIT
O que é o MCP image-diff?
Compara duas imagens pixel a pixel, agrupa diferenças visuais e gera sobreposições de heatmap para identificar mudanças na UI. Ele expõe 14 ferramentas, como source_image, target_image, threshold.
Resumo gerado a partir do README do projeto
Sobre o MCP server de image-diff
Comparar mockups de design com screenshots reais da UI é o que esta ferramenta permite para desenvolvedores e engenheiros de QA. Ao fornecer caminhos de arquivos locais absolutos para uma imagem de origem e uma de destino, a ferramenta get_diff_of_images realiza uma análise pixel a pixel para identificar discrepâncias visuais. Ela suporta formatos PNG, JPEG, WebP e TIFF e pode lidar com imagens de dimensões diferentes por meio de alinhamento automático usando OpenCV ZNCC template matching.
O servidor utiliza a distância de cor perceptual YIQ NTSC para considerar a visão humana e inclui detecção de anti-aliasing para evitar falsos positivos causados por suavização de fontes. Ele agrupa diferenças adjacentes em clusters espaciais usando connected component labeling e natural-breaks clustering. Os usuários recebem dados estruturados, incluindo um resumo da contagem de pixels, níveis de severidade para cada cluster e os caminhos para os arquivos de heatmap e imagens compostas gerados. Você pode refinar a comparação ajustando o threshold, o tamanho mínimo do cluster ou o parâmetro de gap do cluster.
O que você pode fazer com ele
- 1Verificar a implementação da UI em relação aos designsCompare um mockup de design com um screenshot real para encontrar regressões visuais.
- 2Detectar mudanças de texto e valoresIdentifique quando números específicos ou strings de texto foram alterados dentro de um dashboard.
- 3Analisar mudanças na renderização de fontesDetermine como uma mudança de fonte afeta o layout e o alinhamento de pixels de uma página.
- 4Visualizar a severidade das diferençasGere heatmaps para ver exatamente onde ocorreram as mudanças visuais mais significativas.
Escrito a partir do README do projeto. Cada caso de uso é verificado com uma citação dele.
Como instalar o MCP image-diff
Formatos verificados em 10 nov 2026Adicionar ao CursorAdicionar ao GooseInstalar o MCP image-diff no Claude Code
$ claude mcp add image-diff -- npx -y @pulsemcp/image-diff-mcp-serverInstalar o MCP image-diff no Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"image-diff": {
"command": "npx",
"args": [
"-y",
"@pulsemcp/image-diff-mcp-server"
]
}
}
}Instalar o MCP image-diff no VS Code
.vscode/mcp.json
{
"servers": {
"image-diff": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@pulsemcp/image-diff-mcp-server"
]
}
}
}Instalar o MCP image-diff no VS Code CLI
$ code --add-mcp '{"name":"image-diff","type":"stdio","command":"npx","args":["-y","@pulsemcp/image-diff-mcp-server"]}'Instalar o MCP image-diff no Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"image-diff": {
"command": "npx",
"args": [
"-y",
"@pulsemcp/image-diff-mcp-server"
]
}
}
}Instalar o MCP image-diff no Codex
$ codex mcp add image-diff -- npx -y @pulsemcp/image-diff-mcp-serverInstalar o MCP image-diff no Codex config.toml
~/.codex/config.toml
[mcp_servers.image-diff] command = "npx" args = ["-y", "@pulsemcp/image-diff-mcp-server"]
Instalar o MCP image-diff no Gemini CLI
$ gemini mcp add -s user image-diff npx -- -y @pulsemcp/image-diff-mcp-serverInstalar o MCP image-diff no Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"image-diff": {
"command": "npx",
"args": [
"-y",
"@pulsemcp/image-diff-mcp-server"
]
}
}
}Ferramentas do MCP image-diff 14
Detectadas a partir do 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 todas as 14 ferramentasMostrar menos ferramentas
heatmapPathcompositePath
| heatmapPath | — | |
| compositePath | — |
Verificações automatizadas
Executado em 12 de nov. de 2026Relatório completo →Passou em nossas verificações automatizadas. Isso não é uma auditoria de segurança: leia o código e dê ao servidor o acesso mais restrito de que ele precisa. Como as verificações funcionam
- Repositório de origem vinculado e acessívelPassou
- Licença de código aberto (OSI)Passou
- Commit ou release no último anoPassou
- Nome do pacote não é próximo a um pacote popularPassou
- O endpoint remoto usa HTTPSNão verificado
- Ferramentas destrutivas estão rotuladasPassou
- Sem instruções ocultas para o modeloPassou
- Nenhum aviso crítico no pacote ou em suas dependênciasPassou
README
Ver no 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):

Perguntas sobre o MCP image-diff
Como adiciono o MCP image-diff ao Claude Code?
Execute claude mcp add image-diff -- npx -y @pulsemcp/image-diff-mcp-server no seu terminal. Adicione --scope user para torná-lo disponível em todos os projetos.
Como adiciono o MCP image-diff ao Cursor?
Abra ~/.cursor/mcp.json e adicione o servidor em mcpServers, usando a configuração do Cursor mostrada na seção de instalação acima.
Quais ferramentas o MCP image-diff oferece?
Ele expõe 14 ferramentas, incluindo source_image, target_image, threshold, include_aa, min_cluster_size.
O que o image-diff compara?
Ele compara duas imagens pixel a pixel usando distância de cor perceptual, agrupa pixels divergentes em clusters e produz visualizações de heatmap.
O image-diff consegue comparar imagens de tamanhos diferentes?
Sim, quando as imagens possuem tamanhos distintos, a imagem menor é alinhada automaticamente dentro da maior usando template matching.
Quais formatos de imagem o image-diff suporta?
Ele suporta arquivos PNG, JPEG, WebP e TIFF fornecidos como caminhos de arquivos locais.
Quais ferramentas o image-diff oferece?
Ele expõe uma única ferramenta, get_diff_of_images, que recebe os caminhos das imagens de referência e de comparação, além de parâmetros de ajuste opcionais.
O image-diff pode ignorar diferenças de anti-aliasing?
Sim, a detecção de anti-aliasing vem ativada por padrão para filtrar falsos positivos, e o parâmetro include_aa permite que você os contabilize em vez de ignorá-los.













