MCP Server

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:

  1. A text summary of the capture.
  2. 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.
  3. A structuredContent object 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 standard detail. It costs about 1,334 tokens and answers most layout questions.
  • Use element to look at one component instead of the whole page.
  • Use full_page when the question is about content below the fold. Four standard slices cover the first 3,808 pixels of a 1280-wide page.
  • If truncated is true and the rest of the page matters, raise max_slices or capture a specific element.
  • Use high only 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. Use render_html, a public preview URL, or a tunnel.
  • Single captures, not browsing sessions. Each call loads one page and captures it. One click and one cookie are 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_html accepts 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.


/v1/usage
CLI and Agent Skill

Related Docs