Screenshot Analyzer MCP

AI-powered screenshot analysis for UI/UX issues using GPT-5.2

A Model Context Protocol (MCP) server that acts as "eyes" for AI coding assistants, analyzing app screenshots to identify UI/UX problems, compare designs with implementations, and provide actionable fixes.

Features

• Single/Multi Screenshot Analysis - Analyze 1-10 screenshots at once

• Batch Analysis - Process entire folders with automatic batching

• Design Comparison - Compare design mockups vs actual screenshots

• Fast Mode - Quick scans with gpt-4o-mini at lower cost

• Report History - Store and retrieve past analysis reports

• Concurrent Loading - Parallel URL fetching (10x faster)

• Auto Retry - Exponential backoff for rate limits

Requirements

• Python 3.10+

• OpenAI API key (with GPT-5.2 or GPT-4o access)

• Claude Code CLI (for MCP integration)

Installation

1. Clone the Repository

git clone https://github.com/YOUR_USERNAME/screenshot-mcp.git
cd screenshot-mcp

2. Install Dependencies

pip install mcp httpx pillow

Or with requirements.txt:

pip install -r requirements.txt

3. Add to Claude Code

Add to your global settings (~/.claude/settings.json):

{
  "mcpServers": {
    "screenshot-analyzer": {
      "command": "python3",
      "args": ["/path/to/screenshot-mcp/server.py"]
    }
  }
}

Or use Claude CLI:

claude mcp add screenshot-analyzer python3 /path/to/screenshot-mcp/server.py

4. Set Your API Key

In Claude Code, run:

Use set_api_key tool with your OpenAI API key

Or create config.json in the same directory:

{
  "api_key": "sk-proj-your-api-key-here",
  "default_reasoning_effort": "high"
}

Available Tools

Usage Examples

Basic Analysis

analyze_screenshots(
    platform="ios",
    image_paths=["/path/to/screenshot.png"],
    app_description="E-commerce app for fashion retail"
)

Batch Analysis

batch_analyze(
    platform="android",
    folder_path="/path/to/screenshots",
    batch_size=5,
    generate_summary=True
)

Design Comparison

compare_designs(
    design_path="/path/to/figma-export.png",
    screenshot_path="/path/to/actual-screenshot.png",
    platform="ios",
    tolerance="normal"  # strict | normal | relaxed
)

Fast Mode (Lower Cost)

# Enable fast mode (uses gpt-4o-mini)
set_fast_mode(enabled=True)

# Run analysis at ~80% lower cost
analyze_screenshots(platform="web", image_paths=[...])

# Disable for detailed analysis
set_fast_mode(enabled=False)

Output Format

Analysis Report

## Summary
[X critical, Y major, Z minor issues found]

## Critical Issues (Must Fix)
- [Location]: [Problem] → [Fix]

## Major Issues
- [Location]: [Problem] → [Fix]

## Minor Issues
- [Location]: [Problem] → [Fix]

## Suggestions
- [Enhancement idea]

Comparison Report

## Consistency Score: XX/100

## Critical Differences (Design Intent Broken)
- [Element]: Design [value] → Actual [value]

## Major Differences (Noticeable)
- [Element]: Design [value] → Actual [value]

## Minor Differences (Acceptable)
- [Element]: Design [value] → Actual [value]

Configuration Options

Tolerance Levels (Design Comparison)

Technical Details

• Uses OpenAI GPT-5.2 Responses API (/v1/responses)

• Automatic image compression (max 1024px, JPEG 85%)

• Concurrent URL loading with asyncio.gather()

• Exponential backoff retry (429/5xx errors)

• Report history cache (last 20 reports)

• Supports PNG, JPEG, GIF, WebP, BMP formats

• Auto-repair corrupted images (e.g., Android screencap with text header)

Platform Support

Troubleshooting

"API key not configured"

Run set_api_key tool or create config.json with your key.

"Request timed out"

• Reduce number of images per request

• Enable fast mode for quicker responses

• Use batch_analyze for many images

"429 Rate Limit"

The server automatically retries with exponential backoff. If persistent, wait a few minutes or upgrade your OpenAI plan.

Corrupted Images (Android screencap)

If your screenshots have text/warnings embedded at the beginning (common with Android adb exec-out screencap), the MCP will automatically repair them by finding the actual image data.

To prevent this in your capture scripts:

# Redirect stderr to suppress warnings
adb exec-out screencap -p 2>/dev/null > screenshot.png

# Or specify display ID explicitly
adb exec-out screencap -d 0 -p > screenshot.png

License

MIT License - see LICENSE file for details.

Contributing

Pull requests welcome! Please ensure:

1. Code follows existing style

2. Add tests for new features

3. Update README for new tools

Made with Claude Code