Repository avatar
AI Tools
v0.1.0
active

mcp

com.getscreenshotapi/mcp

Screenshot web pages, render HTML and diff captures, with images sized for vision models.

Documentation

getscreenshot-mcp

MCP server and CLI for the GetScreenshot API. It gives AI agents eyes: capture a public web page, or HTML the agent just wrote, and get back images sized for vision models.

claude mcp add --env GETSCREENSHOT_API_KEY=YOUR_API_KEY --transport stdio getscreenshot -- npx -y getscreenshot-mcp

Then ask your agent to "take a screenshot of https://example.com and tell me what is above the fold".

  • Works where there is no browser. Cloud coding agents, sandboxes and CI runners cannot launch Chromium. A hosted HTTPS API can render any public URL, or raw HTML, and hand back an image.
  • Output sized for models. Captures are downscaled and full pages are cut into slices, so every image fits a vision model's input budget. The result reports the estimated token cost. The full-resolution image stays available by URL.
  • One API key. Plans start at $5/month for 2,500 screenshots, and the MCP server, CLI and agent skill work with any key on any plan.

You need an API key: get one at https://www.getscreenshotapi.com/#pricing. It is emailed after checkout. Code FREE5 makes the first month of the $5 plan free.

Quick start

Claude Code

Local server (stdio):

claude mcp add --env GETSCREENSHOT_API_KEY=YOUR_API_KEY --transport stdio getscreenshot -- npx -y getscreenshot-mcp

Hosted server (nothing to install):

claude mcp add --transport http getscreenshot https://mcp.getscreenshotapi.com/mcp --header "Authorization: Bearer YOUR_API_KEY"

Cursor, Claude Desktop and other clients

Add this to the client's MCP config (.cursor/mcp.json or ~/.cursor/mcp.json for Cursor, claude_desktop_config.json for Claude Desktop):

{
  "mcpServers": {
    "getscreenshot": {
      "command": "npx",
      "args": ["-y", "getscreenshot-mcp"],
      "env": { "GETSCREENSHOT_API_KEY": "YOUR_API_KEY" }
    }
  }
}

Any client that speaks Streamable HTTP

  • URL: https://mcp.getscreenshotapi.com/mcp
  • Header: Authorization: Bearer YOUR_API_KEY (x-api-key: YOUR_API_KEY also works)

The key is accepted in a header only. A key in the URL (?apikey=) is ignored: URLs are written to request logs, config files and browser history.

Without a key the server still connects and lists its tools. Each tool then answers with instructions for getting and setting a key.

Tools

ToolWhat it doesCost
capture_screenshotCapture a public web page as images the model can see. Viewport by default; element for one part of the page; full_page for the whole page.1 screenshot
render_htmlRender an HTML string (a component or page the agent just wrote) and screenshot it.1 screenshot
compare_screenshotsVisual diff of two pages or two earlier screenshots: changed-pixel percentage, bounding box, diff image.1 per side given as url, 0 for screenshot_url
capture_pdfSave a page as an A4 PDF and return the link.1 screenshot
get_usageScreenshots used, monthly limit, remaining, reset date.1 screenshot

All tools are annotated readOnlyHint: true, openWorldHint: true, destructiveHint: false, idempotentHint: false.

capture_screenshot inputs

InputTypeDefaultNotes
urlstringrequiredAbsolute http(s) URL, reachable from the public internet.
full_pagebooleanfalseWhole scrollable page.
elementstringCSS selector; captures only that element.
deviceenumiphone5, iphone678, iphone678_plus, iphonex, iphone12, pixel2, pixel2_xl, ipad, ipadpro, hvga, wvga, dvga, wxga_v, xga, wxga_s, wxga_l, sxga, wsxga_plus. Overrides width/height.
width, heightinteger1280, 800Viewport in CSS pixels.
scale1-31Device pixel ratio of the stored image.
formatpng | jpegpngFormat of the stored file. Inline images are always JPEG.
wait_untilenumnetworkidle2load, domcontentloaded, networkidle0, networkidle2.
wait_ms0-200002000Extra wait before capture.
hide_selectorsstringCSS selector(s) to hide.
hide_cookie_bannersbooleantrueHides common cookie banners.
hide_chat_widgetsbooleanfalseHides common chat widgets.
clickstringCSS selector to click before capture.
custom_css, custom_jsstringInjected before capture.
highlightstringKeyword(s) to highlight.
cookie{name, value}One cookie for the target host.
langstringen-USBrowser language.
transparent_backgroundbooleanfalseTransparent where the page sets no background.
full_page_strategy0-30Try another value if a full-page capture renders badly.
detailstandard | highstandardSize of inline images, see below.
max_slices1-104Maximum number of inline images. Fewer are attached if they would exceed the inline size limit, see below.
returnimage_and_url | url_onlyimage_and_urlurl_only attaches no image and reads only the image's dimensions.

