screenshotrun-mcp

Give your AI agent the ability to see any webpage. MCP server for ScreenshotRun Screenshot API.

Features

• Capture screenshots of any public webpage as PNG, JPEG, WebP, or PDF
• Render raw HTML or Markdown to image
• Device emulation — desktop, mobile, and tablet viewports
• Dark mode rendering with prefers-color-scheme: dark
• Full-page capture with automatic scrolling
• Block ads, cookie consent banners, and live chat widgets
• Inject custom CSS/JavaScript before capture
• Target specific elements with CSS selectors
• Wait for elements, click, hover, and scroll before capture
• Retina (2x) and custom device pixel ratio support
• Geolocation and timezone emulation
• Stealth mode to avoid bot detection
• Transparent background, clipping, and output resizing
• Extract page metadata (title, description, OG tags, Twitter Card)
• Analyze page structure — headings, interactive elements, forms, images, navigation with bounding rectangles
• Certified screenshots with SHA-256 hash
• PDF output with custom page format and margins
• Scroll video recording
• Monitor your API usage and remaining quota

Quick Start

1. Get your API key

Sign up for a free API key at screenshotrun.com.

2. Configure your AI client

Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows):

{
  "mcpServers": {
    "screenshotrun": {
      "command": "npx",
      "args": ["-y", "screenshotrun-mcp"],
      "env": {
        "SCREENSHOTRUN_API_KEY": "sr_live_your_key_here"
      }
    }
  }
}

Claude Code

claude mcp add screenshotrun \
  npx -y screenshotrun-mcp \
  -e SCREENSHOTRUN_API_KEY=sr_live_your_key_here

Cursor

Add to .cursor/mcp.json in your project:

{
  "mcpServers": {
    "screenshotrun": {
      "command": "npx",
      "args": ["-y", "screenshotrun-mcp"],
      "env": {
        "SCREENSHOTRUN_API_KEY": "sr_live_your_key_here"
      }
    }
  }
}

Windsurf / VS Code

Add to your MCP configuration with the same npx -y screenshotrun-mcp command and set the SCREENSHOTRUN_API_KEY environment variable.

Available Tools

take_screenshot

Capture a screenshot of any webpage, raw HTML, or Markdown. Returns the image as base64-encoded data that AI agents can analyze and describe.

Source (one required)

