screenshot-mcp

A cross-platform MCP (Model Context Protocol) server for capturing screenshots. Designed for agent-based native application testing.

Also available as a Claude Code plugin with screenshot testing guidance.

Features

List Windows: Get all visible windows with IDs, titles, and bounds
List Displays: Get all available monitors/displays
Screenshot Window: Capture a specific window by ID or title
Screenshot Screen: Capture an entire display
Screenshot Region: Capture a specific screen region

Installation

No installation required - use directly with npx or bunx.

Usage

Configure in Claude Code

Add to your MCP settings (~/.claude/settings.json):

{
  "mcpServers": {
    "screenshot": {
      "command": "bunx",
      "args": ["screenshot-mcp"]
    }
  }
}

Or with npx:

{
  "mcpServers": {
    "screenshot": {
      "command": "npx",
      "args": ["-y", "screenshot-mcp"]
    }
  }
}

Run Standalone

# Using bunx (recommended)
bunx screenshot-mcp

# Using npx
npx -y screenshot-mcp

MCP Tools

`list_windows`

List all visible windows.

// Response
[
  { "id": "1234", "title": "VS Code", "app": "Code", "bounds": { "x": 0, "y": 25, "width": 1920, "height": 1055 } }
]

`list_displays`

List all available displays.

// Response
[
  { "id": 1, "name": "Built-in Retina Display", "primary": true, "bounds": { "x": 0, "y": 0, "width": 2560, "height": 1600 } }
]

`screenshot_window`

Capture a specific window.

// Parameters
{ "window_id": "1234" }
// or
{ "window_title": "VS Code" }
// optional: save to file
{ "window_id": "1234", "save_dir": "/path/to/screenshots" }

`screenshot_screen`

Capture the entire screen.

// Parameters (all optional)
{ "display_id": 1, "save_dir": "/path/to/screenshots" }

`screenshot_region`

Capture a specific region.

// Parameters
{ "x": 100, "y": 100, "width": 800, "height": 600 }
// optional: save to file
{ "x": 100, "y": 100, "width": 800, "height": 600, "save_dir": "/path/to/screenshots" }

Platform Support

Platform	Status	Requirements
macOS	✅ Supported	Screen Recording permission
Windows	✅ Supported	PowerShell (built-in)
Linux (X11)	✅ Supported	`xdotool` or `wmctrl` for windows, `gnome-screenshot`/`scrot`/`import` for capture
Linux (Wayland)	⚠️ Partial	GNOME Shell only, `grim` for screenshots

Configuration (Plugin Settings)

Create .claude/screenshot.local.md in your project to set a default save directory:

---
default_save_dir: /Users/yourname/Desktop/screenshots
---

When this file exists, Claude will automatically use this directory for saving screenshots.

Note: Add .claude/*.local.md to your .gitignore.

Requirements

Runtime: Bun v1.0+ or Node.js 18+

macOS

Screen Recording permission (System Settings > Privacy & Security > Screen Recording)

Windows

PowerShell (built-in, no extra installation needed)

Linux (X11)

Window listing: xdotool (recommended) or wmctrl
Screenshots: gnome-screenshot, scrot, or import (ImageMagick)
Display info: xrandr

# Ubuntu/Debian
sudo apt install xdotool scrot

# Fedora
sudo dnf install xdotool scrot

# Arch
sudo pacman -S xdotool scrot

Linux (Wayland)

Window listing: Only GNOME Shell supported (via gdbus)
Screenshots: gnome-screenshot or grim
Display info: wlr-randr or falls back to xrandr

As Claude Code Plugin

Install as a plugin to get the screenshot-testing skill:

# Install from npm
npm install -g screenshot-mcp
claude plugin add screenshot-mcp

# Or use local development
claude --plugin-dir /path/to/screenshot-mcp

The skill provides guidance on:

Effective screenshot testing workflows
Comparison testing strategies
Multi-display testing
Electron app testing examples

License

MIT