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:

Code follows existing style
Add tests for new features
Update README for new tools

Made with Claude Code