2つの画像をピクセル単位で比較し、視覚的な差異をクラスター化して、UIの変更箇所を特定するためのヒートマップを生成します。
別名 pulsemcp/mcp-servers, @pulsemcp/image-diff-mcp-server
- スター
- 81
- ツール
- 14
- ダウンロード数(30日間)
- —
- 最新バージョン
- 0.1.3
- 最終コミット
- 2026年10月9日
- ライセンス
- MIT
image-diff MCPとは
image-diffはMCPサーバーです。 2つの画像をピクセル単位で比較し、視覚的な差異をクラスター化して、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 クラスタリングを使用して、隣接する差異を空間的なクラスターにグループ化します。ユーザーは、ピクセル数の要約、各クラスターの深刻度評価、および生成されたヒートマップと合成画像ファイルへのパスを含む構造化されたデータを受け取ります。しきい値、最小クラスターサイズ、またはクラスターギャップパラメータを調整することで、比較を微調整できます。
できること
- 1デザインに対するUI実装の検証デザインモックアップとライブスクリーンショットを比較して、視覚的なリグレッションを見つけます。
- 2テキストや値の変更の検出ダッシュボード内の特定の数値やテキスト文字列が変更されたかどうかを特定します。
- 3フォントレンダリングの変化の分析フォントの変更がページのレイアウトやピクセルの配置にどのように影響するかを判断します。
- 4差異の深刻度の可視化ヒートマップを生成して、最も大きな視覚的変化がどこで発生したかを正確に把握します。
プロジェクトの README から作成されています。すべてのユースケースは、その引用と照らし合わせて確認されています。
image-diff MCPのインストール方法
フォーマット検証日 2026年11月10日Cursor に追加Gooseに追加Claude Codeにimage-diff MCPをインストール
$ claude mcp add image-diff -- npx -y @pulsemcp/image-diff-mcp-serverCursorにimage-diff MCPをインストール
~/.cursor/mcp.json
{
"mcpServers": {
"image-diff": {
"command": "npx",
"args": [
"-y",
"@pulsemcp/image-diff-mcp-server"
]
}
}
}VS Codeにimage-diff MCPをインストール
.vscode/mcp.json
{
"servers": {
"image-diff": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@pulsemcp/image-diff-mcp-server"
]
}
}
}VS Code CLIにimage-diff MCPをインストール
$ code --add-mcp '{"name":"image-diff","type":"stdio","command":"npx","args":["-y","@pulsemcp/image-diff-mcp-server"]}'Claude Desktopにimage-diff MCPをインストール
claude_desktop_config.json
{
"mcpServers": {
"image-diff": {
"command": "npx",
"args": [
"-y",
"@pulsemcp/image-diff-mcp-server"
]
}
}
}Codexにimage-diff MCPをインストール
$ codex mcp add image-diff -- npx -y @pulsemcp/image-diff-mcp-serverCodex config.tomlにimage-diff MCPをインストール
~/.codex/config.toml
[mcp_servers.image-diff] command = "npx" args = ["-y", "@pulsemcp/image-diff-mcp-server"]
Gemini CLIにimage-diff MCPをインストール
$ gemini mcp add -s user image-diff npx -- -y @pulsemcp/image-diff-mcp-serverGemini settings.jsonにimage-diff MCPをインストール
~/.gemini/settings.json
{
"mcpServers": {
"image-diff": {
"command": "npx",
"args": [
"-y",
"@pulsemcp/image-diff-mcp-server"
]
}
}
}image-diff MCPツール 14
READMEから検出source_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 | — |
自動チェック
実行日 2026年11月12日完全なレポート →自動チェックに合格しました。これはセキュリティ監査ではありません。コードを読み、サーバーに必要最小限のアクセス権を与えてください。 チェックの仕組み
- ソースリポジトリがリンクされており、アクセス可能合格
- オープンソースライセンス (OSI)合格
- 過去1年以内にコミットまたはリリースあり合格
- パッケージ名が有名なパッケージに酷似していない合格
- リモートエンドポイントがHTTPSを使用未チェック
- 破壊的なツールがラベル付けされている合格
- モデルへの隠れた指示がない合格
- パッケージおよびその依存関係に重大な勧告なし合格
README
GitHubで見る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
- 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を開き、上記のインストールセクションに示すCursor設定を使ってmcpServersの下にサーバーを追加します。
image-diff MCPが提供するツールは
14個のツールを提供しており、source_image, target_image, threshold, include_aa, min_cluster_sizeなどがあります。
image-diffは何を比較しますか?
知覚的な色距離を用いて2つの画像をピクセル単位で比較し、異なるピクセルをクラスターにグループ化して、ヒートマップによる可視化を行います。
image-diffは異なるサイズの画像を比較できますか?
はい、画像のサイズが異なる場合、テンプレートマッチングを使用して、小さい方の画像が自動的に大きい方の画像内に配置されます。
image-diffはどの画像フォーマットに対応していますか?
ローカルファイルパスで指定されたPNG、JPEG、WebP、およびTIFFファイルをサポートしています。
image-diffはどのようなツールを提供しますか?
get_diff_of_images という単一のツールを提供します。これには、リファレンス画像と比較画像のパス、およびオプションの調整パラメータを指定します。
image-diffはアンチエイリアスの差異を無視できますか?
はい、誤検知を防ぐためにアンチエイリアス検出がデフォルトで有効になっています。また、include_aa パラメータを使用することで、それらをカウント対象にすることも可能です。













