Universal Screenshot MCP

Universal Screenshot MCP

An MCP (Model Context Protocol) server that provides AI assistants with screenshot capabilities — both web page capture via Puppeteer and cross-platform system screenshots using native OS tools.

Features

• Web Page Screenshots — Capture any public URL using a headless Chromium browser
• Cross-Platform System Screenshots — Fullscreen, window, or region capture using native OS tools (macOS screencapture, Linux maim/scrot/gnome-screenshot/etc., Windows PowerShell+.NET)
• Security-First Design — SSRF prevention, path traversal protection, DNS rebinding defense, command injection prevention, and DoS limiting
• MCP Native — Integrates directly with Claude Desktop, Cursor, and any MCP-compatible client

Requirements

• Node.js >= 18.0.0
• Chromium is downloaded automatically by Puppeteer on first run

Platform-Specific Requirements for take_system_screenshot

Platform	Required Tools	Notes
macOS	screencapture (built-in)	No additional installation needed
Linux	One of: maim, scrot, gnome-screenshot, spectacle, grim, or import (ImageMagick)	maim or scrot recommended for full feature support. For window-by-name capture, also install xdotool.
Windows	powershell (built-in)	Uses .NET System.Drawing — no additional installation needed

Linux Installation Examples

# Ubuntu/Debian (recommended)
sudo apt install maim xdotool

# Fedora
sudo dnf install maim xdotool

# Arch Linux
sudo pacman -S maim xdotool

# Wayland (Sway, etc.)
sudo apt install grim

Quick Start

Install from npm

npm install -g universal-screenshot-mcp

Or run directly with npx:

npx universal-screenshot-mcp

Install from Source

git clone https://github.com/sethbang/mcp-screenshot-server.git
cd mcp-screenshot-server
npm install
npm run build

Configure Your MCP Client

Add the server to your MCP client configuration. For Claude Desktop, edit ~/Library/Application Support/Claude/claude_desktop_config.json:

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

Or if installed from source:

{
  "mcpServers": {
    "screenshot-server": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-screenshot-server/build/index.js"]
    }
  }
}

For Cursor or other MCP clients, consult their documentation for the equivalent configuration.

Tools

The server exposes two MCP tools:

take_screenshot

Captures a web page (or a specific element) via a headless Puppeteer browser.

Parameter	Type	Required	Description
url	string	✅	URL to capture (http/https only)
width	number	—	Viewport width (1–3840)
height	number	—	Viewport height (1–2160)
fullPage	boolean	—	Capture the full scrollable page
selector	string	—	CSS selector to capture a specific element
waitForSelector	string	—	Wait for this selector before capturing
waitForTimeout	number	—	Delay in milliseconds (0–30000)
outputPath	string	—	Output file path (default: ~/Desktop/Screenshots)

Example prompt:

Take a screenshot of https://example.com at 1920x1080

take_system_screenshot

Captures the desktop, a specific application window, or a screen region using native OS tools. Works on macOS, Linux, and Windows.

Parameter	Type	Required	Description
mode	enum	✅	fullscreen, window, or region
windowId	number	—	Window ID for window mode
windowName	string	—	App name (e.g. "Safari", "Firefox") for window mode
region	object	—	{ x, y, width, height } for region mode
display	number	—	Display number for multi-monitor setups
includeCursor	boolean	—	Include the mouse cursor in the capture
format	enum	—	png (default) or jpg
delay	number	—	Capture delay in seconds (0–10)
outputPath	string	—	Output file path (default: ~/Desktop/Screenshots)

Cross-Platform Feature Support

Feature	macOS	Linux	Windows
Fullscreen	✅	✅	✅
Region	✅	✅ (maim, scrot, grim, import)	✅
Window by name	✅	⚠️ X11 + xdotool	⚠️ best-effort
Window by ID	✅	✅ X11 only	⚠️ HWND
Multi-display	✅	⚠️ tool-dependent	✅
Include cursor	✅	⚠️ tool-dependent	⚠️
Delay	✅	✅	✅

Example prompt:

Take a system screenshot of the Safari window

Output Directories

Screenshots are saved to ~/Desktop/Screenshots by default. Custom output paths must resolve to one of these allowed directories:

Directory	Description
~/Desktop/Screenshots	Default output location
~/Downloads	User downloads folder
~/Documents	User documents folder
/tmp	System temp directory

Security

This server implements multiple layers of security hardening:

ID	Threat	Mitigation
SEC-001	SSRF / DNS rebinding	URLs validated against blocked IP ranges; DNS resolved pre-request with IP pinning via --host-resolver-rules; navigation redirects re-validated
SEC-003	Command injection	All subprocesses use execFile (no shell); app names validated against SAFE_APP_NAME_PATTERN
SEC-004	Path traversal	Output paths validated with fs.realpath() symlink resolution; restricted to allowed directories
SEC-005	Denial of service	Concurrent Puppeteer instances limited to 3 via semaphore

For full details, see docs/security.md.

Development

Scripts

Command	Description
npm run build	Compile TypeScript to build/
npm run watch	Recompile on file changes
npm test	Run tests with Vitest
npm run test:watch	Run tests in watch mode
npm run test:coverage	Run tests with coverage report
npm run lint	Lint source with ESLint
npm run inspector	Launch MCP Inspector for debugging

Project Structure

src/
├── index.ts                 # Entry point — stdio transport
├── server.ts                # MCP server factory
├── config/
│   ├── index.ts             # Static constants (limits, allowed dirs)
│   └── runtime.ts           # Singleton semaphore, default directory
├── tools/
│   ├── take-screenshot.ts   # Web page capture tool
│   └── take-system-screenshot.ts  # macOS system capture tool
├── types/
│   └── index.ts             # Shared TypeScript interfaces
├── utils/
│   ├── helpers.ts           # Response builders, file utilities
│   ├── screenshot-provider.ts # Cross-platform provider interface + factory
│   ├── macos-provider.ts    # macOS: screencapture wrapper
│   ├── linux-provider.ts    # Linux: maim/scrot/gnome-screenshot/etc.
│   ├── windows-provider.ts  # Windows: PowerShell + .NET System.Drawing
│   ├── macos.ts             # Window ID lookup via CoreGraphics
│   └── semaphore.ts         # Async concurrency limiter
└── validators/
    ├── path.ts              # Output path validation (SEC-004)
    └── url.ts               # URL/SSRF validation (SEC-001)

Testing

Tests use Vitest with full dependency injection — no real network calls, filesystem access, or subprocess execution in tests.

npm test

Debugging with MCP Inspector

npm run inspector

This launches the MCP Inspector connected to your built server, allowing you to invoke tools interactively.

License

Apache-2.0 — Copyright 2026 Seth Bang