render_html takes html (required, at most 2 MB) plus full_page, element, device, width, height, scale, wait_ms, detail, max_slices, return. The HTML is hosted at an unguessable temporary URL, captured like any page, and deleted as soon as the capture returns (at the latest after 5 minutes or 3 reads). Relative asset URLs do not resolve unless the HTML sets <base href> or inlines its assets. The page runs in a sandbox without cookies or localStorage, so code that depends on them may render blank. Cookie-banner hiding is off for this tool so the page renders as written.

compare_screenshots takes before and after, each either { "url": "..." } (a page to capture) or { "screenshot_url": "..." } (an earlier GetScreenshot result), plus shared full_page, width, height, device, hide_selectors, wait_until, wait_ms, and threshold (0-1, default 0.1). screenshot_url must be a GetScreenshot result URL (https://storage.googleapis.com/getscreenshot-storage/...); anything else is refused. A screenshot_url side is checked first (it must exist and be an image) before a capture is spent on a url side. At most the top 2,400 px are compared, at up to 1280 px wide; for a lower part of a long page, capture that part of both versions with capture_screenshot and element, then compare the two screenshot_url values.

capture_pdf takes url, wait_until, wait_ms, hide_selectors, custom_css.

Output contract

Every successful call returns a short text block, then the image blocks (if any), plus structuredContent that matches the tool's declared outputSchema.

Screenshot captured: https://storage.googleapis.com/getscreenshot-storage/imageAbC123xYz9.png
Page: https://example.com (HTTP 200).
Original image: 1280x6000 px (png).
Attached: 4 of 7 slices as JPEG images, 1280 px wide, top to bottom, about 6,256 image tokens (approximate).
Truncated: only the top 3808 px of 6000 px (after downscaling) are attached. To see the rest, raise max_slices (up to 10) or capture one part with `element`.
The link is public to anyone who has it and expires in 30 days.

structuredContent of capture_screenshot and render_html:

{
  "screenshot_url": "https://storage.googleapis.com/getscreenshot-storage/imageAbC123xYz9.png",
  "origin_url": "https://example.com",
  "page_status": 200,
  "captured_at": "2026-11-18T14:03:22Z",
  "format": "png",
  "original": { "width": 1280, "height": 6000 },
  "images": [
    { "index": 0, "y": 0, "width": 1280, "height": 952, "estimated_tokens": 1564 },
    { "index": 1, "y": 952, "width": 1280, "height": 952, "estimated_tokens": 1564 },
    { "index": 2, "y": 1904, "width": 1280, "height": 952, "estimated_tokens": 1564 },
    { "index": 3, "y": 2856, "width": 1280, "height": 952, "estimated_tokens": 1564 }
  ],
  "total_slices": 7,
  "truncated": true,
  "estimated_image_tokens": 6256,
  "expires_in_days": 30,
  "warnings": []
}
  • images[i] describes the i-th image block. y is the slice's top offset in the downscaled capture, in the same pixels as width and height.
  • page_status is the HTTP status the page answered with. At 400 or above the text and warnings say so, because the capture is probably an error page.
  • original is null if the stored image could not be read. The capture and its URL are still returned. The same happens when the server is too busy to process the image: the result is not an error, images is empty and warnings says why.
  • total_slices is how many slices the whole image needs at this detail level, whether or not they are attached. truncated is true when images were requested and some slices were left out, because of max_slices or the inline size limit. With return: "url_only" no image is attached by request, so images is empty, truncated is false, and total_slices is what a normal call would produce.
  • compare_screenshots returns changed_percent, changed_pixels, total_pixels, identical, threshold, bounding_box ({x, y, width, height} or null), size_changed, compared, before and after (each with screenshot_url, origin_url, page_status, width, height), and the same image fields. identical is true only when no compared pixel differs and both images have exactly the same width and height. The diff image is the after image dimmed, with changed pixels in magenta and a red rectangle around the changed area. It is cropped to the changed rows. When nothing changed, no image is attached. If a capture succeeded but the comparison could not be completed, the error names the screenshot URLs that are already paid for, so they can be passed back as screenshot_url.
  • capture_pdf returns pdf_url, origin_url, page_status, captured_at, expires_in_days, warnings.
  • get_usage returns used, limit, remaining, percent_used, period, quota_restart_date, resets_on.

Failures are returned as tool results with isError: true and a message that says what to change. For example a page that fails to load suggests wait_until: "domcontentloaded", and a crashed capture with element set says the selector probably matched nothing.

Stored files are on Google Cloud Storage for 30 days. The links are public to anyone who has them.

Sizing rules

detailMax widthMax long edgeMax tokens per imageSlice height at max width
standard (default)1280 px1568 pxabout 1,568952 px
high1920 px2576 pxabout 4,7841932 px
  1. Images wider than the max width are downscaled. Nothing is upscaled.
  2. The result is cut top to bottom into slices of the tallest height that respects both limits. If the last slice would be under 200 px, the last two slices are balanced instead.
  3. The first max_slices slices are returned. truncated and total_slices tell you whether there is more.
  4. Inline images are JPEG, quality 80. Transparent areas are flattened onto white.
  5. The inline images of one result may not exceed about 1.5 MB in total (standard) or 4 MB (high). A slice over its share is re-encoded at quality 70, then 60. If the total still does not fit, trailing slices are left out, truncated is true and warnings names the cause. Ordinary pages stay far below this; photo-heavy or noisy pages can reach it. The first slice is always returned.
  6. Token estimate per image: ceil(width / 28) * ceil(height / 28). This is an approximation in the style of Claude's image accounting; other models count differently.

A default 1280x800 viewport capture is one image of about 1,334 tokens. Use element to look at one part of a page for less, and high only when you need to read small text.

CLI

The same package is a command-line tool, for agents that have a shell but no MCP client.

export GETSCREENSHOT_API_KEY=YOUR_API_KEY
npx -y getscreenshot-mcp capture https://example.com --full-page -o page.png
url: https://storage.googleapis.com/getscreenshot-storage/imageAbC123xYz9.png
saved: /work/page.png
page_status: 200
getscreenshot-mcp capture <url> [--full-page] [--element SEL] [--device NAME]
                                [--width N] [--height N] [--format png|jpeg]
                                [--wait-until X] [--wait-ms N] [--hide SEL]
                                [-o FILE] [--json]
getscreenshot-mcp pdf <url> [--wait-until X] [--wait-ms N] [--hide SEL] [-o FILE] [--json]
getscreenshot-mcp usage [--json]
getscreenshot-mcp --help | --version
  • -o FILE downloads the original full-resolution file. A .jpg or .jpeg name selects JPEG unless --format says otherwise.
  • --json prints one JSON object: screenshot_url (or pdf_url), origin_url, page_status, captured_at, format (capture only), saved_to, expires_in_days. usage --json prints used, limit, remaining, period, quota_restart_date. A failure with exit code 1 also prints {"error": {"code", "message"}} on stdout.
  • Exit codes: 0 success, 1 the capture or download failed (the message on stderr says what to change), 2 bad arguments, for example an unknown --device name or a flag the subcommand does not support, such as pdf --element (nothing is captured and no quota is used).
  • With no arguments the bin starts the MCP server on stdio. --http starts the hosted server.

Agent skill

The package ships an agent skill named getscreenshot in skills/. Install it with:

npx skills add rasterwise/getscreenshot-mcp

Limits

  • No localhost. A hosted API cannot reach localhost or private networks. Use render_html, or a public preview URL or tunnel. Such URLs are rejected before any quota is used.
  • Single-shot captures. One page load per call, with an optional click, cookie, CSS and JS. Logged-in, multi-step browsing sessions are what browser-automation tools such as Playwright MCP are for.
  • Failed captures still count against the monthly quota. The API charges one unit per authenticated request, so the server never retries a failed capture on its own. The only automatic retry is for a 429 Too Many Requests rate limit (2 retries with backoff).
  • Captures take about 9 seconds typically and up to about 25 seconds. The API gives up at 90 seconds.
  • Sites with aggressive bot protection may refuse headless browsers.
  • render_html in the local (stdio) server uploads the HTML to the hosted service at mcp.getscreenshotapi.com, because the capture API needs a public URL to load. The document is deleted as soon as the capture returns, and at the latest after 5 minutes or 3 reads.
  • compare_screenshots compares at most the top 2,400 px of each image (at up to 1280 px wide). The local server can raise this with COMPARE_MAX_HEIGHT.
  • The hosted server limits each caller to 60 tool calls per minute, runs at most 3 image jobs at a time, and holds at most 5 render_html documents per caller. When a limit is hit the tool returns an error that says how long to wait. A capture that already succeeded is still returned by URL.

Environment variables

Local server and CLI:

VariableDefaultPurpose
GETSCREENSHOT_API_KEYYour API key.
GETSCREENSHOT_API_BASEhttps://api.rasterwise.comREST API base URL. For tests.
GETSCREENSHOT_MCP_BASEhttps://mcp.getscreenshotapi.comService that hosts HTML for render_html in stdio mode.
COMPARE_MAX_HEIGHT2400Rows compare_screenshots compares at most. A compare holds about 12 bytes per compared pixel in memory, so raise it only with memory to spare.
INLINE_MAX_BYTES_STANDARD1500000Cap on the total inline JPEG bytes of one result at detail: "standard".
INLINE_MAX_BYTES_HIGH4000000The same at detail: "high".
IMAGE_CONCURRENCY3Image jobs (download and resize, or compare) that run at once.
IMAGE_QUEUE_MAX24Image jobs that may wait for a slot. Beyond this a job is refused at once.
IMAGE_QUEUE_WAIT_MS20000Longest a job waits for a slot before it is refused.

Hosted server (getscreenshot-mcp --http). All of the above apply, plus:

VariableDefaultPurpose
PORT8080Port to listen on.
PUBLIC_BASE_URLhttp://127.0.0.1:<port>Public origin of the MCP endpoint. Must be set in production.
HTML_PUBLIC_BASE_URLvalue of PUBLIC_BASE_URLPublic origin used in render_html links (/h/<id>). Point this at a throwaway domain so a flagged page cannot damage the MCP hostname.
RATE_LIMIT_PER_MINUTE60Tool calls per caller per minute. A caller is the API key (as a SHA-256 hash), or the client address when no key is sent.
RATE_LIMIT_PER_IP_PER_MINUTE120Tool calls per client address per minute, across all keys it sends. Stops a caller from getting a fresh allowance by inventing keys.
HTML_MAX_DOCS_PER_CALLER5Live render_html documents per caller. One client address may hold four times this across keys.
SHARP_CONCURRENCY1libvips threads per image job.
TRUSTED_PROXY_HOPS0Proxies between Google's front end and the container that append to X-Forwarded-For. 0 for Cloud Run reached directly or by domain mapping, 1 behind an external load balancer. A value above 0 is only safe when the service is deployed with --ingress internal-and-cloud-load-balancing; otherwise a caller who reaches the service directly chooses the address that is trusted.
TRIAL_API_KEYunsetTurns on keyless preview mode, see below. Off by default. Not for production yet.
TRIAL_DAILY_LIMIT_PER_IP5Preview captures per client address per UTC day.
TRIAL_DAILY_LIMIT_GLOBAL200Preview captures per UTC day in total.

Client addresses are IPv4 addresses, or the /64 of an IPv6 address.

Routes:

RoutePurpose
POST /mcpStateless Streamable HTTP. A fresh server per request, no sessions. One JSON-RPC message per POST: a batch (JSON array) is rejected with error -32600. GET and DELETE answer 405. CORS is open for browser-based clients.
GET /health{"status":"ok","version":"..."}. /healthz answers too, but Cloud Run intercepts that path, so use /health there
GET /302 to https://www.getscreenshotapi.com/agents/
POST /v1/htmlBody is raw HTML (at most 2 MB), key in Authorization: Bearer or x-api-key. Returns {"url", "expires_in_seconds"}. Used by the local server's render_html. Answers 429 when the caller is over a limit and 503 when the store is full.
GET /h/:idServes a stored document with Content-Security-Policy: sandbox allow-scripts, X-Robots-Tag: noindex, Cache-Control: no-store, Referrer-Policy: no-referrer.
DELETE /h/:idRemoves a document. Needs the key that uploaded it. Used by the local server once its capture has returned.

Authentication is by header only: Authorization: Bearer <API key> or x-api-key: <API key>. The query string is never read for a key.

Logging

The server writes one JSON line per request to stdout: method, path without the query string, status, duration, whether a key was sent and in which header, and the tool name and outcome. It does not write API keys, query strings, request bodies, tool arguments or the ids of hosted documents.

The platform keeps its own request log, which this server does not control. Cloud Run's request log records the full URL of every request, including the path of GET /h/<id> and anything a client puts in a query string. This is why keys are only accepted in headers.

Limits that protect the service

A key cannot be verified without spending the caller's quota, so every limit below applies whether or not the key is valid. All of them are held in the memory of the one instance.

  • Request targets that are not a plain path (//host, absolute URLs, *) get a 400. A request must deliver its headers and body within 15 seconds or the connection is closed with a 408. Bodies are capped at 6 MB for /mcp and 2 MB for /v1/html.
  • Tool calls are limited per caller and per client address (RATE_LIMIT_PER_MINUTE, RATE_LIMIT_PER_IP_PER_MINUTE). Over the limit, the tool returns an error with the number of seconds to wait.
  • Downloading, resizing and comparing images goes through one gate (IMAGE_CONCURRENCY, IMAGE_QUEUE_MAX, IMAGE_QUEUE_WAIT_MS). When it is full, compare_screenshots is refused before anything is captured. A capture that already succeeded is returned by URL with a warning instead of an image.
  • Memory per image job is bounded. Slices are encoded one at a time, which measured 30 to 50 MB for the largest pages (3840x20000 px, high, 10 slices). A compare is capped at 2,400 rows and measured 50 to 60 MB. Inline images are capped in bytes (INLINE_MAX_BYTES_*). With 3 jobs at a time, a sustained worst-case load test kept the process under 500 MB (measured on macOS; not yet measured in the Linux container).
  • HTML documents: at most 5 live per caller and 20 per client address, 60 uploads per minute per client address (POST /v1/html and render_html together), 200 documents and 100 MB in total. When the store is full a new document is refused; documents that are already there are never evicted. A render_html document is deleted as soon as its capture returns, and otherwise after 5 minutes or 3 reads.
  • POST /v1/html only checks that a key-shaped value was sent. The capture that follows is what the API authenticates.

The service must run as a single instance (deploy.sh sets --max-instances 1). HtmlStore in src/html-store.ts is the interface to implement for a shared store.

Keyless preview mode

Off by default. Do not enable it in production yet: its daily counters are kept in the memory of the process and reset on every restart, new revision and scale-to-zero, so the limits are not reliable until a persistent counter exists. The server logs a warning at startup when TRIAL_API_KEY is set.

When TRIAL_API_KEY is set, a request without a key uses that key, within the two daily limits. Only capture_screenshot is allowed, and only as a plain viewport capture: no full_page, no element, scale 1, no click, custom_js, custom_css or cookie, wait_ms at most 5000, and a viewport of at most 1920x1200. Pages on the server's own hostnames are refused, so an uploaded HTML document cannot be captured without a key. The result says it was a preview capture and how to get a key; past the limit the tool returns that message as an error. The client address is the right-most X-Forwarded-For entry, which on Cloud Run is the one appended by Google's front end and cannot be forged by the client; IPv6 addresses count by their /64.

Deploying

GCP_PROJECT=my-project ./deploy.sh          # prints what it would run and exits
GCP_PROJECT=my-project ./deploy.sh --yes    # deploys to Cloud Run

deploy.sh needs GCP_PROJECT (the Google Cloud project id) and refuses to run without it. It deploys service $SERVICE (default getscreenshot-mcp) to region $REGION (default us-central1) with --max-instances 1, --memory 2Gi and --timeout 300, and sets PUBLIC_BASE_URL (default https://mcp.getscreenshotapi.com) and, if given, HTML_PUBLIC_BASE_URL.

Each deploy replaces the service's environment variables and secrets. Preview mode is on only when TRIAL_API_KEY_SECRET names a Secret Manager secret; when it is unset, the script passes --clear-secrets, so a TRIAL_API_KEY attached by an earlier deploy is removed.

To serve render_html documents from their own hostname, map a second domain to the same service and set HTML_PUBLIC_BASE_URL to it. That hostname then serves only /h/<id>, and the MCP hostname serves no HTML documents.

The Dockerfile is a multi-stage node:22-slim build that runs as the unprivileged node user. It starts Node with --expose-gc, so the server can ask for a garbage collection after each image job instead of letting dead pixel buffers pile up, and sets MALLOC_ARENA_MAX=2 to limit allocator fragmentation.

Development

Requires Node.js 20.9 or newer.

npm install
npm run typecheck   # tsc --noEmit over src and test
npm run build       # tsc to dist/
npm test            # builds, then runs the vitest suite

The tests make no calls to the real API. test/helpers/fake-upstream.ts is a local HTTP server that mimics the REST API and its image storage: the success JSON points at PNGs it generates and serves (including a 1280x6000 one), every error in the API's error table can be triggered, and, like the real gateway, it rejects every key that is not on its list of valid test keys. On top of it the suite covers:

  • test/api.test.ts: the exact query parameters received for every input, including the ones that must not be sent, and every error row mapped to its message.
  • test/vision.test.ts: slice math and token estimates as tables, real image slicing, the inline byte budget, and the download allow-list.
  • test/diff.test.ts, test/html-store.test.ts, test/limits.test.ts: the diff, the HTML store (per-caller caps, reject when full), and the rate limiters and image gate.
  • test/mcp.e2e.test.ts: a real MCP Client over the SDK's in-memory transport calling each tool; image blocks are decoded and checked against the sizing rules and structuredContent is validated against each outputSchema.
  • test/http.test.ts: the HTTP server on an ephemeral port with the SDK's Streamable HTTP client, plus raw sockets for malformed request lines, stalled bodies, batches and the limits.
  • test/cli.test.ts: the built bin as a child process (CLI, stdio server, --http with SIGTERM, malformed requests and uncaught errors against the real process).

Run the server against a local fake or staging API by setting GETSCREENSHOT_API_BASE. Downloads are only allowed from https://storage.googleapis.com and, when the base is overridden, from that base's origin. Redirects are refused and downloads are capped at 25 MB.

Source layout:

FileRole
src/api.tsREST client, parameter mapping, error mapping.
src/download.tsAllow-listed, size-capped downloads.
src/vision.tsDownscale, slice, JPEG encode, token estimates.
src/diff.tsImage comparison.
src/html-store.tsTemporary HTML documents.
src/limits.tsCaller identity, rate limiters, the image gate.
src/tools.ts, src/server.tsThe five tools and the MCP server.
src/stdio.ts, src/http.ts, src/cli.ts, src/bin.tsEntry points.

Links

MIT License. Copyright (c) 2026 Rasterwise, LLC.

NPM
getscreenshot-mcp
Install Command
npm install getscreenshot-mcp
Runtime: npx