MCP Server

GetScreenshot MCP Server

Five tools that let an agent capture a web page, render HTML, diff two screenshots, save a PDF and check its quota. Images come back sized for vision models, with an estimated token cost on every result.

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

That is the install for Claude Code. Other clients and the hosted endpoint are under Install.

On this page: Install · Tools · Output and token cost · Errors · Limits · Client setup

What It Is

An MCP server named getscreenshot. It calls the GetScreenshot REST API, fetches the capture, resizes it for a vision model and returns it inside the tool result.

The agent does not need a browser, and it does not need to download and resize the image itself. It gets the picture, the hosted URL of the full-resolution original and the estimated token cost in one response.

It works with any API key on any plan, including the $5 Lincoln plan. Each capture uses one screenshot from the monthly quota.

At a glance

npm package getscreenshot-mcp
Local transport stdio, started with npx -y getscreenshot-mcp
Hosted endpoint https://mcp.getscreenshotapi.com/mcp (Streamable HTTP)
Auth Your GetScreenshot API key. Env var GETSCREENSHOT_API_KEY locally, Authorization: Bearer header when hosted.
Tools capture_screenshot, render_html, compare_screenshots, capture_pdf, get_usage
Tool annotations All tools are marked read-only and non-destructive (readOnlyHint: true, destructiveHint: false, openWorldHint: true).
Source github.com/rasterwise/getscreenshot-mcp

Install

Run it locally with npx, or connect to the hosted endpoint

1

Get an API key

Pick a plan on the pricing section. The key is emailed after checkout. Plans start at $5/month for 2,500 screenshots, and code FREE5 makes the first month of that plan free. If you lose the key you can recover it on the account page.

View pricing plans
2

Option A: local server with npx

The client starts the server as a child process and talks to it over stdio. In Claude Code:

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

Cursor, Claude Desktop and most other clients take a JSON entry of this shape:

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

Needs Node.js 20.9 or newer on the machine that runs the client.

3

Option B: hosted endpoint

Nothing to install. Point the client at the URL and send your API key in a header. In Claude Code:

claude mcp add --transport http getscreenshot https://mcp.getscreenshotapi.com/mcp \
  --header "Authorization: Bearer YOUR_API_KEY"
  • URL: https://mcp.getscreenshotapi.com/mcp
  • Transport: Streamable HTTP
  • Header: Authorization: Bearer YOUR_API_KEY. The server also accepts x-api-key: YOUR_API_KEY.

Each client has its own syntax for remote servers and headers. The client setup pages have the exact config.

4

Try it

Ask the agent something that needs a look at a page:

Take a screenshot of https://example.com and tell me what is on the page.

The agent calls capture_screenshot, receives the image and describes it. A capture typically takes about 9 seconds.

The Five Tools

Inputs, and what comes back

capture_screenshot

Captures a public web page as an image the model can see. Only url is required.

{
  "url": "https://example.com/pricing",
  "full_page": true,
  "wait_until": "domcontentloaded"
}
Input Type and default What it does
url string, required Public http or https page to capture. URL shorteners are rejected.
full_page boolean, false Capture the full scrollable page instead of the viewport.
element CSS selector Capture only that element. The capture fails if the selector matches nothing.
device preset name Sets the viewport and, for phones, a mobile user agent. One of iphone5, iphone678, iphone678_plus, iphonex, iphone12, pixel2, pixel2_xl, ipad, ipadpro, hvga, wvga, dvga, wxga_v, xga, wxga_s, wxga_l, sxga, wsxga_plus.
width, height integers, 1280 and 800 Viewport size in CSS pixels.
scale 1 to 3, default 1 Device pixel ratio. 2 is retina.
format png or jpeg, default png Format of the stored file behind screenshot_url. Inline images are always JPEG.
wait_until default networkidle2 load, domcontentloaded, networkidle0 or networkidle2. domcontentloaded is the fastest and the most reliable on heavy sites.
wait_ms 0 to 20000, default 2000 Extra wait in milliseconds before the capture.
hide_selectors string CSS selector or selectors to hide before the capture.
hide_cookie_banners boolean, true Hides common cookie banners. Pass false to keep them.
hide_chat_widgets boolean, false Hides common chat widgets such as Intercom and Drift.
click CSS selector Clicks one element before the capture.
custom_css, custom_js strings CSS or JavaScript injected into the page before the capture.
highlight string Keyword or keywords to highlight on the page.
cookie {name, value} One cookie, set for the target host.
lang default en-US Browser language and Accept-Language header.
transparent_background boolean, false Transparent background where the page sets none.
full_page_strategy 0 to 3, default 0 Full-page capture strategy. Try another value if a full-page capture renders badly.
detail standard or high, default standard How large the inline images may be. See vision sizing.
max_slices 1 to 10, default 4 Upper bound on the number of inline images for a tall capture.
return image_and_url (default) or url_only url_only skips the inline images and returns just the link and metadata.

