screenshotapi-mcp
OfficialScreenshotAPI MCP Server
Official MCP server for ScreenshotAPI. It gives your AI assistant 8 tools for website screenshots, URL and HTML to PDF, scrolling videos, JavaScript-aware web scraping (Markdown, text, HTML), and bulk captures. You ask in plain English and the server makes the API calls. Your assistant also gets the screenshot back as an image, so it can see the page it captured.
Works with Claude Desktop, Claude Code, Cursor, Windsurf, VS Code, Cline, Codex, and any other MCP-compatible client.
Item | Value |
Package |
|
Transport |
|
Node.js |
|
Quick Start
Sign up for ScreenshotAPI and copy your API key from the dashboard.
Cursor users can install in one click:
Everyone else: add this to your MCP client config (see Install by Client for the exact file path):
{
"mcpServers": {
"screenshotapi": {
"command": "npx",
"args": ["-y", "@screenshotapinet/mcp"],
"env": {
"SCREENSHOTAPI_TOKEN": "<YOUR_API_KEY>"
}
}
}
}Restart your client.
Test it: ask "Take a screenshot of https://example.com"
Related MCP server: Screenshot MCP
Table of Contents
Install by Client
Requirements
Node.js 18 or later
npxavailable in your terminalA ScreenshotAPI API key (sign up)
Claude Desktop
Add to claude_desktop_config.json (Settings → Developer → Edit Config):
{
"mcpServers": {
"screenshotapi": {
"command": "npx",
"args": ["-y", "@screenshotapinet/mcp"],
"env": {
"SCREENSHOTAPI_TOKEN": "<YOUR_API_KEY>"
}
}
}
}Restart Claude Desktop after saving.
Claude Code
claude mcp add screenshotapi --env SCREENSHOTAPI_TOKEN=<YOUR_API_KEY> -- npx -y @screenshotapinet/mcpStart a new Claude Code session after adding the server.
Cursor
One-click install:
Or add to .cursor/mcp.json manually:
{
"mcpServers": {
"screenshotapi": {
"command": "npx",
"args": ["-y", "@screenshotapinet/mcp"],
"env": {
"SCREENSHOTAPI_TOKEN": "<YOUR_API_KEY>"
}
}
}
}Restart Cursor after saving.
Windsurf
Add to ~/.codeium/windsurf/mcp_config.json:
{
"mcpServers": {
"screenshotapi": {
"command": "npx",
"args": ["-y", "@screenshotapinet/mcp"],
"env": {
"SCREENSHOTAPI_TOKEN": "<YOUR_API_KEY>"
}
}
}
}Restart Windsurf after saving.
VS Code / GitHub Copilot
Add to your VS Code settings.json:
{
"mcp": {
"servers": {
"screenshotapi": {
"command": "npx",
"args": ["-y", "@screenshotapinet/mcp"],
"env": {
"SCREENSHOTAPI_TOKEN": "<YOUR_API_KEY>"
}
}
}
}
}Restart VS Code after saving.
Cline
Open MCP Servers panel → Configure → Advanced MCP Settings. Add to cline_mcp_settings.json:
{
"mcpServers": {
"screenshotapi": {
"command": "npx",
"args": ["-y", "@screenshotapinet/mcp"],
"env": {
"SCREENSHOTAPI_TOKEN": "<YOUR_API_KEY>"
}
}
}
}Restart Cline after saving.
Codex CLI
codex mcp add screenshotapi --env SCREENSHOTAPI_TOKEN=<YOUR_API_KEY> -- npx -y @screenshotapinet/mcp
codex mcp listStart a new Codex session after adding the server.
Any Other MCP Client
Use this config:
{
"command": "npx",
"args": ["-y", "@screenshotapinet/mcp"],
"env": {
"SCREENSHOTAPI_TOKEN": "<YOUR_API_KEY>"
}
}Verify It Works
Try these after setup:
Prompt | Expected tool |
Take a screenshot of https://example.com |
|
Screenshot stripe.com on an iPhone-sized screen in dark mode |
|
Capture the full page of https://news.ycombinator.com without ads |
|
Save https://example.com/invoice as an A4 PDF to ./invoice.pdf |
|
Read https://react.dev/learn and summarize it |
|
Make a 10-second scrolling GIF of https://apple.com |
|
Screenshot these 5 competitor homepages |
|
Is bulk job 1f2e... done yet? |
|
Tool Reference
All 8 tools wrap the ScreenshotAPI REST API. The render tools (take_screenshot, generate_pdf, scrape_page, record_scrolling_video) call GET https://shot.screenshotapi.net/v3/screenshot with output=json and share the page preparation options below. Each takes either url or custom_html.
Shared render options
Group | Parameters |
Viewport |
|
Timing |
|
Page manipulation |
|
Blocking |
|
Emulation |
|
Caching |
|
Storage |
|
take_screenshot
Captures a page as an image and returns the hosted image URL. The image is also returned inline so the assistant can see it. Full-page captures are the exception, since they are usually too tall to view; pass include_image=true to get them inline anyway.
Parameter | Required | Description |
| One of | URL to capture |
| One of | Raw HTML to render instead of a URL |
| No |
|
| No | Capture the whole scrollable page. Default |
| No | 2x pixel density. Default |
| No | JPEG quality 0-100. Default 80 |
| No | Transparent background for plain-background pages (PNG only) |
| No | Resize output to this width, keeping aspect ratio |
| No | Capture a single element by CSS selector |
| No | Capture a rectangle: |
| No | Capture at several viewport sizes in one request: |
| No | Return the image inline. Default |
| No | Also save the file locally |
Plus all shared render options.
generate_pdf
Converts a URL or raw HTML to PDF and returns the hosted PDF URL. With no format (and no width/height), the whole page becomes one continuous PDF page.
Parameter | Required | Description |
| One of | URL to convert |
| One of | Raw HTML to convert |
| No |
|
| No | Landscape orientation. Default |
| No | Keep only these pages, e.g. |
| No | Include background colors and images |
| No |
|
| No | Also save the PDF locally |
Plus all shared render options.
scrape_page
Renders the page in a real browser, so JavaScript runs first, then extracts its content. The server downloads the extracted files and returns their contents inline. A screenshot is captured in the same request.
Parameter | Required | Description |
| One of | URL to scrape |
| One of | Raw HTML to process |
| No | Any of |
| No | Return extracted contents inline. Default |
| No | Truncate each extracted file. Default 50000 |
Plus viewport, timing, page manipulation, blocking, and emulation options.
record_scrolling_video
Records the browser scrolling down a page and returns the hosted video URL.
Parameter | Required | Description |
| One of | URL to record |
| One of | Raw HTML to record |
| No |
|
| No |
|
| No | Seconds, 0-60 |
| No | Scroll back to the top at the end |
| No | Start recording before the page finishes loading |
| No | Record the viewport for |
| No | Record at several viewport sizes: |
| No | Also save the video locally (single size only) |
Plus viewport, timing, page manipulation, blocking, and emulation options.
bulk_screenshots
POST https://api.screenshotapi.net/v1/bulk/json submits up to 50 URLs as one job. Paid plans only.
Parameter | Required | Description |
| Yes |
|
| No | Options applied to every entry unless the entry overrides them |
bulk_screenshots_csv
POST https://api.screenshotapi.net/v1/bulk/csv uploads a CSV with a url column. Any other column is a render option for that row. Paid plans only.
Parameter | Required | Description |
| One of | Path to a local CSV file |
| One of | CSV text |
get_bulk_status
GET https://api.screenshotapi.net/v1/bulk/csv/status returns percent_complete, successful_urls, and failed_urls for a job.
Parameter | Required | Description |
| Yes | Job uuid |
download_bulk_results
GET https://api.screenshotapi.net/v1/bulk/csv/download returns one row per URL with url, status, screenshot, and error_message.
Parameter | Required | Description |
| Yes | Job uuid |
Prompt Examples
Screenshots
Take a screenshot of https://linear.app
Screenshot https://github.com on a 390px-wide mobile viewport in dark mode.
Capture the full page of https://vercel.com/pricing with ads and cookie banners blocked.
Grab just the pricing table on https://example.com/pricing (selector
#pricing).Screenshot our staging site and blur anything with the class
.user-email.Show me how https://www.bbc.com looks from Germany in German.
PDFs
Convert https://example.com/report to an A4 landscape PDF and save it to ./report.pdf.
Turn this HTML invoice into a Letter-size PDF.
Export only pages 2-4 of https://docs.example.com/guide as a PDF.
Scraping
Read https://react.dev/learn and give me the key points.
Get the rendered HTML of https://example.com after JavaScript runs.
List every image URL on https://unsplash.com.
Video
Record a slow scrolling MP4 of https://stripe.com that scrolls back to the top.
Make a scrolling GIF of our landing page at desktop and mobile sizes.
Bulk
Screenshot these 20 URLs at 1440x900 with cookie banners hidden.
What's the status of my bulk job, and download the results when it's done.
Error Codes
Tool calls never crash the server. Upstream errors come back as structured tool results with error, code, message, and a guidance field, so the client can explain the problem and suggest a fix.
Code | Meaning |
| Too many redirects on the target URL |
| Invalid parameters (URL, file type, proxy, geolocation, CSS/JS URL, clip, template) or target SSL problems |
| Missing or invalid |
| Service paused for unpaid dues or usage over twice the plan quota |
| Screenshot quota used up, trial expired, or target refused the connection |
| Account is not on a plan or trial |
| Proxy tunnel connection failed |
| Page took too long to render |
| Too many requests per minute |
| Target site closed the connection or returned nothing |
| Target site SSL/TLS version or cipher mismatch |
| This server stopped waiting for the API (see |
| ScreenshotAPI internal error, safe to retry |
| Server could not reach ScreenshotAPI |
| ScreenshotAPI or the target page is temporarily unavailable |
Example error result for a missing URL:
{
"error": "url_required",
"code": 400,
"message": "Provide either 'url' or 'custom_html'.",
"guidance": "Pass a fully qualified URL including the protocol, e.g. 'https://example.com', or pass custom_html instead."
}See the full list in the ScreenshotAPI error docs.
How It Works
This is a stdio MCP server that wraps the ScreenshotAPI REST API.
At runtime:
Your MCP client starts the server process via
npx.The client reads the tool list.
When a prompt matches a tool, the client calls it.
The server validates inputs, calls ScreenshotAPI with
output=json, and returns structured JSON with the hosted file URL.For screenshots, the server also downloads the image and returns it inline. For scraping, it downloads the extracted Markdown, text, or HTML and returns the contents.
The API key is read from the environment on each call and sent as the token parameter. The server strips the token from every response before it reaches the model. Requests with very long values, such as large custom_html, are sent as a POST with a JSON body to avoid URL length limits.
Environment Variables
Variable | Required | Default | Description |
| Yes | Your ScreenshotAPI API key | |
| No |
| Upstream request timeout in ms |
| No |
| Largest screenshot returned inline to the model |
Building from Source
git clone https://github.com/Screenshot-API/screenshot-mcp.git
cd screenshot-mcp
npm install
npm run buildRun it directly:
SCREENSHOTAPI_TOKEN=<YOUR_KEY> node dist/cli.jsInspect with the MCP Inspector:
SCREENSHOTAPI_TOKEN=<YOUR_KEY> npx @modelcontextprotocol/inspector node dist/cli.jsTroubleshooting
Client uses an old tool list after updating: Restart the client and confirm it loaded the latest npm version.
401 token_required: SCREENSHOTAPI_TOKEN is not set in your MCP client config's env block.
401 invalid_token: The key is wrong, or it was rolled in the dashboard. Copy the current key from the dashboard.
Screenshot comes back as a URL but not an image: The image is larger than SCREENSHOTAPI_MAX_INLINE_IMAGE_BYTES, or it was a full_page capture. Use thumbnail_width, jpg with a lower image_quality, or set include_image=true.
Blank or half-loaded pages: Add delay (e.g. 3000), use wait_for_event=networkidle, or set lazy_load=true for pages with lazy images.
Cookie banners or popups in the shot: Pass block: ["cookie_banners", "ads", "chat_widgets"], or remove specific elements with remove_selector.
CAPTCHA or bot blocks: Route the request through a residential proxy. See the proxy docs.
Timeouts: Slow pages may need a higher timeout (API side, default 100000 ms) and a higher SCREENSHOTAPI_REQUEST_TIMEOUT_MS (this server, default 180000 ms). Some MCP clients also have their own tool-call timeout.
Links
License
Available Tools
8 toolsbulk_screenshotsCapture screenshots of many URLsA
Submits up to 50 URLs as one bulk screenshot job (JSON bulk API). Each entry is a URL plus any take_screenshot option using the raw API parameter names (file_type, width, height, full_page, fresh, delay, css, block_ads, no_cookie_banners, ...). 'defaults' are applied to every entry unless the entry overrides them. Returns the API's job response; if it contains a uuid, track it with get_bulk_status and fetch results with download_bulk_results. Paid plans only.
Inputs: screenshots (required), defaults.
bulk_screenshots_csvStart a bulk screenshot job from a CSVA
Uploads a CSV to start a bulk screenshot job. The CSV must have a 'url' column with full https:// URLs; any other column is treated as a render option for that row using the API parameter names (file_type, width, height, css, delay, headers, ...). Pass either a local csv_path or the CSV text in csv_content. Returns the job response including its uuid for get_bulk_status and download_bulk_results. ScreenshotAPI also emails a download link when the job finishes. Paid plans only.
Inputs: csv_path, csv_content.
download_bulk_resultsDownload bulk screenshot resultsA
Downloads the results of a finished bulk screenshot job by uuid: one row per URL with its status, the hosted screenshot URL, and any error message.
Inputs: uuid (required).
generate_pdfConvert a web page or HTML to PDFA
Renders a URL or raw HTML in a real browser and converts it to a PDF, returning the hosted PDF URL. Choose a paper size ('format') for paginated output; without format (and without width/height) the whole page becomes one long continuous PDF page. Supports landscape, page ranges, print backgrounds, print vs screen CSS, and all page preparation options (delay, lazy_load, ad/cookie-banner blocking, CSS/JS injection). Use save_path to save the PDF locally.
Inputs: js, css, ttl, url, +42 more.
get_bulk_statusCheck a bulk screenshot jobA
Returns the progress of a bulk screenshot job by uuid: percent complete plus successful and failed URLs. Call download_bulk_results once it reaches 100%.
Inputs: uuid (required).
record_scrolling_videoRecord a scrolling video of a web pageA
Records a video (mp4, webm, or gif) of the browser scrolling down a web page and returns the hosted video URL. Control scroll speed, duration, and scrolling back to the top. Set video=true to record the viewport without scrolling (for animations or live dashboards). Pass 'sizes' to record the same page at several viewport sizes in one request. Rendering takes noticeably longer than a screenshot.
Inputs: js, css, url, block, +37 more.
scrape_pageScrape page content as Markdown, text, or HTMLA
Loads a page in a real browser (JavaScript executed) and extracts its content: clean Markdown (best for reading and summarizing), plain text, the fully rendered HTML, and/or every image URL on the page. Extracted files are fetched and returned inline, truncated to max_content_chars. Works on JavaScript-heavy sites that plain HTTP fetches can't read. A screenshot is captured as part of the same request and counts as one credit.
Inputs: js, css, url, block, +32 more.
take_screenshotTake a website screenshotA
Captures a screenshot of a web page (or of raw HTML) in a real browser and returns the hosted image URL. By default the image is also returned inline so you can see it — except for full_page captures, which are often too tall to view; set include_image=true to force it. Supports viewport or full-page capture, a single element via 'selector', a pixel region via 'clip', retina output, ad/cookie-banner blocking, CSS/JS injection, clicking elements first, dark mode, custom headers/cookies, proxies, geolocation, and timezone. Each call uses one screenshot credit unless a cached capture is served.
Inputs: js, css, ttl, url, +47 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 8 tools
Tools map cleanly to distinct output types and stages: single screenshot, PDF, scrape, video, and bulk job submit/status/download. The only real overlap is bulk_screenshots vs bulk_screenshots_csv, which both start bulk jobs but differ by input format; descriptions clarify this.
Six of eight tools follow a clear verb_noun pattern (take_screenshot, generate_pdf, scrape_page, record_scrolling_video, download_bulk_results, get_bulk_status). The two bulk submission tools are noun phrases (bulk_screenshots, bulk_screenshots_csv), a minor deviation; all names use consistent snake_case.
Eight tools is well within the ideal 3-15 range for this server's purpose. Each tool covers a distinct capability—screenshot, PDF, scrape, video, bulk JSON/CSV submission, status polling, and result download—with no obvious padding.
The surface covers the core capture types plus a full bulk lifecycle: submit, poll status, and download results. Minor gaps remain—no cancel/delete bulk job, no account/credit check, and no job listing—but agents can work around these.
Maintenance
Related MCP Connectors
Screenshots, PDFs, image editing, QR codes, email validation and more through one hosted MCP server.
A remote MCP server to convert HTML documents (URL or raw source) to PDF or screenshots
Web scraping MCP server — scrape, extract structured data, screenshot any site with anti-bot bypass.
Official MCP server for Softhills 3D/2D Visualization SDKs, API documentation, and code examples.
Related MCP Servers
- AlicenseBqualityCmaintenanceAn official MCP server implementation that allows AI assistants to capture website screenshots through the ScreenshotOne API, enabling visual context from web pages during conversations.138MIT
- AlicenseBqualityCmaintenanceAn MCP server that enables capturing website screenshots with full-page, element-specific, and device-responsive capabilities through natural language commands.362MIT
- AlicenseAqualityBmaintenanceMCP server for the OpenGraph.io API -- extract OG metadata, capture screenshots, scrape pages, query sites with AI, and generate branded images with iterative refinement.11182 npm2ISC
- AlicenseAqualityDmaintenanceMCP server for the SnapAPI web capture API. Take screenshots, scrape pages, extract structured data, generate PDFs, record videos, and run AI analysis on any URL — all from Claude, Cursor, VS Code, or any MCP client. 9 tools, 30+ device presets, ad/cookie blocking. Install: npx snapapi-mcp97 npmMIT