ScreenshotAPI

ScreenshotAPI MCP Server

[npm version] [GitHub] [Node.js] [License]

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.

Quick Start

1. Sign up for ScreenshotAPI and copy your API key from the dashboard.

2. Cursor users can install in one click:

   [Add to Cursor]

3. 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>"      }    }  }}

4. Restart your client.

5. Test it: ask "Take a screenshot of https://example.com"

Table of Contents

• Quick Start
• Install by Client
• Verify It Works
• Tool Reference
• Prompt Examples
• Error Codes
• How It Works
• Environment Variables
• Building from Source
• Troubleshooting
• Links
• License

Install by Client

Requirements

• Node.js 18 or later
• npx available in your terminal
• A 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/mcp

Start a new Claude Code session after adding the server.

Cursor

One-click install:

[Add to Cursor]

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/mcpcodex mcp list

Start 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:

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

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.

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.

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.

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.

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.

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.

get_bulk_status

GET https://api.screenshotapi.net/v1/bulk/csv/status returns percent_complete, successful_urls, and failed_urls for a job.

download_bulk_results

GET https://api.screenshotapi.net/v1/bulk/csv/download returns one row per URL with url, status, screenshot, and error_message.

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.

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:

1. Your MCP client starts the server process via npx.
2. The client reads the tool list.
3. When a prompt matches a tool, the client calls it.
4. The server validates inputs, calls ScreenshotAPI with output=json, and returns structured JSON with the hosted file URL.
5. 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

Building from Source

git clone https://github.com/Screenshot-API/screenshot-mcp.gitcd screenshot-mcpnpm installnpm run build

Run it directly:

SCREENSHOTAPI_TOKEN=<YOUR_KEY> node dist/cli.js

Inspect with the MCP Inspector:

SCREENSHOTAPI_TOKEN=<YOUR_KEY> npx @modelcontextprotocol/inspector node dist/cli.js

Troubleshooting

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

• ScreenshotAPI Website
• API Documentation
• Query Builder
• Pricing
• GitHub Repository

License

MIT