Returns: a text summary, one or more inline JPEG images, and structured content. Details are in the output contract.

render_html

Renders an HTML string and screenshots it. For a component or page the agent just wrote that is not deployed anywhere.

{
  "html": "<!doctype html><html><body style=\"font-family: sans-serif; padding: 24px\"><button class=\"cta\">Start now</button></body></html>",
  "width": 600,
  "height": 300
}
  • Inputs: html (required, up to 2 MB), plus the same viewport and output options as capture_screenshot: full_page, element, device, width, height, scale, wait_ms, detail, max_slices, return.
  • How it works: the server hosts the HTML at a temporary, unguessable URL, captures that URL through the normal API, deletes the document as soon as the capture returns, and returns the result in the same shape as capture_screenshot.
  • Assets: relative URLs for stylesheets, scripts and images will not resolve. Inline them, or set <base href> to a public origin that serves them.
  • Quota: one screenshot.

compare_screenshots

Visual diff of two pages or two existing screenshots. Before and after a change, or staging against production.

{
  "before": { "url": "https://www.example.com/pricing" },
  "after": { "url": "https://staging.example.com/pricing" },
  "full_page": true
}
  • Inputs: before and after. Each is either {url}, a page to capture now, or {screenshot_url}, the URL of an earlier GetScreenshot result.
  • Shared capture options: full_page, width, height, device, hide_selectors, wait_until, wait_ms. They apply to both sides so the two captures match.
  • Sensitivity: threshold, from 0 to 1, default 0.1.
  • Returns: the percentage of pixels that changed, the bounding box of the changed area, an inline diff image with the changes highlighted, and both source URLs.
  • Limit: at most the top 2,400 px of each side are compared, at up to 1280 px wide. To compare a region further down a long page, capture it with element first and pass the two results as {screenshot_url}.
  • Quota: one screenshot per {url} input. Reusing an earlier capture with {screenshot_url} does not take a new screenshot.

capture_pdf

Saves a page as an A4 PDF.

  • Inputs: url, wait_until, wait_ms, hide_selectors, custom_css.
  • Returns: pdf_url, a link that works for 30 days.
  • Quota: one screenshot.

get_usage

Reports quota for the configured API key.

  • Inputs: none.
  • Returns: screenshots used this month, the monthly limit and the date the quota resets.
  • Quota: the call itself uses one unit, so there is no reason to check before every capture.

Output Contract and Vision Sizing

What a capture result contains, and how many tokens it costs

1. Text summary

A short plain-text description of the result.

2. Inline images

One or more JPEG image blocks at about quality 80, resized to fit a vision model's input. A tall capture arrives as several slices, top to bottom.

3. Structured content

A JSON object with the URL of the original, page status, dimensions and the token estimate for each image.

Fields in structuredContent

Field Description
screenshot_url Public URL of the full-resolution original on Google Cloud Storage.
origin_url The page that was captured.
page_status HTTP status the page answered with. A 404 here means the image shows the site's error page.
captured_at When the capture was taken, in UTC.
format Format of the stored original, png or jpeg.
original {width, height} of the original in pixels. null if the stored image could not be read.
images One entry per inline image: {index, y, width, height, estimated_tokens}. index starts at 0 and runs top to bottom. y is the top offset of the slice, in inline-image pixels.
total_slices How many slices the capture needs in full.
truncated true when the page needed more slices than max_slices allowed, so the bottom of the page is not in the inline images.
estimated_image_tokens Sum of the estimates for all inline images in this result.
expires_in_days 30. The stored file is kept for 30 days.
warnings List of notes about this result, for example that the page answered with an HTTP error status. Empty when there is nothing to report.

Sizing rules

The detail input picks the budget for each inline image. The full-resolution original is always at screenshot_url, whatever the setting.

detail Max width Max long edge per image Max tokens per image (approx.)
standard 1280 px 1568 px 1,568
high 1920 px 2576 px 4,784

The token estimate for one image is:

estimated_tokens = ceil(width / 28) * ceil(height / 28)

