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-mcpThat 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
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 plansOption 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-mcpCursor, 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.
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 acceptsx-api-key: YOUR_API_KEY.
Each client has its own syntax for remote servers and headers. The client setup pages have the exact config.
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 ascapture_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:
beforeandafter. 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
elementfirst 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
elementwhen 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_slicesfor long pages, and checktruncatedto 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.
Client Setup
Exact config for each client
Claude Code
One command, hosted or local.
Cursor
Add it to Cursor's MCP servers.
Claude Desktop
Capture pages from a chat.
Codex
Connect OpenAI Codex.
VS Code + Copilot
Use the tools from GitHub Copilot.
Gemini CLI
Register the server with Gemini CLI.
Windsurf
Add it to Windsurf's MCP servers.
CLI and agent skill
For agents with a shell and no MCP client.
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.