Parameter	Type	Description
url	string	URL to screenshot (http:// or https://)
html	string	Raw HTML to render (max 500KB)
markdown	string	Markdown to render (max 500KB)

Output

Parameter	Type	Default	Description
format	png | jpeg | webp | pdf	png	Output format
quality	number	80	Image quality for JPEG/WebP (1-100)

Viewport & Device

Parameter	Type	Default	Description
width	number	1280	Viewport width (320-3840)
height	number	800	Viewport height (200-2160)
full_page	boolean	false	Capture entire scrollable page
device	desktop | mobile | tablet	--	Device preset
retina	boolean	false	2x resolution
device_scale_factor	number	--	Custom pixel ratio (0.5-4)

Appearance

Parameter	Type	Default	Description
dark_mode	boolean	false	Enable dark mode
omit_background	boolean	false	Transparent background (PNG/WebP)
media_type	screen | print	--	Emulate CSS media type
reduced_motion	boolean	false	Emulate prefers-reduced-motion
disable_animations	boolean	false	Disable CSS animations

Blocking

Parameter	Type	Default	Description
block_ads	boolean	false	Block advertisements
block_cookies	boolean	true	Block cookie consent dialogs
block_chats	boolean	false	Block live chat widgets
block_requests	string[]	--	URL patterns to block
block_resources	string[]	--	Resource types to block (image, stylesheet, font, script, media, websocket, manifest, other)

Interaction

Parameter	Type	Description
selector	string	CSS selector to capture a specific element
click_selector	string	Element to click before capture
hover_selector	string	Element to hover before capture
scroll_to	string	Element to scroll into view
hide_selectors	string[]	Elements to hide before capture
wait_for_selector	string	Wait for element to appear

Injection

Parameter	Type	Description
css	string	Custom CSS (max 10KB)
js	string	Custom JavaScript (max 10KB)
user_agent	string	Custom User-Agent
headers	object	Custom HTTP headers
cookies	array	Cookies to set ({name, value, domain?})

Timing

Parameter	Type	Default	Description
delay	number	0	Seconds to wait after load (0-10)
timeout	number	30	Max page load time (5-60s)
navigation_timeout	number	--	Max navigation time (5-60s)
wait_until	string	--	load, domcontentloaded, networkidle, or commit

Clipping & Resizing

Parameter	Type	Description
resize_width	number	Resize output width (16-3840)
resize_height	number	Resize output height (16-2160)
clip	object	Clip rectangle {x, y, width, height}

Advanced

Parameter	Type	Default	Description
stealth	boolean	false	Stealth mode (avoid bot detection)
bypass_csp	boolean	false	Bypass Content Security Policy
cache_ttl	number	--	Cache duration in seconds (0-86400)
extract_metadata	boolean	false	Extract page metadata (title, OG, Twitter Card)
certified	boolean	false	Certified screenshot with SHA-256

Geolocation

Parameter	Type	Description
geolocation	object	{latitude, longitude, accuracy?}
timezone	string	e.g. America/New_York
proxy	string	HTTP/SOCKS proxy URL

PDF Options (format=pdf)

Parameter	Type	Description
pdf_landscape	boolean	Landscape orientation
pdf_page_format	string	A3, A4, A5, Letter, Legal, Tabloid
pdf_margin_top	string	e.g. 1cm, 0.5in
pdf_margin_right	string	Right margin
pdf_margin_bottom	string	Bottom margin
pdf_margin_left	string	Left margin

Scroll Video

Parameter	Type	Description
scroll_video	boolean	Record scrolling video
scroll_duration	number	Duration 2-30 seconds
scroll_speed	slow | medium | fast	Scroll speed

analyze_page

Analyze any webpage and get structured data about its content. Returns headings, interactive elements (buttons, links, inputs), forms, images, and navigation links — each with a bounding rectangle [x, y, width, height] for visual mapping. Pro feature with 20 free trial runs per month.

Core Parameters

Parameter	Type	Default	Description
url	string	required	URL to analyze (http:// or https://)
include	string[]	all	Categories to return: headings, interactive, forms, images, text, navigation
visible_only	boolean	true	Only return visible elements
scope	string	--	CSS selector to limit analysis to a section (e.g. main, #content)
with_screenshot	boolean	false	Capture screenshot alongside analysis (costs 1 extra request)

Viewport & Appearance

Parameter	Type	Default	Description
width	number	1280	Viewport width (320-3840)
height	number	800	Viewport height (200-2160)
device	desktop | mobile | tablet	--	Device preset
dark_mode	boolean	false	Enable dark mode

Blocking & Timing

Parameter	Type	Default	Description
block_ads	boolean	false	Block advertisements
block_cookies	boolean	true	Block cookie consent dialogs
block_chats	boolean	false	Block live chat widgets
delay	number	0	Seconds to wait after load (0-10)
timeout	number	30	Max page load time (5-60s)
stealth	boolean	false	Stealth mode

Injection & Advanced

Parameter	Type	Description
css	string	Custom CSS (max 10KB)
js	string	Custom JavaScript (max 10KB)
hide_selectors	string[]	Elements to hide before analysis
wait_for_selector	string	Wait for element to appear
user_agent	string	Custom User-Agent
proxy	string	HTTP/SOCKS proxy URL
timezone	string	e.g. America/New_York
geolocation	object	{latitude, longitude, accuracy?}
headers	object	Custom HTTP headers
cookies	array	Cookies to set ({name, value, domain?})

extract_content

Extract page metadata from any URL without downloading the full image. Returns title, description, Open Graph tags, Twitter Card tags, favicon URL, and HTTP status. Useful for SEO audits, content analysis, and link previews.

Parameter	Type	Description
url	string	URL to extract metadata from

check_usage

Check your ScreenshotRun API usage for the current billing period. Returns screenshots used, remaining quota, usage percentage, and days remaining.

No parameters required.

Example Prompts

• "Take a screenshot of screenshotrun.com"
• "Screenshot stripe.com on mobile in dark mode"
• "Capture full-page screenshot of my website in WebP"
• "Take a retina screenshot of example.com in JPEG format"
• "Screenshot a page with the cookie banner and chat widget hidden"
• "Render this HTML as an image: <h1>Hello World</h1>"
• "Capture example.com as seen from Tokyo" (with geolocation + timezone)
• "Take a screenshot with transparent background for my design comp"
• "Wait for the .loading-spinner to disappear, then screenshot"
• "Click the 'Show More' button, then capture the page"
• "Analyze the page structure of competitor.com — show me all headings and interactive elements"
• "What forms and images are on this landing page?"
• "Analyze example.com on mobile and show me the navigation links"
• "Extract the OG tags and meta description from competitor.com"
• "Check how many screenshots I have left this month"

How It Works

1. Your AI agent receives a user request involving a webpage
2. The agent calls the appropriate tool (take_screenshot, analyze_page, or extract_content)
3. The MCP server sends the request to the ScreenshotRun API
4. The API renders the page in a real browser and returns the result
5. Screenshots are returned as base64 images; analysis results are returned as structured text with element positions

Requirements

• Node.js 18+
• A ScreenshotRun API key (get one free)

Other Projects by ScreenshotRun

• SnapshotArchive — Automated website monitoring with visual diff detection
• WatchCron — Cron job & heartbeat monitoring for developers

License

MIT