SC
OfficialDeveloper Tools

ScreenshotMCP MCP Server: Full-Page, Element, Device Screenshots

Capture full-page, element, and device-size screenshots with an MCP server for fast, automated website image capture and testing.

View on GitHub
Quick Install
npx -y @upnorthmedia/ScreenshotMCP

Overview

ScreenshotMCP is an MCP (Model Context Protocol) server that automates website image capture. It runs a headless Chromium instance to take full-page screenshots, snapshots of specific DOM elements, and device-size renders (mobile, tablet, desktop). The server exposes a small set of tools you can call from MCP-capable clients (e.g., Claude Code, Cursor) or via a programmatic HTTP/MCP interface, letting you embed fast, repeatable screenshot capture into testing, monitoring, or content workflows.

Designed for reliability and safety, ScreenshotMCP includes viewport presets, configurable wait conditions (selectors, network idle, timeouts), input validation, and rate-limiting. This makes it suitable for automated visual testing, documentation generation, and ad-hoc captures where you need consistent, reproducible images of web pages.

Features

  • Full-page screenshots with automatic scrolling and stitching
  • Element-only captures via CSS selectors
  • Built-in device presets: mobile, tablet, desktop
  • Custom viewport configuration (width, height, device scale)
  • Wait strategies: selector, function, timeout, network idle
  • Extra delay option before capture
  • Input validation and URL sanitization (HTTP/HTTPS only)
  • Rate limiting and concurrent job limits
  • Debug and verbose logging modes
  • Simple MCP integration examples for Claude and Cursor

Installation / Configuration

Basic install:

# clone repo
git clone https://github.com/upnorthmedia/ScreenshotMCP.git
cd ScreenshotMCP

# copy environment template
cp .env.example .env

# install dependencies and start
npm install
npm start

Environment variables (example .env keys):

# Browser / runtime
BROWSER_HEADLESS=true
BROWSER_TIMEOUT=30000
MAX_CONCURRENT_SCREENSHOTS=5

# Defaults
DEFAULT_VIEWPORT_WIDTH=1920
DEFAULT_VIEWPORT_HEIGHT=1080
DEFAULT_WAIT_TIMEOUT=10000

# Rate limiting
RATE_LIMIT_REQUESTS=100
RATE_LIMIT_WINDOW=60000

# Debugging
DEBUG=false
LOG_LEVEL=info

Register as an MCP server (Claude Code CLI example):

{
  "screenshot-full-page-mcp": {
    "command": "node",
    "args": ["/path/to/screenshot-full-page-mcp/index.js"]
  }
}

Cursor IDE (Settings → MCP Servers) accepts the same JSON entry.

Available Tools

capture_screenshot

  • Purpose: Capture a full-page screenshot or a viewport-limited image.
  • Key params:
    • url (string, required)
    • viewport: { preset, width, height, deviceScaleFactor, isMobile, hasTouch }
    • waitFor: { type: “selector”|“function”|“timeout”|“networkidle”, value, timeout }
    • delay (ms)
    • waitUntil (e.g., “load”, “domcontentloaded”, “networkidle0”)

capture_element

  • Purpose: Capture a screenshot of a single DOM element.
  • Key params:
    • url (string, required)
    • selector (string, required) — CSS selector for the element
    • viewport (same as above)
    • waitFor (optional)

list_device_presets

  • Purpose: Return built-in presets and their values.

Wait types explained:

  • selector — wait until the CSS selector is present/visible
  • function — evaluate a page function that returns true
  • timeout — wait a fixed number of milliseconds
  • networkidle — wait until network activity subsides

Device Presets

PresetWidthHeightScaleMobileTouch
mobile375px667px2xYesYes
tablet768px1024px2xYesYes
desktop1920px1080px1xNoNo

Custom viewports are allowed (width/height in range 100–5000).

Use Cases

  • Visual regression testing: capture full pages across branches or deployments using the same viewport and wait conditions. Example command (natural language to Claude Code): “Take a full-page screenshot of https://example.com once the .loaded element exists.”

  • Component snapshots: record the visual output of a specific element for component snapshots. Example payload:

    {
  "tool": "capture_element",
  "url": "https://example.com",
  "selector": "#main-hero",
  "viewport": { "preset": "desktop" }
}

  • Responsive checks: generate mobile/tablet/desktop screenshots with the presets or custom sizes to validate responsive layouts.

  • Monitoring and uptime screenshots: periodically capture a page and save images for change detection or incident context. Use rate limiting and concurrency settings to avoid overload.

  • Troubleshooting dynamic content: wait for a CSS selector or a network idle state before capture to ensure content is fully rendered (useful for SPAs and lazy-loaded assets).

Tips and Troubleshooting

  • If Chromium fails to launch, ensure required system libraries and enough memory are available. Try BROWSER_HEADLESS=false to debug visually.
  • Increase BROWSER_TIMEOUT when targets are slow or large.
  • Reduce MAX_CONCURRENT_SCREENSHOTS if you see memory pressure.
  • Enable DEBUG=true in .env for verbose logs.

For source, issues, and contributions, see the repository on GitHub.

Tags:developer-tools