# 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`):
```json
{
"mcpServers": {
"screenshot": {
"command": "bunx",
"args": ["screenshot-mcp"]
}
}
}
```
Or with npx:
```json
{
"mcpServers": {
"screenshot": {
"command": "npx",
"args": ["-y", "screenshot-mcp"]
}
}
}
```
### Run Standalone
```bash
# Using bunx (recommended)
bunx screenshot-mcp
# Using npx
npx -y screenshot-mcp
```
## MCP Tools
### `list_windows`
List all visible windows.
```json
// Response
[
{ "id": "1234", "title": "VS Code", "app": "Code", "bounds": { "x": 0, "y": 25, "width": 1920, "height": 1055 } }
]
```
### `list_displays`
List all available displays.
```json
// 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.
```json
// 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.
```json
// Parameters (all optional)
{ "display_id": 1, "save_dir": "/path/to/screenshots" }
```
### `screenshot_region`
Capture a specific region.
```json
// 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:
```markdown
---
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`
```bash
# 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:
```bash
# 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
