The MCP Screenshot Server allows you to capture screenshots of web pages and local HTML files through a simple MCP tool interface with customizable options:
Capture Screenshots: Take screenshots by providing a URL or path to a local HTML file
Configurable Viewport: Adjust the width and height dimensions for the screenshot
Full Page Capture: Optionally capture the entire scrollable page instead of just the viewport
Custom Output Path: Specify where to save the screenshot file
Automatic Directory Management: The server handles screenshot storage directory organization
Allows capturing screenshots of websites and local HTML files through Puppeteer with configurable viewport dimensions, full page capture support, and custom output paths.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@MCP Screenshot Server take a screenshot of https://example.com with width 1200 and full page"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
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
Related MCP server: Webpage Screenshot MCP Server
Node.js >= 18.0.0
Chromium is downloaded automatically by Puppeteer on first run
take_system_screenshotPlatform | Required Tools | Notes |
macOS |
| No additional installation needed |
Linux | One of: |
|
Windows |
| Uses .NET |
# 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 grimAfter installing, you can verify your setup with:
npx universal-screenshot-mcp --doctorThis probes the host and prints copy-pasteable install commands for any missing tools, tailored to your detected distro.
npm install -g universal-screenshot-mcpOr run directly with npx:
npx universal-screenshot-mcpgit clone https://github.com/sethbang/mcp-screenshot-server.git
cd mcp-screenshot-server
npm install
npm run buildAdd 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 Claude Code, register the server with the claude mcp add command:
# Project scope (current directory only)
claude mcp add screenshot-server -- npx -y universal-screenshot-mcp
# User scope (available across all projects)
claude mcp add --scope user screenshot-server -- npx -y universal-screenshot-mcpOr if installed from source:
claude mcp add screenshot-server -- node /absolute/path/to/mcp-screenshot-server/build/index.jsVerify the server registered with claude mcp list, or check live status from inside a session with /mcp.
For Cursor or other MCP clients, consult their documentation for the equivalent configuration.
The server exposes two MCP tools:
take_screenshotCaptures a web page (or a specific element) via a headless Puppeteer browser.
Parameter | Type | Required | Description |
| string | ✅ | URL to capture (http/https only) |
| number | — | Viewport width (1–3840) |
| number | — | Viewport height (1–2160) |
| boolean | — | Capture the full scrollable page |
| string | — | CSS selector to capture a specific element |
| string | — | Wait for this selector before capturing |
| number | — | Delay in milliseconds (0–30000) |
| string | — | Output file path (default: |
Example prompt:
Take a screenshot of https://example.com at 1920x1080
take_system_screenshotCaptures the desktop, a specific application window, or a screen region using native OS tools. Works on macOS, Linux, and Windows.
Parameter | Type | Required | Description |
| enum | ✅ |
|
| number | — | Window ID for window mode |
| string | — | App name (e.g. |
| object | — |
|
| number | — | Display number for multi-monitor setups |
| boolean | — | Include the mouse cursor in the capture |
| enum | — |
|
| number | — | Capture delay in seconds (0–10) |
| string | — | Output file path (default: |
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
Variable | Default | Description |
|
| Default output directory relative to |
|
| Set to |
Screenshots are saved to ~/Documents/screenshots by default (configurable via SCREENSHOT_OUTPUT_DIR). Custom output paths must resolve to one of these allowed directories:
Directory | Description |
| Default output location (configurable) |
| Original default location |
| User downloads folder |
| User documents folder |
| System temp directory |
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 |
SEC-003 | Command injection | All subprocesses use |
SEC-004 | Path traversal | Output paths validated with |
SEC-005 | Denial of service | Concurrent Puppeteer instances limited to 3 via semaphore |
For full details, see docs/security.md.
Command | Description |
| Compile TypeScript to |
| Recompile on file changes |
| Unit tests (fast, fully mocked) |
| Integration tests (real DNS/filesystem) |
| E2E tests (real Puppeteer/native tools) |
| All test tiers together |
| Linux e2e via Docker (requires Docker) |
| Run tests in watch mode |
| Run tests with coverage report |
| Lint source with ESLint |
| Launch MCP Inspector for debugging |
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)Tests use Vitest in three tiers:
Unit (npm test) — Full dependency injection, no real I/O. Fast feedback loop.
Integration (npm run test:integration) — Real DNS resolution, real filesystem with temp directories, real Puppeteer against a local HTTP server.
E2E (npm run test:e2e) — Real native screenshot tools. macOS tests run natively; Linux tests run in Docker via npm run test:linux.
npm test # Unit tests (~300ms)
npm run test:linux # Linux provider tests in Docker
npm run test:all # Everythingnpm run inspectorThis launches the MCP Inspector connected to your built server, allowing you to invoke tools interactively.
Apache-2.0 — Copyright 2026 Seth Bang
Capture web page or element via headless browser. Saves to ~/Documents/screenshots by default (configurable via SCREENSHOT_OUTPUT_DIR env var).
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | URL to capture | |
| width | No | Viewport width | |
| height | No | Viewport height | |
| fullPage | No | Capture full page | |
| selector | No | CSS selector for element | |
| waitForSelector | No | Wait for selector | |
| waitForTimeout | No | Delay in ms | |
| outputPath | No | Absolute path, or relative to home dir |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden but only mentions method and save location; it omits critical behavioral traits like destructiveness, permission needs, or return value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences: first states purpose, second details save behavior. Front-loaded and no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite 8 parameters and no output schema, the description omits return value, error handling, and other essential context, leaving significant gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers all 8 parameters with descriptions, so baseline is 3. The description adds the default save path and env var override, providing marginal extra context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses specific verb 'capture' and resource 'web page or element' with method 'via headless browser', clearly distinguishing it from sibling 'take_system_screenshot' which captures system screens.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for web screenshots but does not explicitly state when to use versus alternatives, nor does it mention prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Capture desktop, window, or region screenshot. Cross-platform: macOS (screencapture), Linux (maim/scrot/gnome-screenshot/etc.), Windows (PowerShell+.NET). Saves to ~/Documents/screenshots by default (configurable via SCREENSHOT_OUTPUT_DIR env var). For window mode, provide windowName (app name like "Safari") or windowId.
| Name | Required | Description | Default |
|---|---|---|---|
| mode | Yes | fullscreen=entire screen, window=specific app (requires windowName or windowId), region=coordinates | |
| windowId | No | Window ID (for window mode) | |
| windowName | No | App name like "Safari", "Firefox" (for window mode) | |
| region | No | Region {x,y,width,height} | |
| display | No | Display number | |
| includeCursor | No | Include cursor | |
| format | No | Image format (png or jpg) | |
| delay | No | Delay seconds | |
| outputPath | No | Absolute path, or relative to home dir |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden. It discloses the default save location and cross-platform tool dependencies but does not mention return behavior (e.g., file path or binary), permission requirements, or failure modes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with 4 sentences, front-loading the main action. It effectively uses bullet-like information for cross-platform details and mode instructions, though it could be slightly more structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 9 parameters including a nested object and no output schema, the description covers default directory and platform support but omits return value, error handling, and comparison with the sibling tool. It is adequate but not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds minor value by specifying default output directory and that windowName is an app name, but the schema already describes all parameters adequately.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Capture desktop, window, or region screenshot' with specific verb and resource. It distinguishes from the sibling tool 'take_screenshot' by specifying cross-platform support and modes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use each mode (fullscreen, window, region) and gives examples for window mode. However, it lacks guidance on when not to use this tool versus the sibling 'take_screenshot', missing explicit exclusion or alternative differentiation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The two tools are clearly distinct: one captures web pages/elements via headless browser, the other captures desktop/system screenshots. There is no overlap in functionality.
Both tools follow a consistent verb_noun pattern with snake_case (take_screenshot, take_system_screenshot), using the same 'take_' prefix.
Only 2 tools for a screenshot server is minimal but still covers the core use cases. More tools might be expected for management or configuration, but the count is not severely inadequate.
The tool set covers the primary screenshot domains (web and system). Minor gaps exist, such as listing or deleting screenshots, but core functionality is well-covered.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Screenshot any URL/HTML as PNG/JPEG/WebP, or read it as clean Markdown/text for LLMs.
Screenshot, PDF, OG-image, and page extraction (markdown/JSON) over MCP. Bearer key or x402.
Screenshot and HTML render MCP server for AI agents
Screenshot, diff, audit and sitemap-capture any web page — 5 MCP tools for AI agents.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/sethbang/mcp-screenshot-server'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
