Universal Screenshot MCP

Install

Config snippet generator goes here (5 client tabs)

README

# Universal Screenshot MCP

[![npm version](https://img.shields.io/npm/v/universal-screenshot-mcp.svg)](https://www.npmjs.com/package/universal-screenshot-mcp)
[![MCP Registry](https://img.shields.io/badge/MCP_Registry-io.github.sethbang%2Fscreenshot--server-blue)](https://registry.modelcontextprotocol.io)
[![License](https://img.shields.io/badge/license-Apache--2.0-green.svg)](LICENSE)

An [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) server that provides AI assistants with screenshot capabilities — both web page capture via [Puppeteer](https://pptr.dev/) 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

```bash
# 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

```bash
npm install -g universal-screenshot-mcp
```

Or run directly with `npx`:

```bash
npx universal-screenshot-mcp
```

### Install from Source

```bash
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`:

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

Or if installed from source:

```json
{
  "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