Screenshot Analyzer

You deploy this MCP server to give AI coding assistants visual analysis of app screenshots. It analyzes 1–10 images at once, supports batch processing, compares designs to implementations, and stores past reports for quick reference.

How to use

Use a connected MCP client to communicate with the server. You can run analyses on single or multiple screenshots, batch-process folders, and request design comparisons to spot gaps between mockups and actual UI.

Common workflows you’ll perform include:

• Analyzing one or more screenshots to surface UI/UX issues.
• Batch analyzing a folder of images with automatic batching.
• Comparing a design mockup against a real screenshot to highlight inconsistencies.
• Toggling a fast mode to reduce cost for quick triage while preserving essential feedback.

To retrieve results, you’ll request an analysis report or pull a specific past report by ID. You can also enable or disable fast mode and adjust the reasoning level to balance depth and cost.

How to install

Prerequisites you need before setup:

• Python 3.10 or newer
• OpenAI API key with access to GPT-5.2 or GPT-4o
• Claude Code CLI for MCP integration (or use an equivalent MCP client)

# 1. Clone the MCP server
git clone https://github.com/YOUR_USERNAME/screenshot-mcp.git
cd screenshot-mcp

# 2. Install dependencies
pip install mcp httpx pillow

# Or install from requirements.txt
pip install -r requirements.txt

3. Add the MCP server to Claude Code (stdio configuration shown). This example uses a local Python runtime to start the server script.

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

4. Start the API key setup for the server access. You can either set the key in Claude Code or create a config.json with your key.

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

Additional configuration and notes

Environment variables shown to configure the MCP include your OpenAI API key and reasoning preferences. You can supply these in a config file or through your MCP client’s key management.

Configuration options available in the server include model choice, image size, quality, and fast mode settings. You can adjust these to optimize cost versus depth of analysis.

If you encounter issues with API keys or timeouts, ensure you provide a valid key and consider enabling fast mode for quicker responses. For large image batches, use batch processing to manage request load.

Available tools

analyze_screenshots

Analyze one or more screenshots for UI/UX issues and surface actionable fixes.

batch_analyze

Batch analyze a folder or multiple image files with automatic batching.

compare_designs

Compare a design mockup against an actual screenshot to identify discrepancies.

set_fast_mode

Toggle fast mode to use a cheaper model for quicker analyses.

get_report_history

List recent analysis reports stored by the MCP server.

get_report_by_id

Retrieve a specific analysis report by its ID.

get_last_report

Get the most recently generated report.

set_api_key

Configure the OpenAI API key used by the MCP server.

set_reasoning_effort

Set the reasoning level for analysis (none/low/medium/high/xhigh).

get_config

View current MCP server configuration.