How do I use MCP Image Compare Server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@MCP Image Compare Server Compare before.png and after.png for visual differences." That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

MCP Image Compare Server

by leky90

Overview Schema Related Servers Score Discussions

TypeScript

Local

MCP Image Compare Server

npm version License: MIT Node.js Version

Tiếng Việt | English

A Model Context Protocol (MCP) server for pixel-perfect image comparison using Pixelmatch from Mapbox. Compare images, capture and compare screenshots, detect visual differences with precision.

Features

🎯 Pixel-perfect comparison - Detect even single-pixel differences
🎨 Perceptual color difference - YIQ color space for human-like perception
🔍 Anti-aliasing detection - Smart detection and exclusion of anti-aliased pixels
📊 Detailed statistics - Pixel count, percentage, dimensions
🖼️ Visual diff output - Color-coded difference visualization
🌐 Web screenshot support - Compare with live websites
📁 Multiple formats - PNG and JPEG support
⚡ Fast & lightweight - ~60-80KB package size

Related MCP server: MCP Design Comparison Server

Quick Start

Installation

# Install globally
npm install -g mcp-image-compare-server

# Install Chromium for screenshots
npx playwright install chromium

Configuration

For Claude Desktop

Add to your Claude Desktop config file:

Windows: %APPDATA%\Claude\claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "image-compare": {
      "command": "npx",
      "args": ["-y", "mcp-image-compare-server"]
    }
  }
}

Restart Claude Desktop after configuration.

For Cursor

Add to your Cursor MCP settings file:

Windows: %APPDATA%\Cursor\User\globalStorage\mcp.json
macOS: ~/Library/Application Support/Cursor/User/globalStorage/mcp.json
Linux: ~/.config/Cursor/User/globalStorage/mcp.json

{
  "mcpServers": {
    "image-compare": {
      "command": "npx",
      "args": ["-y", "mcp-image-compare-server"]
    }
  }
}

Or through Cursor settings:

Open Cursor Settings (Ctrl+, or Cmd+,)
Search for "MCP"
Click "Edit in settings.json"
Add the configuration above

Restart Cursor after configuration.

Usage

Ask in Claude Desktop or Cursor:

Compare image1.png and image2.png

That's it! 🎉

Tools

1. compare_images

Compare two local image files.

Parameters:

image1_path (string, required) - Path to first image
image2_path (string, required) - Path to second image
diff_output_path (string, optional) - Where to save diff image
threshold (number, optional) - Comparison threshold (0-1), default 0.1
includeAA (boolean, optional) - Include anti-aliased pixels, default false

Example:

{
  "image1_path": "./screenshots/before.png",
  "image2_path": "./screenshots/after.png",
  "diff_output_path": "./diff-result.png",
  "threshold": 0.1
}

2. compare_image_with_url

Compare a local image with a screenshot from a URL.

Parameters:

image_path (string, required) - Path to local image
url (string, required) - URL to capture and compare
diff_output_path (string, optional) - Where to save diff image
threshold (number, optional) - Comparison threshold (0-1), default 0.1
includeAA (boolean, optional) - Include anti-aliased pixels, default false

Example:

{
  "image_path": "./design-mockup.png",
  "url": "https://example.com",
  "threshold": 0.15
}

3. compare_urls

Compare screenshots from two different URLs.

Parameters:

url1 (string, required) - First URL to capture
url2 (string, required) - Second URL to capture
diff_output_path (string, optional) - Where to save diff image
threshold (number, optional) - Comparison threshold (0-1), default 0.1
includeAA (boolean, optional) - Include anti-aliased pixels, default false

Example:

{
  "url1": "https://staging.example.com",
  "url2": "https://production.example.com"
}

Output Format

All tools return JSON with detailed statistics:

{
  "success": true,
  "diffPixels": 1234,
  "totalPixels": 921600,
  "percentDiff": 0.13,
  "width": 1280,
  "height": 720,
  "diffImagePath": "/path/to/diff.png",
  "message": "Comparison completed: 1234 pixels differ (0.13%)"
}

Fields:

success - Operation status (true/false)
diffPixels - Number of different pixels
totalPixels - Total pixels in image
percentDiff - Percentage difference
width - Image width in pixels
height - Image height in pixels
diffImagePath - Path to generated diff image
message - Human-readable result message
error - Error message (if failed)

Use Cases

Visual Regression Testing

Compare UI before and after updates to catch unintended changes.

I have two screenshots:
- before-update.png
- after-update.png

Compare them and tell me what changed.

Cross-browser Testing

Compare rendering across different browsers to ensure consistency.

Design Review

Compare design mockups with actual implementation.

Compare design-mockup.png with https://myapp.com/landing

A/B Testing

Compare different versions of the same page.

Compare:
- https://myapp.com/variant-a
- https://myapp.com/variant-b

Mobile vs Desktop

Compare responsive layouts across different viewports.

Configuration

Threshold Values

The threshold parameter (0-1) controls comparison sensitivity:

0.0 - Very sensitive, detects smallest differences
0.1 - Default, good balance for most cases
0.3 - Less sensitive, ignores minor differences
1.0 - Least sensitive, only major differences

