The GetScreenshot MCP server gives an AI agent a way to look at a web page. The agent asks for a URL, or passes HTML it just wrote, and gets back an image sized for a vision model. It calls the same REST API as every other GetScreenshot integration and works with any API key on any plan.
Sections in this article
Quick start
You need a GetScreenshot API key. Keys are emailed after checkout at getscreenshotapi.com. Plans start at $5 per month for 2,500 screenshots, and the code FREE5 makes the first month of the $5 plan free.
Hosted endpoint
Add the hosted server to Claude Code:
claude mcp add --transport http getscreenshot https://mcp.getscreenshotapi.com/mcp --header "Authorization: Bearer YOUR_API_KEY"
The endpoint is https://mcp.getscreenshotapi.com/mcp and speaks Streamable HTTP. Send your API key in the Authorization header as a Bearer token. The header x-api-key: YOUR_API_KEY is accepted as well. Any MCP client that supports remote servers with custom headers can use this endpoint.
Local server
Run the server on your own machine over stdio:
GETSCREENSHOT_API_KEY=YOUR_API_KEY npx -y getscreenshot-mcp
The package is getscreenshot-mcp on npm and needs Node.js 20.9 or later. It reads the key from the GETSCREENSHOT_API_KEY environment variable. To register the local server with Claude Code:
claude mcp add --env GETSCREENSHOT_API_KEY=YOUR_API_KEY --transport stdio getscreenshot -- npx -y getscreenshot-mcp
Other clients
Cursor, Claude Desktop and most other MCP clients take a JSON block of this shape:
{
"mcpServers": {
"getscreenshot": {
"command": "npx",
"args": ["-y", "getscreenshot-mcp"],
"env": { "GETSCREENSHOT_API_KEY": "YOUR_API_KEY" }
}
}
}
The file that holds this block differs per client. Step-by-step setup for each client is at getscreenshotapi.com/agents.
Try it
Once the server is connected, ask the agent something like:
Take a screenshot of https://example.com and tell me what is above the fold.
Tools
The server is named getscreenshot and exposes five tools. All of them are read-only: they do not change anything on the pages they capture.
| Tool | What it does | Quota cost |
|---|---|---|
capture_screenshot |
Captures a public web page as an image the model can see. | 1 screenshot |
render_html |
Renders an HTML string and captures it. | 1 screenshot |
compare_screenshots |
Visual diff of two pages or two earlier screenshots. | 1 screenshot for each page it has to capture |
capture_pdf |
Saves a page as an A4 PDF. | 1 screenshot |
get_usage |
Reports screenshots used, the monthly limit and the reset date. | 1 screenshot |
Quota is counted per API request, so a capture that fails still uses one unit.
capture_screenshot
Captures a public web page and returns it as one or more images.
| Input | Type | Default | Description |
|---|---|---|---|
url |
string | required | Page to capture. Must be a public http or https URL. URL shorteners are rejected. |
full_page |
boolean | false |
Capture the full scrollable page instead of the viewport. Tall pages come back as several slices. |
element |
string | none | CSS selector. Captures only that element. |
device |
string | none | Device preset. Sets the viewport and, for phones, a mobile user agent. See Device presets. |
width |
integer | 1280 |
Viewport width in CSS pixels. Ignored when device is set. |
height |
integer | 800 |
Viewport height in CSS pixels. Ignored when device is set. |
scale |
integer | 1 |
Device pixel ratio of the stored image: 1, 2 (retina) or 3. Inline images are downsized either way. |
format |
string | png |
png or jpeg. This is the format of the stored file at screenshot_url. Inline images are always JPEG. |
wait_until |
string | networkidle2 |
When the page counts as loaded: load, domcontentloaded, networkidle0 or networkidle2. domcontentloaded is the fastest and the most reliable on heavy sites. |
wait_ms |
integer | 2000 |
Extra wait before the capture, in milliseconds, from 0 to 20000. |
hide_selectors |
string | none | CSS selector or selectors to hide before the capture. |
hide_cookie_banners |
boolean | true |
Hide common cookie banners. |
hide_chat_widgets |
boolean | false |
Hide common chat widgets such as Intercom and Drift. |
click |
string | none | CSS selector of an element to click once before the capture, for example to open a menu. |
custom_css |
string | none | CSS injected before the capture. |
custom_js |
string | none | JavaScript injected before the capture. |
highlight |
string | none | Word or phrase to highlight on the page. |
cookie |
object | none | One cookie to set for the target host, as an object with name and value. Meant for things like a feature flag or a locale. Do not pass credentials or session tokens. |
lang |
string | en-US |
Browser language. |
transparent_background |
boolean | false |
Keep the background transparent where the page does not set one. Applies to the stored PNG. Inline images are flattened onto white. |
full_page_strategy |
integer | 0 |
Full-page capture strategy, from 0 to 3. Try another value if a full-page capture renders badly. |
detail |
string | standard |
standard or high. Controls how large the images sent to the model are. See Vision sizing. |
max_slices |
integer | 4 |
Maximum number of images returned for a tall capture, from 1 to 10. |
return |
string | image_and_url |
image_and_url returns inline images and the URL. url_only returns the URL without inline images. |
Example call:
{
"url": "https://example.com",
"wait_until": "domcontentloaded"
}
Example structured result. The values are illustrative:
{
"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": 800 },
"images": [
{ "index": 0, "y": 0, "width": 1280, "height": 800, "estimated_tokens": 1334 }
],
"total_slices": 1,
"truncated": false,
"estimated_image_tokens": 1334,
"expires_in_days": 30,
"warnings": []
}
Alongside this the agent receives a short text summary and the image itself. The full shape is described under Output contract.
render_html
Renders an HTML string and captures it. Use it for a component or page the agent just wrote, or for anything that is not reachable from the public internet.
| Input | Type | Default | Description |
|---|---|---|---|
html |
string | required | The HTML to render. Up to 2 MB. |
full_page |
boolean | false |
Capture the full scrollable page. |
element |
string | none | CSS selector. Captures only that element. |
device |
string | none | Device preset. See Device presets. |
width |
integer | 1280 |
Viewport width in CSS pixels. Ignored when device is set. |
height |
integer | 800 |
Viewport height in CSS pixels. Ignored when device is set. |
scale |
integer | 1 |
Device pixel ratio of the stored image: 1, 2 or 3. |
wait_ms |
integer | 2000 |
Extra wait before the capture, in milliseconds. |
detail |
string | standard |
standard or high. |
max_slices |
integer | 4 |
Maximum number of images returned, from 1 to 10. |
return |
string | image_and_url |
image_and_url or url_only. |
The capture service can only load public URLs, so the HTML is hosted at an unguessable temporary URL on GetScreenshot’s hosted service. It is deleted as soon as the capture returns (and after five minutes at the latest). The page runs in a sandbox without cookies or localStorage, so code that depends on them may render blank. The local server uploads the HTML there for you. The page is then captured through the normal API, and the result has the same shape as capture_screenshot.
Things to know:
- Relative asset URLs do not resolve, because the HTML is not served from your project. Inline the CSS and images, load them from absolute public URLs, or set
<base href="https://your-site.example/">so relative URLs point at a public host. - Cookie banner hiding is off for this tool, so the page renders as written.
- Do not put secrets in the HTML. The resulting image link is public to anyone who has it.
Example call:
{
"html": "<!doctype html><html><body style=\"font-family: sans-serif; padding: 40px\"><h1>Pricing</h1><p>Three plans.</p></body></html>",
"width": 390,
"height": 844
}
compare_screenshots
Visual diff of two pages or two existing screenshots. Use it for before and after a change, or staging against production.
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.
| Input | Type | Default | Description |
|---|---|---|---|
before |
object | required | Either an object with url (a page to capture now) or an object with screenshot_url (a URL from an earlier GetScreenshot result). |
after |
object | required | Same shape as before. |
full_page |
boolean | false |
Capture full pages instead of the viewport. Applies to sides given as url. |
width |
integer | 1280 |
Viewport width for both sides. |
height |
integer | 800 |
Viewport height for both sides. |
device |
string | none | Device preset for both sides. |
hide_selectors |
string | none | CSS selector or selectors to hide on both sides. Useful for ads, timestamps and other content that changes on every load. |
wait_until |
string | networkidle2 |
Load condition for both sides. |
wait_ms |
integer | 2000 |
Extra wait for both sides, in milliseconds. |
threshold |
number | 0.1 |
Per-pixel colour tolerance, from 0 (any difference counts) to 1 (nothing counts). The default ignores anti-aliasing noise. |
Example call:
{
"before": { "url": "https://www.example.com/pricing" },
"after": { "url": "https://staging.example.com/pricing" },
"hide_selectors": ".timestamp"
}
Each side must contain exactly one of url or screenshot_url. Only GetScreenshot storage URLs are accepted as screenshot_url.
Example structured result. The values are illustrative:
{
"changed_percent": 2.4,
"changed_pixels": 24576,
"total_pixels": 1024000,
"identical": false,
"threshold": 0.1,
"bounding_box": { "x": 96, "y": 180, "width": 640, "height": 220 },
"size_changed": false,
"compared": { "width": 1280, "height": 800 },
"before": {
"screenshot_url": "https://storage.googleapis.com/getscreenshot-storage/imageAbC123xYz9.png",
"origin_url": "https://www.example.com/pricing",
"page_status": 200,
"width": 1280,
"height": 800
},
"after": {
"screenshot_url": "https://storage.googleapis.com/getscreenshot-storage/imageDeF456uVw0.png",
"origin_url": "https://staging.example.com/pricing",
"page_status": 200,
"width": 1280,
"height": 800
},
"images": [
{ "index": 0, "y": 60, "width": 1280, "height": 460, "estimated_tokens": 782 }
],
"total_slices": 1,
"truncated": false,
"estimated_image_tokens": 782,
"expires_in_days": 30,
"warnings": []
}
| Field | Description |
|---|---|
changed_percent |
Share of compared pixels that differ, from 0 to 100. |
changed_pixels, total_pixels |
The raw counts behind the percentage. |
identical |
true when no pixel differs and both images have the same size. |
bounding_box |
Smallest rectangle that contains every changed pixel. null when nothing changed. |
size_changed |
true when the two images differ in size, for example because the page got taller. |
compared |
Size both images were normalised to before comparing. |
before, after |
The screenshot URL, page URL, page status and size of each side. origin_url and page_status are null for a side given as screenshot_url. |
When something changed, the agent also receives a diff image inline: the after image dimmed, changed pixels in magenta, and a red rectangle around the changed area. The image is cropped to the rows that changed, plus a margin, and images[].y gives its offset within the comparison image. When nothing changed, no image is attached.
Each side given as a url costs one screenshot. A side given as a screenshot_url costs nothing, so comparing two earlier results uses no quota. To check a change, capture the page first, make the change, then pass the earlier screenshot_url as before and the page url as after.
capture_pdf
Saves a page as an A4 PDF.
| Input | Type | Default | Description |
|---|---|---|---|
url |
string | required | Page to save. Must be a public http or https URL. |
wait_until |
string | networkidle2 |
Load condition. |
wait_ms |
integer | 2000 |
Extra wait before the capture, in milliseconds. |
hide_selectors |
string | none | CSS selector or selectors to hide. |
custom_css |
string | none | CSS injected before the capture. |
Example structured result:
{
"pdf_url": "https://storage.googleapis.com/getscreenshot-storage/pdfAbC123xYz9.pdf",
"origin_url": "https://example.com/terms",
"page_status": 200,
"captured_at": "2026-11-18T14:03:22Z",
"expires_in_days": 30,
"warnings": []
}
The PDF is not shown to the model. pdf_url is a public link that works for 30 days. To look at a page, use capture_screenshot.
get_usage
Takes no inputs. Returns the number of screenshots used this month, the monthly limit, how many are left and the date the quota resets, for the configured API key.
Example structured result:
{
"used": 1500,
"limit": 6000,
"remaining": 4500,
"percent_used": 25,
"period": "MONTH",
"quota_restart_date": "2026-12-01",
"resets_on": "2026-12-01"
}
The call itself costs one unit of quota, so do not call it routinely. Use it before a large batch of captures or after a quota error.
Device presets
device accepts these names:
| Preset | Viewport |
|---|---|
iphone5 |
iPhone 5 |
iphone678 |
iPhone 6, 7, 8 |
iphone678_plus |
iPhone 6, 7, 8 Plus |
iphonex |
iPhone X and XS |
iphone12 |
iPhone 12 and 13 (390 x 844) |
pixel2 |
Google Pixel 2 |
pixel2_xl |
Google Pixel 2 XL |
ipad |
iPad, portrait |
ipadpro |
iPad Pro, portrait |
hvga |
320 x 480 |
wvga |
480 x 800 |
dvga |
640 x 960 |
wxga_v |
768 x 1280 |
xga |
1024 x 768 |
wxga_s |
1280 x 800 |
wxga_l |
1366 x 768 |
sxga |
1280 x 1024 |
wsxga_plus |
1680 x 1050 |
Output contract
capture_screenshot and render_html return three things:
- A text summary of the capture.
- One or more inline images. These are JPEG at roughly quality 80, sized for vision models. A tall capture is cut into slices from top to bottom.
- A
structuredContentobject with these fields:
| Field | Description |
|---|---|
screenshot_url |
URL of the original, full-resolution file. |
origin_url |
The page that was captured. |
page_status |
HTTP status code the page returned. |
captured_at |
Time of the capture, ISO 8601 in UTC. |
format |
Format of the stored file, png or jpeg. |
original |
width and height of the stored file in pixels. null if the stored file could not be read. |
images |
One entry per inline image, in the same order as the images: index (counted from 0, top to bottom), y (top offset of the slice within the downsized capture), width, height and estimated_tokens. |
total_slices |
Number of slices the whole capture needs at this detail level. |
truncated |
true when total_slices is larger than the number of images returned, so the bottom of the page is not shown inline. |
estimated_image_tokens |
Sum of estimated_tokens over the returned images. |
expires_in_days |
Stored files are deleted after this many days. Currently 30. |
warnings |
Notes about this result, for example that the page answered with an HTTP error status. |
The inline images are downsized copies. The original stays at screenshot_url for 30 days. That URL is public: anyone who has the link can fetch the file, so treat it like an unlisted link and do not capture pages that show secrets.
With return set to url_only the agent gets the summary and the structured result without inline images, so the call uses no image tokens. Use it when the agent needs the file but does not need to look at it.
Check page_status. A value of 400 or above usually means the capture shows the site’s error page.
Vision sizing
Vision models charge by image area, and they downscale large images on their side anyway. The server resizes before sending, so the agent pays for pixels the model can use.
detail |
Maximum width | Maximum long edge | Maximum per image |
|---|---|---|---|
standard |
1280 px | 1568 px | about 1,568 tokens |
high |
1920 px | 2576 px | about 4,784 tokens |
A capture that does not fit in one image is cut into slices. max_slices caps how many are returned. The default is 4. Slices are also left out if the inline images would exceed about 1.5 MB in total (4 MB at high detail); the result then has truncated: true and a warning.
Token figures in this section are approximate. They are computed as ceil(width / 28) × ceil(height / 28), which follows how Claude models count image tokens. Other models count differently, but the relative sizes hold.
| Capture | detail |
Images sent to the model | Approximate tokens |
|---|---|---|---|
| 1280 x 800 viewport (the default) | standard |
1 image, 1280 x 800 | 1,334 |
390 x 844 viewport (device: iphone12) |
standard |
1 image, 390 x 844 | 434 |
| 1920 x 1080 viewport | standard |
1 image, downsized to 1280 x 720 | 1,196 |
| 1920 x 1080 viewport | high |
1 image, 1920 x 1080 | 2,691 |
| 1280-wide full page | standard |
slices up to 1280 x 952, 4 returned by default | 1,564 per full slice, up to 6,256 for 4 |
| 1920-wide full page | high |
slices up to about 1920 x 1932 | about 4,761 per full slice |
Practical guidance for agents:
- Start with a viewport capture at
standarddetail. It costs about 1,334 tokens and answers most layout questions. - Use
elementto look at one component instead of the whole page. - Use
full_pagewhen the question is about content below the fold. Fourstandardslices cover the first 3,808 pixels of a 1280-wide page. - If
truncatedistrueand the rest of the page matters, raisemax_slicesor capture a specificelement. - Use
highonly when small text has to be read exactly.
Errors
A failed call returns an MCP tool result with isError set to true and a text message the agent can act on. These are the main cases:
| Situation | What it means | What the agent should do |
|---|---|---|
| No API key configured | The server has no key to call the API with. Every tool returns an error that explains how to get a key and how to set it. | Ask the user to set GETSCREENSHOT_API_KEY or the Authorization header. |
| API key not recognised | The key is wrong or mistyped. | Ask the user to check the key. Do not retry. |
| API key disabled | The subscription was cancelled or a payment failed. The API sometimes answers an unrecognised key the same way. | Ask the user to check the key and their account at getscreenshotapi.com/account. Do not retry. |
| Monthly quota used up | No screenshots are left this month. | Stop capturing and tell the user. |
| Rate limited | Too many requests in a short time. | Wait and retry with backoff. |
| Invalid URL | url is missing or is not a valid http or https URL. |
Fix the URL. |
| Localhost or private address | The capture service cannot reach it. The server rejects the call before it reaches the API, so no quota is used. | Use render_html, or a public preview URL or tunnel. |
| URL not allowed | The URL is a shortener or a blocked domain. | Use the final destination URL. |
| Page did not load in time | The page is slow, offline, or refuses automated browsers. | Retry once with wait_until set to domcontentloaded. If it fails again, report it. |
| Capture crashed | Most often the element selector matched nothing or the click selector is wrong. An unknown device name does not get this far: the tool’s input schema rejects it before anything is captured. |
Check the selector and retry. |
| Timed out | The capture took longer than 90 seconds. | Retry with domcontentloaded, a smaller wait_ms, or without full_page. |
Failed captures count toward the monthly quota, so retry once with different settings instead of repeating the same call.
Limits
- No localhost or private networks. The capture runs on GetScreenshot’s servers, so it cannot reach
localhost, a dev server on your machine, or hosts inside a private network. Userender_html, a public preview URL, or a tunnel. - Single captures, not browsing sessions. Each call loads one page and captures it. One
clickand onecookieare supported per call. Multi-step flows behind a login need a browser automation tool such as Playwright MCP. - Bot protection. Sites with aggressive bot protection may refuse headless browsers.
- 90 second timeout. A typical capture takes about 9 seconds, and slow pages around 25. Anything over 90 seconds fails.
- 30 day storage. Screenshots and PDFs are deleted after 30 days.
- Public URLs. Stored files have random names but no access control.
- HTML size.
render_htmlaccepts up to 2 MB of HTML.
FAQ
Which plans include the MCP server?
All of them. The MCP server, the CLI and the agent skill call the REST API, so any API key works, including the $5 Lincoln plan. Each capture uses one screenshot from the monthly allowance.
Hosted or local?
Use the hosted endpoint when the client supports remote MCP servers with custom headers, or when the agent runs somewhere it cannot start a local process. Use the local server when the client only supports stdio. Both expose the same tools.
Can the agent screenshot my local dev server?
Not by URL. Pass the HTML to render_html, or expose the dev server through a public preview URL or a tunnel and capture that.
I asked for PNG. Why are the inline images JPEG?
format controls the stored file at screenshot_url. The inline copies are always JPEG because they are smaller to transfer and the model sees the same content.
How do I keep token use down?
Capture the viewport or a single element at standard detail, and lower max_slices for full pages. Use return set to url_only when the model does not need to see the image.
Is there a command-line version?
Yes. The same package ships a CLI and an agent skill. See CLI and Agent Skill. To call the REST API from your own agent code, see Quickstart for LLMs and agent builders.