batteryshark/mcp-screenshot

MCP Screenshot Server

A FastMCP server that captures screenshots and returns them as images for visual analysis by LLMs. Perfect for UI debugging, troubleshooting, and visual inspection of applications.

⚠️ SECURITY WARNING

This MCP server can capture and record your screen content. It has access to everything visible on your display, including sensitive information like passwords, private messages, financial data, and confidential documents.

Recommendations:

• Only enable this MCP server when you specifically need screenshot functionality
• Disable it when working with sensitive information
• Be aware that any connected LLM can request screenshots of your current screen
• Consider using window-specific capture instead of full-screen capture when possible

You have been warned. Use responsibly.

Features

• 🤖 Enhanced Smart Capture: Natural language queries like "what am I watching on YouTube" with auto-zoom
• 🧠 Smart Capture: Automatically finds the most relevant window (browsers, media, dev tools)
• 🎯 Context-Aware: Provide hints like "youtube", "code", "browser" for targeted capture
• 📱 Active Window Capture: Automatically capture the focused window
• 📋 Window Management: List, activate, and capture specific windows by ID
• 📐 Region Capture: Capture specific rectangular areas
• 🔍 Text Enhancement: OpenCV-powered image processing for better text readability
• ⚡ Quality Modes: Optimize for overview, readable text, or pixel-perfect detail
• 🔧 Permission Checking: Verify macOS permissions and available functionality
• 💻 Cross-Platform: macOS (native), Windows/Linux (fallback)
• 🚫 Ultra-Wide Friendly: Avoids massive full-screen captures by default

Installation

# Clone and setup
git clone https://github.com/yourusername/mcp-screenshot.git
cd mcp-screenshot
uv venv --python 3.12
uv add fastmcp pillow pyautogui opencv-python numpy

# Run the server
uv run python server.py

MCP Configuration

Local/stdio Configuration

{
  "mcpServers": {
    "screenshot": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "--directory", "/path/to/mcp-screenshot", "python", "server.py"]
    }
  }
}

Configuration Locations:

• VS Code: .vscode/mcp.json (project) or user settings
• Claude Desktop: claude_desktop_config.json
• Cursor: .cursor/mcp.json (project) or ~/.cursor/mcp.json (user)

Tools

screenshot_smart_enhanced 🤖 NEW PRIMARY TOOL

Enhanced smart screenshot with natural language understanding and auto-zoom.

• query: Natural language query like "what am I watching on YouTube" or "show me my code"
• auto_zoom: Automatically capture focused regions if initial screenshot is unclear
• quality_mode: "overview" (0.4x), "readable" (0.8x), "detail" (1.0x)
• enhance_text: Apply sharpening/contrast for text readability
• format: "png" or "jpeg"

Enhanced Logic:

1. Parses natural language intent (media consumption, development, communication)
2. Intelligently finds matching windows based on user query
3. Auto-activates target window for clean capture
4. Auto-zooms into interesting content regions if needed
5. Provides contextual response messages

screenshot_smart ⭐ STANDARD SMART TOOL

Intelligently finds and captures the most relevant window automatically.

• context: Optional hint ("youtube", "browser", "code", "slack", etc.)
• Same quality/enhancement options as enhanced version

Smart Logic:

1. Looks for windows matching context hint
2. Falls back to active window if relevant
3. Prioritizes browsers, media apps, development tools
4. Avoids tiny/system windows
5. Last resort: center region (not full screen!)

screenshot_full ⚠️ AVOID ON ULTRA-WIDE

Capture entire desktop/screen (use sparingly).

• Same parameters as smart capture
• Default: quality_mode="overview" to handle large screens

screenshot_active_window

Capture currently focused window.

• Same parameters as screenshot_full
• Default: quality_mode="readable"

screenshot_region

Capture specific rectangular area.

• x, y: Top-left coordinates
• width, height: Region dimensions
• Same quality/enhancement options
• Default: quality_mode="detail"

check_permissions 🔧 NEW DIAGNOSTIC TOOL

Check what macOS permissions are available and what functionality works. Returns detailed permission status and available features.

list_windows

Get list of all open windows with IDs and bounds. Returns structured data with window information for use with screenshot_window.

activate_window 🔧 NEW UTILITY

Activate/focus a specific window by bringing it to front.

• window_id: Window identifier from list_windows

screenshot_window

Capture specific window by ID from list_windows.

• window_id: Window identifier
• Same quality/enhancement options
• Automatically activates window first for clean capture

Quality Modes

• overview (0.4x scale): Quick layout checks, fits ultra-wide screens
• readable (0.8x scale): Text stays legible, good for debugging
• detail (1.0x scale): Full resolution for pixel-perfect analysis

Text Enhancement

Automatic image processing for better LLM readability:

• OpenCV sharpening filters
• Contrast enhancement
• Unsharp masking
• Optimized for text recognition

Platform Support

• macOS: Native screencapture + AppleScript for window management
• Windows/Linux: PyAutoGUI fallback (basic functionality)

Permissions

macOS Permissions Required:

1. Screen Recording: System Preferences > Security & Privacy > Privacy > Screen Recording

   • Add Terminal, Cursor, or whatever app runs the MCP server
   • Required for: All screenshot capture functionality

2. Accessibility: System Preferences > Security & Privacy > Privacy > Accessibility

   • Add Terminal, Cursor, or whatever app runs the MCP server
   • Required for: Window listing (list_windows) and selective window capture
   • Note: Smart capture works without this (uses active window detection)

Without Accessibility permissions:

• ✅ screenshot_smart works (uses active window)
• ✅ screenshot_active_window works
• ✅ screenshot_full and screenshot_region work
• ❌ list_windows returns empty (can't enumerate all windows)
• ❌ screenshot_window won't work (needs window list)

Examples

# Enhanced smart capture (recommended):
"What am I watching on YouTube?"
"Show me what I'm working on" 
"What am I listening to?"
"Show me my conversation"

# Standard smart capture:
"Take a smart screenshot of what I'm watching on YouTube"
"Show me what's in my browser"
"Capture my development environment" 
"Take a smart screenshot with context 'slack'"

# Utility tools:
"Check my macOS permissions"
"Show me all open windows"
"Activate window ID 5"
"Screenshot window ID 3 in detail mode"  
"Capture region at coordinates 100,100 with size 800x600"
"Take full screen screenshot in overview mode"  # Last resort

The server returns images directly to the LLM context for immediate visual analysis.