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

Tool	Description
analyze_screenshots	Analyze screenshots for UI/UX issues
batch_analyze	Batch analyze folder or multiple files
compare_designs	Compare design mockup vs implementation
set_fast_mode	Toggle fast/precise mode
get_report_history	List recent analysis reports
get_report_by_id	Retrieve a specific report
get_last_report	Get the most recent report
set_api_key	Configure OpenAI API key
set_reasoning_effort	Set reasoning level (none/low/medium/high/xhigh)
get_config	View current configuration

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

Option	Default	Description
api_key	(required)	OpenAI API key
default_model	gpt-5.2	Model for analysis
default_reasoning_effort	high	Reasoning level
max_image_size	1024	Max dimension in pixels
jpeg_quality	85	Compression quality
fast_mode	false	Use faster/cheaper model
fast_mode_model	gpt-4o-mini	Model for fast mode
fast_mode_reasoning	low	Reasoning in fast mode

Tolerance Levels (Design Comparison)

Level	Description
strict	Flag all differences, even 1px variations
normal	Flag noticeable differences (2-4px, visible color mismatches)
relaxed	Only flag significant differences affecting UX

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

Platform	Guidelines
ios	Human Interface Guidelines (HIG)
android	Material Design
web	WCAG, modern web standards
desktop	Platform-specific guidelines

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