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

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:

1. Open Cursor Settings (Ctrl+, or Cmd+,)
2. Search for "MCP"
3. Click "Edit in settings.json"
4. 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

1. Verify config path is correct
2. Ensure you ran npm run build
3. Restart Claude Desktop or Cursor completely
4. 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:

• Pixelmatch by Mapbox
• Model Context Protocol
• Playwright
• Sharp

Support

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

---

Made with ❤️ using TypeScript and MCP