Сравнивает два изображения попиксельно, группирует визуальные различия и создает тепловые карты для обнаружения изменений в UI.
Также известен как pulsemcp/mcp-servers, @pulsemcp/image-diff-mcp-server
- Звёзды
- 81
- Инструменты
- 14
- Загрузки, 30 дней
- —
- Последняя версия
- 0.1.3
- Последний коммит
- 9 окт. 2026 г.
- Лицензия
- MIT
Что такое image-diff MCP?
image-diff — это MCP server. Сравнивает два изображения попиксельно, группирует визуальные различия и создает тепловые карты для обнаружения изменений в UI. Он предоставляет 14 инструментов, например source_image, target_image, threshold.
Сводка сгенерирована из README проекта
О image-diff MCP server
Этот инструмент позволяет разработчикам и QA-инженерам сравнивать макеты дизайна с реальными скриншотами UI. Передавая абсолютные локальные пути к исходному и целевому изображениям, инструмент get_diff_of_images выполняет попиксельный анализ для выявления визуальных несоответствий. Он поддерживает форматы PNG, JPEG, WebP и TIFF, а также может обрабатывать изображения разных размеров благодаря автоматическому выравниванию с использованием метода сопоставления шаблонов OpenCV ZNCC.
Сервер использует перцептивное цветовое расстояние YIQ NTSC, учитывающее особенности человеческого зрения, и включает детектор сглаживания для предотвращения ложных срабатываний из-за сглаживания шрифтов. Инструмент группирует соседние различия в пространственные кластеры, используя маркировку связных компонентов и кластеризацию методом естественных разрывов (natural-breaks clustering). Пользователи получают структурированные данные, включая сводку по количеству пикселей, оценку серьезности каждого кластера и пути к сгенерированным файлам тепловых карт и комбинированных изображений. Вы можете точно настроить сравнение, изменяя порог чувствительности, минимальный размер кластера или параметр зазора между кластерами.
Что вы можете с ним делать
- 1Проверка реализации UI на соответствие дизайнуСравнение макета дизайна с живым скриншотом для поиска визуальных регрессий.
- 2Обнаружение изменений текста и значенийВыявление изменений конкретных чисел или текстовых строк в дашбордах.
- 3Анализ сдвигов рендеринга шрифтовОпределение того, как изменение шрифта влияет на макет и попиксельное выравнивание страницы.
- 4Визуализация серьезности различийГенерация тепловых карт, чтобы точно увидеть, где произошли наиболее значимые визуальные изменения.
Взято из README проекта. Каждый вариант использования проверен на соответствие цитате из него.
Как установить image-diff MCP
Форматы проверены 10 ноя 2026Добавить в CursorДобавить в GooseУстановка image-diff MCP в Claude Code
$ claude mcp add image-diff -- npx -y @pulsemcp/image-diff-mcp-serverУстановка image-diff MCP в Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"image-diff": {
"command": "npx",
"args": [
"-y",
"@pulsemcp/image-diff-mcp-server"
]
}
}
}Установка image-diff MCP в VS Code
.vscode/mcp.json
{
"servers": {
"image-diff": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@pulsemcp/image-diff-mcp-server"
]
}
}
}Установка image-diff MCP в VS Code CLI
$ code --add-mcp '{"name":"image-diff","type":"stdio","command":"npx","args":["-y","@pulsemcp/image-diff-mcp-server"]}'Установка image-diff MCP в Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"image-diff": {
"command": "npx",
"args": [
"-y",
"@pulsemcp/image-diff-mcp-server"
]
}
}
}Установка image-diff MCP в Codex
$ codex mcp add image-diff -- npx -y @pulsemcp/image-diff-mcp-serverУстановка image-diff MCP в Codex config.toml
~/.codex/config.toml
[mcp_servers.image-diff] command = "npx" args = ["-y", "@pulsemcp/image-diff-mcp-server"]
Установка image-diff MCP в Gemini CLI
$ gemini mcp add -s user image-diff npx -- -y @pulsemcp/image-diff-mcp-serverУстановка image-diff MCP в Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"image-diff": {
"command": "npx",
"args": [
"-y",
"@pulsemcp/image-diff-mcp-server"
]
}
}
}Инструменты image-diff MCP 14
Определено из 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 | — |
Показать все 14 инструментовПоказать меньше инструментов
heatmapPathcompositePath
| heatmapPath | — | |
| compositePath | — |
Автоматические проверки
Запущено 12 нояб. 2026 г.Полный отчёт →Прошло наши автоматизированные проверки. Это не аудит безопасности: изучите код и предоставьте серверу минимально необходимый доступ. Как работают проверки
- Связанный и доступный исходный репозиторийПройдено
- Open source лицензия (OSI)Пройдено
- Коммит или релиз за последний годПройдено
- Имя пакета не похоже на популярный пакетПройдено
- Удаленная конечная точка использует HTTPSНе проверялось
- Деструктивные инструменты помеченыПройдено
- Нет скрытых инструкций для моделиПройдено
- Нет критических предупреждений в пакете или его зависимостяхПройдено
README
Открыть на 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):

Вопросы о image-diff MCP
Как добавить image-diff MCP в Claude Code?
Выполните claude mcp add image-diff -- npx -y @pulsemcp/image-diff-mcp-server в терминале. Добавьте --scope user, чтобы сервер был доступен во всех проектах.
Как добавить image-diff MCP в Cursor?
Откройте ~/.cursor/mcp.json и добавьте сервер в mcpServers, используя конфигурацию Cursor из раздела установки выше.
Какие инструменты предоставляет image-diff MCP?
Он предоставляет 14 инструментов, включая source_image, target_image, threshold, include_aa, min_cluster_size.
Что именно сравнивает image-diff?
Инструмент сравнивает два изображения попиксельно, используя перцептивное цветовое расстояние, группирует различающиеся пиксели в кластеры и создает визуализации в виде тепловых карт.
Может ли image-diff сравнивать изображения разных размеров?
Да, если изображения различаются по размеру, меньшее изображение автоматически выравнивается относительно большего с помощью сопоставления шаблонов (template matching).
Какие форматы изображений поддерживает image-diff?
Поддерживаются файлы PNG, JPEG, WebP и TIFF, переданные в виде локальных путей к файлам.
Какие инструменты предоставляет image-diff?
Доступен один инструмент, get_diff_of_images, который принимает пути к эталонному и сравниваемому изображениям, а также необязательные параметры настройки.
Может ли image-diff игнорировать различия из-за сглаживания (anti-aliasing)?
Да, обнаружение сглаживания включено по умолчанию для фильтрации ложноположительных результатов, а параметр include_aa позволяет, наоборот, учитывать их в анализе.