This follows the way Claude counts image tokens. Other models count differently, so treat every number here as approximate.

What common captures cost

Capture Images returned Approximate tokens
Default viewport, 1280x800 1 image, 1280x800 1,334
Phone viewport, 390x844 (device: "iphone12") 1 image, 390x844 434
Tablet viewport, 768x1024 (device: "ipad") 1 image, 768x1024 1,036
Full page, 1280 wide, standard Slices of up to 1280x952, 4 by default 1,564 per slice, up to 6,256 for 4
Full page, 390 wide (phone) Slices of up to 390x1568, 4 by default 784 per slice, up to 3,136 for 4
Full page with max_slices: 10 Up to 10 slices of 1280x952 Up to 15,640
Any capture with return: "url_only" None 0 image tokens

Computed with the formula above. The exact figure for a capture is in estimated_image_tokens.

Keeping the cost down

  • Capture one element when the question is about one component. A 600x400 card is about 330 tokens.
  • Capture the viewport instead of the full page when what you are checking is above the fold. One image instead of up to four.
  • Lower max_slices for long pages, and check truncated to know whether something was left out.
  • Use return: "url_only" when the agent only needs a link, for example to paste into a report.

Errors Agents Will See

A failed call comes back as a tool error with a message that says what to change

What the agent is told API response behind it What it means and what to do
No API key is configured None. The API is not called. Every tool returns this until a key is set. The message says where to get one (plans from $5/month, code FREE5) and how to set GETSCREENSHOT_API_KEY or the Authorization header.
The API key is not recognised HTTP 500 {"message": "error"} with header x-amzn-errortype: AuthorizerConfigurationException The key has a typo, quotes or stray whitespace. The API usually answers an unknown key with a 500 for legacy reasons, and the server translates it. Retrying will not help.
The API key is disabled HTTP 403 {"message":"Forbidden"} The subscription was cancelled or a payment failed. Fix it on the account page. The API sometimes answers an unknown key with this 403 as well, so check the key for typos too. The agent should tell the user and stop.
The monthly quota is used up HTTP 429 {"message":"Limit Exceeded"} No more captures until the quota resets or the plan is upgraded. get_usage reports the reset date.
Rate limited HTTP 429 {"message":"Too Many Requests"} Too many requests at once. Wait a few seconds, retry, and send fewer captures in parallel.
The URL is not valid HTTP 400 {"status":"denied","message":"Bad posture."} url is missing or is not an absolute http or https URL. Pass the full URL with its protocol.
The URL is not allowed HTTP 403 {"status":"denied", ...} URL shorteners and some blocked domains are refused. Pass the final destination URL.
The page did not load in time HTTP 500 {"status":"failed", ...} The site is slow, offline, or blocking automated browsers. Retry once with wait_until: "domcontentloaded". If that fails too, more retries will not help.
The capture crashed HTTP 500 with plain text Internal Server Error Most often the element selector matched nothing or the click selector is wrong. Fix the input. An unknown device name does not get this far: the tool's input schema rejects it before anything is captured. Capturing without element first shows what is on the page.
The capture timed out HTTP 504 {"message": "error"} It took longer than the API's 90 second limit. Try wait_until: "domcontentloaded", a smaller wait_ms, or the viewport instead of the full page.

Failed captures still use quota

Every authenticated request to the API counts as one unit, including a capture that fails. An agent should change something before each retry and should not retry in a loop. It is worth saying so in your agent's rules file.

Limits

What the server does not do

No localhost or private networks

The capture runs on GetScreenshot's servers. It can only load pages on the public internet. Use render_html, a public preview URL or a tunnel.

Single-shot captures

One page load per call. No sessions, no multi-step navigation, no logged-in browsing. For those, see GetScreenshot vs Playwright MCP.

Bot protection

Sites with aggressive bot protection may refuse headless browsers. The capture may fail, or show a challenge page instead of the content.

Timing

A successful capture typically takes about 9 seconds, about 15 seconds at the 90th percentile and about 25 at the 99th. The API gives up at 90 seconds.

Stored files are public for 30 days

Each capture is stored on Google Cloud Storage at a public URL for 30 days. Anyone with the URL can fetch it. Do not capture pages that show data you would not put behind a public link.

Formats

Stored images are PNG or JPEG. PDFs are A4. render_html accepts up to 2 MB of HTML.

Get a Key and Add the Server

The MCP server works with any API key on any plan, from $5/month for 2,500 screenshots.