Anti-aliasing

When includeAA = false (default), the server automatically detects and ignores anti-aliased pixels, reducing false positives from different rendering engines.

Diff Image Colors

Red: Different pixels
Yellow: Anti-aliased pixels (if includeAA = true)
Faded: Matching pixels (reduced opacity)

Installation Methods

Method 1: NPM Global (Recommended)

npm install -g mcp-image-compare-server
npx playwright install chromium

Configure Claude Desktop:

{
  "command": "npx",
  "args": ["-y", "mcp-image-compare-server"]
}

Method 2: NPX (No Installation)

Configure Claude Desktop:

{
  "command": "npx",
  "args": ["-y", "mcp-image-compare-server"]
}

First run will download the package automatically.

Method 3: From Source

git clone https://github.com/leky90/mcp-image-compare-server.git
cd mcp-image-compare-server
npm install
npx playwright install chromium
npm run build

Configure Claude Desktop or Cursor:

{
  "command": "node",
  "args": ["/absolute/path/to/mcp-image-compare-server/dist/index.js"]
}

Replace /absolute/path/to/mcp-image-compare-server with your actual path.

System Requirements

Node.js: 18.0.0 or higher
npm: 8.0.0 or higher
OS: Windows 10+, macOS 10.15+, Linux (Ubuntu 20.04+)
Disk: ~500MB (includes Chromium browser)
RAM: 2GB minimum

Troubleshooting

Server doesn't connect

Verify config path is correct
Ensure you ran npm run build
Restart Claude Desktop or Cursor completely
Check the MCP logs for errors

"Browser not found" error

npx playwright install chromium

Screenshot timeout

For slow websites, the default 30-second timeout will handle most cases. If issues persist, please report.

Out of memory

For very large images:

Resize images before comparison
Use lower resolution images
Increase Node.js memory: node --max-old-space-size=4096 dist/index.js

Development

Building from Source

npm install
npm run build

Running Locally

npm start
# or
npm run dev

Testing

See CONTRIBUTING.md for development guidelines.

Tech Stack

Framework: Model Context Protocol SDK
Image Comparison: Pixelmatch
Screenshots: Playwright
Image Processing: Sharp, pngjs
Language: TypeScript

Contributing

Contributions are welcome! Please read CONTRIBUTING.md for guidelines.

Changelog

See CHANGELOG.md for version history.

License

MIT License - see LICENSE file for details.

Acknowledgments

Built with:

Support

🐛 Bug Reports: GitHub Issues
💬 Questions: GitHub Discussions
📖 Documentation: This README

Made with ❤️ using TypeScript and MCP

Available Tools

3 tools

compare_imagesA

Compare two local image files pixel by pixel. Supports PNG and JPEG formats. Returns the number of different pixels, percentage difference, and generates a diff image showing the differences.

ParametersJSON Schema

Name	Required	Description
`includeAA`	No	Optional: If true, include anti-aliased pixels in the diff. Default: false
`threshold`	No	Optional: Matching threshold (0-1). Lower values are more sensitive. Default: 0.1
`image1_path`	Yes	Absolute or relative path to the first image file
`image2_path`	Yes	Absolute or relative path to the second image file
`diff_output_path`	No	Optional: Path where the diff image will be saved. If not provided, a timestamped file will be created in the current directory.

TDQS

A3.8/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It describes pixel-by-pixel comparison and output, but does not mention constraints like same dimensions required, or error cases. Could be more explicit about limitations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded, no redundant information. Every sentence adds value: purpose, supported formats, and output description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, but the description explains the return values (different pixels, percentage, diff image). It also covers supported formats. Missing potential details like image size requirements, but overall adequate for a tool with well-documented parameters.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so baseline is 3. The description does not add extra meaning beyond the schema for parameters like threshold or includeAA, which are already well-documented in the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Compare two local image files'), identifies the resource type, and distinguishes from siblings by specifying 'local image files' while siblings likely handle URLs. It also mentions supported formats and output.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for local files but does not explicitly state when to use this tool versus the sibling tools (compare_image_with_url, compare_urls). No prerequisites or exclusions are mentioned.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

compare_image_with_urlA

Compare a local image file with a screenshot captured from a URL. Takes a screenshot of the webpage and compares it pixel by pixel with the provided image. Returns difference statistics and a diff image.

ParametersJSON Schema

Name	Required	Description
`url`	Yes	URL of the webpage to capture and compare
`includeAA`	No	Optional: If true, include anti-aliased pixels in the diff. Default: false
`threshold`	No	Optional: Matching threshold (0-1). Lower values are more sensitive. Default: 0.1
`image_path`	Yes	Absolute or relative path to the local image file
`diff_output_path`	No	Optional: Path where the diff image will be saved. If not provided, a timestamped file will be created.

TDQS

