sosukesuzuki/pixelmatch-mcp-server

Pixelmatch MCP Server

MCP server for comparing UI screenshots using pixelmatch to help autonomous coding agents validate frontend implementations.

Overview

This MCP (Model Context Protocol) server provides image comparison tools specifically designed for autonomous coding agents working on frontend implementations. It uses pixelmatch to calculate visual similarity between current UI screenshots and target/ideal designs, enabling rapid iteration and validation of UI changes.

Installation

npm install pixelmatch-mcp-server
# or
pnpm add pixelmatch-mcp-server

Usage

Settings

{
  "mcpServers": {
    "pixelmatch": {
      "command": "npx",
      "args": ["pixelmatch-mcp-server"]
    }
  }
}

MCP Tool: compare_ui_images

Compares two UI screenshots and returns detailed similarity analysis.

Parameters

• current_image_path (required): Path to the current UI screenshot
• target_image_path (required): Path to the target/ideal UI screenshot
• threshold (optional): Pixel matching sensitivity (0-1, default: 0.1)
• output_diff_path (optional): Path to save visual diff image

Response

{
  "success": true,
  "similarity_score": 0.92,
  "difference_percentage": 8.0,
  "different_pixels": 1200,
  "total_pixels": 15000,
  "dimensions": {
    "width": 800,
    "height": 600
  },
  "diff_saved": true,
  "diff_path": "./diff.png",
  "assessment": {
    "is_very_similar": false,
    "is_similar": true,
    "is_different": false,
    "recommendation": "Images are similar with minor differences - may need small adjustments"
  }
}

Assessment Levels

• Very Similar (>95%): UI implementation looks correct
• Similar (>80%): Minor differences, may need small adjustments
• Noticeable Differences (>50%): UI implementation needs improvements
• Significantly Different (<50%): Major UI implementation changes needed

License

MIT