# 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
```bash
git clone https://github.com/YOUR_USERNAME/screenshot-mcp.git
cd screenshot-mcp
```
### 2. Install Dependencies
```bash
pip install mcp httpx pillow
```
Or with requirements.txt:
```bash
pip install -r requirements.txt
```
### 3. Add to Claude Code
Add to your global settings (`~/.claude/settings.json`):
```json
{
"mcpServers": {
"screenshot-analyzer": {
"command": "python3",
"args": ["/path/to/screenshot-mcp/server.py"]
}
}
}
```
Or use Claude CLI:
```bash
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:
```json
{
"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
```python
analyze_screenshots(
platform="ios",
image_paths=["/path/to/screenshot.png"],
app_description="E-commerce app for fashion retail"
)
```
### Batch Analysis
```python
batch_analyze(
platform="android",
folder_path="/path/to/screenshots",
batch_size=5,
generate_summary=True
)
```
### Design Comparison
```python
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)
```python
# 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
```markdown
## 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
```markdown
## 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:
```bash
# 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