A4.2/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden. It discloses that a screenshot is taken, pixel-by-pixel comparison occurs, results include statistics and a diff image, and diff output path behavior (defaults to timestamped file). However, it does not mention network requirements, timeouts, or potential side effects like file creation on disk.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences: first defines the tool's core function, second elaborates on the process. No redundant information, and essential information is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 5 parameters, no output schema, and no annotations, the description covers the main purpose and outputs but lacks details on return value format (e.g., difference statistics structure) and potential limitations (e.g., screenshot viewport size). Still largely adequate.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. The description adds value by explaining that the diff_output_path defaults to a timestamped file, and that includeAA controls anti-aliasing inclusion, which is not fully covered by schema descriptions. This extra context justifies a 4.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'compare' and the unique resources: a local image file and a screenshot from a URL. It distinguishes itself from siblings compare_images and compare_urls by specifying this hybrid scenario.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

While the description implies the tool is best for comparing a local image with a webpage screenshot, it does not explicitly state when to use it over siblings or provide when-not/exclusion criteria.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

compare_urlsA

Compare screenshots from two different URLs. Captures screenshots of both webpages and compares them pixel by pixel. Returns difference statistics and a diff image showing the visual differences.

ParametersJSON Schema

Name	Required	Description
`url1`	Yes	URL of the first webpage to capture
`url2`	Yes	URL of the second webpage to capture
`includeAA`	No	Optional: If true, include anti-aliased pixels in the diff. Default: false
`threshold`	No	Optional: Matching threshold (0-1). Lower values are more sensitive. Default: 0.1
`diff_output_path`	No	Optional: Path where the diff image will be saved. If not provided, a timestamped file will be created.

TDQS

A3.8/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full disclosure burden. It mentions capturing screenshots and pixel-by-pixel comparison, but does not address potential issues like dynamic content, network timeouts, or resolution behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences convey purpose and output clearly. No unnecessary words, highly efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 5-parameter tool with no output schema, the description explains the return type (difference statistics and diff image) sufficiently. However, it could be more specific about the statistics format (e.g., percentage difference) given the lack of output schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. The description adds high-level context but does not elaborate on parameter semantics beyond what the schema already provides. The threshold and includeAA parameters are adequately described in the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states the verb 'compare' and resource 'screenshots from two URLs' and distinguishes from sibling tools (compare_images, compare_image_with_url) by specifying that it works with URLs, not pre-captured images.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies when to use the tool (comparing two webpages), but does not provide when-not-to-use or highlight alternatives. With sibling tools available, explicit guidance would improve clarity.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

3 tool updatesv1.0.1Jul 12, 2026
- First observedcompare_image_with_url
- First observedcompare_images
- First observedcompare_urls

Install Server

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.2/5.0

Disambiguation5/5

Each tool has a distinct purpose: two local files, local file vs URL screenshot, and two URL screenshots. No overlap.

Naming Consistency5/5

All tools follow a consistent 'compare_' prefix with clear argument differentiation (images, image_with_url, urls).

Tool Count5/5

Three tools cover the essential image comparison scenarios without unnecessary bloat.

Completeness5/5

The tool set fully covers local-local, local-URL, and URL-URL comparisons. No obvious gaps for typical use cases.

Maintenance

ActivityInactive

ResponsivenessSyncing

Resources

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Snapshot SiteOAuth
com.snapshot-site
Capture screenshots, detect visual regressions between page versions, and analyze with AI.
Testing & QA Tools Image & Video Processing AI & Machine Learning
41
Web Validator by DigestSEO A
io.github.AKzar1el
Validate HTML/CSS, audit SEO and JSON-LD, check links, and capture responsive screenshots.
Marketing Testing & QA Tools Browser Automation
817
UI Verify A
io.github.igrlk
MCP server for visual regression testing: triage a PR's UI diffs from your coding agent.
9118
HTML/CSS to Image APIOAuth
io.github.htmlcsstoimage
Generate images and PDFs from HTML/CSS, live websites, and reusable templates.
1

Related MCP Servers

websight
Browser Automation Testing & QA Tools
h34tsink
A
license
Not graded
quality
D
maintenance
Enables AI agents to see, analyze, and visually verify web page changes through pixel-perfect diffing, theme extraction, layout analysis, and interactive element detection.
Updated 6 months ago (2026-03-07 17:47 UTC)
5
MIT
MCP Design Comparison Server
Design Tools Testing & QA Tools
w01fgang
A
license
A
quality
B
maintenance
Compare design and implementation screenshots using pixel-by-pixel analysis, generating visual diff images and metrics.
Updated 25 days ago (2026-08-12 18:57 UTC)
1
19
MIT
screenshot
Browser Automation Web Scraping
therealMrFunGuy
A
license
Not graded
quality
D
maintenance
Provides tools to capture pixel-perfect website screenshots as images or PDF. Supports configurable viewport, full-page capture, CSS injection, and returns either viewable images or base64-encoded content.
Updated 5 months ago (2026-03-30 00:51 UTC)
MIT
claude-vision-mcp
Image & Video Processing Browser Automation Testing & QA Tools
wonderstone843
A
license
A
quality
C
maintenance
Enables Claude to capture screenshots of the screen, windows, regions, and web pages, and compare screenshots for visual regression testing.
Updated 2 months ago (2026-06-27 05:12 UTC)
6
MIT

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/leky90/mcp-image-compare-server'

If you have feedback or need assistance with the MCP directory API, please join our Discord server