Connect ScreenshotRun to AI agents via the MCP Server. Install for Claude Desktop, Claude Code, Cursor, and Windsurf. Take screenshots with natural language.
MCP Server
The ScreenshotRun MCP Server lets AI agents — like Claude, Cursor, or Windsurf — take screenshots, analyze page structure, extract metadata, and check API usage autonomously. Instead of writing code, you just tell the AI "take a screenshot of example.com" or "analyze the page structure" and it does the rest.
MCP (Model Context Protocol) is an open standard for connecting AI models to external tools. By adding the ScreenshotRun MCP server, your AI assistant gets four tools: capturing screenshots, analyzing page structure, extracting page metadata, and monitoring usage quota.
Available Tools
The MCP server exposes four tools to the AI agent:
Tool
Description
take_screenshot
Captures a screenshot of any webpage, raw HTML, or Markdown. Supports all 50+ API parameters — viewport, device emulation, full-page capture, dark mode, retina, format selection, ad/cookie/chat blocking, CSS/JS injection, element targeting, geolocation, stealth mode, PDF output, scroll video, and more. Returns the image as base64 data for the AI to analyze or save.
analyze_page
Analyzes any webpage and returns structured data: headings, interactive elements (buttons, links, inputs), forms, images, and navigation links. Each element includes its bounding rectangle [x, y, width, height] for visual mapping. Supports scoping to specific page sections, visibility filtering, and optional screenshot capture. See Page Analysis for full details.
extract_content
Extracts page metadata from any URL without returning the full image. Returns title, description, Open Graph tags, Twitter Card tags, favicon URL, and HTTP status code. Useful for SEO audits, content analysis, and building link previews.
check_usage
Returns your current quota: screenshots used, remaining, usage percentage, billing period dates. Useful for preventing AI agents from burning through your quota in batch workflows.
Installation
The MCP server is distributed as an npm package: screenshotrun-mcp. No global installation needed — it runs via npx.
Note
You need your API key before setting up. Get it from your dashboard.
Claude Desktop
Add this to your Claude Desktop config file (claude_desktop_config.json):
The take_screenshot tool accepts all ScreenshotRun API parameters. The AI agent picks the right ones based on your natural language request.
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, etc.)
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 to inject (max 10KB)
js
string
Custom JavaScript to execute (max 10KB)
user_agent
string
Custom User-Agent string
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 page load (0-10)
timeout
number
30
Max page load time in seconds (5-60)
navigation_timeout
number
—
Max navigation time in seconds (5-60)
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 to 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 tags, Twitter Card)
certified
boolean
false
Certified screenshot with SHA-256 hash
Geolocation
Parameter
Type
Description
geolocation
object
{latitude, longitude, accuracy?}
timezone
string
IANA timezone, 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
Top margin, 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 a scrolling video of the page
scroll_duration
number
Video duration in seconds (2-30)
scroll_speed
slow | medium | fast
Scroll speed
analyze_page Parameters
The analyze_page tool scans a webpage and returns structured data about its content. The AI agent uses this to understand page layout, find elements, audit SEO/accessibility, and more.
Core
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)
with_screenshot
boolean
false
Capture screenshot alongside analysis (costs 1 extra request)
The extract_content tool extracts page metadata without downloading the full screenshot image. It returns structured data that the AI agent can use for SEO analysis, content audits, or building link previews.
Parameter
Type
Description
url
string
URL to extract metadata from
Returns:
Title — page title from <title> tag
Description — meta description
Open Graph — og:title, og:description, og:image, og:type, og:url, og:site_name
Once the MCP server is connected, you can ask the AI to capture screenshots using natural language. Here are some examples of what you can say:
Basic screenshot
text
Take a screenshot of https://example.com
Mobile screenshot in dark mode
text
Capture https://example.com as it looks on a mobile phone in dark mode
Full-page screenshot
text
Take a full-page screenshot of https://example.com/pricing in WebP format
Render HTML to image
text
Render this HTML as an image: <h1>Hello World</h1><p>This is a test</p>
Screenshot with stealth mode
text
Take a screenshot of cloudflare.com using stealth mode to bypass bot detection
Geo-targeted screenshot
text
Capture google.com as seen from Tokyo, Japan
Analyze page structure
text
Analyze the page structure of competitor.com — show me all headings and interactive elements
Analyze on mobile
text
Analyze example.com/pricing on mobile and list all forms and CTAs
Extract page metadata
text
Extract the OG tags and meta description from competitor.com
Click and capture
text
Click the "Show More" button on example.com/products, then take a screenshot
Visual comparison
text
Take screenshots of stripe.com, paddle.com, and lemonsqueezy.com. Compare their pricing page designs.
Check remaining quota
text
How many screenshots do I have left this month?
How It Works Under the Hood
The AI decides to use the take_screenshot, analyze_page, or extract_content tool based on your request.
The MCP server sends a capture request to the ScreenshotRun API.
It polls for completion (every 2 seconds, up to 60 seconds timeout).
Once ready, the image is downloaded and returned to the AI as base64 data, or structured data is returned as text (for analyze_page and extract_content).
The AI can then analyze the image, compare it with others, or save it to disk.
Security
Your API key is stored in the MCP config file and passed as an environment variable. It is never sent to the AI model itself.
The MCP server only communicates with api.screenshotrun.com — no data is sent elsewhere.
Each screenshot captured by the AI agent counts toward your plan quota, just like any other API request.