shotbot-mcp

shotbot-mcp

MCP server for the Shotbot screenshot API. Exposes four tools so AI agents (Claude Code, Claude Desktop, Cursor, Windsurf, etc.) can take screenshots directly.

Install

No local files, no Node.js, no npm. The server runs on api.shotbot.net.

Get a free API key at https://www.shotbot.net/screenshot-api-key/

Configure

Claude Code

claude mcp add --scope user shotbot --transport http "https://api.shotbot.net/mcp?key=your-key"

Then claude mcp list to confirm, and just ask Claude Code to capture a URL. Full guide: https://www.shotbot.net/claude-code-screenshots/

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "shotbot": {
      "url": "https://api.shotbot.net/mcp?key=your-key"
    }
  }
}

Cursor / Windsurf

Add to your MCP settings file (.cursor/mcp.json or .windsurf/mcp.json):

{
  "mcpServers": {
    "shotbot": {
      "url": "https://api.shotbot.net/mcp?key=your-key"
    }
  }
}

Transport

The server runs as an HTTP Streamable MCP endpoint (https://api.shotbot.net/mcp). Pass your API key as a ?key= query parameter - no environment variables needed.

A stdio version is also available for local/offline use (requires Node.js 18+).

Via npm (no install, runs through npx):

claude mcp add --scope user --env SHOTBOT_API_KEY=your-key shotbot -- npx -y shotbot-mcp

Or run it directly: SHOTBOT_API_KEY=your-key npx -y shotbot-mcp

Single file, no npm:

curl -fsSL https://api.shotbot.net/shotbot-mcp/index.mjs -o index.mjs
curl -fsSL https://api.shotbot.net/shotbot-mcp/package.json -o package.json
npm install
SHOTBOT_API_KEY=your-key node index.mjs

Tools

capture

Take a screenshot of any public URL.

url                    (required) - public http/https URL
format                 jpg | png | webp | webp_lossless | avif | pdf  (non-Pro: jpg only)
viewport_width         390/768/1280 (free) | 280-3840 (Pro)
output_size            output width in px
fullpage               capture full page height
wait                   seconds to wait before capture (0-5 free, 0-30 Pro)
color_scheme           dark | light
ratio                  16:9 | 4:3 | 1:1 | 9:16 | ...
crop_height            custom height in px, cropped from top (Pro)
selector               CSS selector to clip output (Pro)
scroll_before_capture  scroll to trigger lazy-loaded content (Pro)
nojs                   disable JavaScript
hidpi                  render at 2× device pixel ratio (retina)
dismiss_cookies        '' | accept | reject - cookie banner handling (Pro)
block_ads              block ads and trackers (Pro)
http_auth              { user, pass } - HTTP Basic Auth (Pro)
cookies                [{ name, value, domain?, path?, httpOnly?, secure? }] max 50 (Pro)
render_region          fr-paris (free) | ca-montreal | sg-singapore | au-sydney | vn-hanoi (Pro)
preset                 og | mobile | square | reel | ... (named output bundle)
frame                  rounded | shadow | browser_chrome | browser_chrome_dark | mobile | mobile_light | tablet | tablet_light | laptop | polaroid | gradient | shotbot_brand
pdf_page_size          A4 | A3 | A5 | Letter | Legal | Tabloid   (format=pdf)
pdf_margin_mm          0-50           (format=pdf)
pdf_scale              0.10-2.00      (format=pdf)
pdf_landscape          landscape orientation (format=pdf)
cdn                    true = publish to the public CDN (permanent URL); default: private (download link, auto-expires)
callback_url           HTTPS webhook for async delivery
callback_secret        shared secret echoed in callback payload

get_status

Poll the status of a capture by token. Returns queued | processing | done | failed. When done: image_url (public cdn captures) or download (private captures; fetchable until it auto-expires).

token (required) - 32-character alphanumeric token [A-Za-z0-9]

batch

Submit up to 500 URLs (Pro: 5000) in one atomic request. Returns a token per URL. Quota is deducted atomically - no partial batches.

jobs           (required) - array of {url, ...options}
format         default format for all jobs
viewport_width default viewport for all jobs
callback_url   HTTPS webhook, called once per completed job

account_status

Get plan (free | pro), credit balance, and monthly quota usage.

Free vs Pro

Feature	Free	Pro
Formats	jpg only	jpg, png, webp, webp_lossless, avif, pdf
Viewports	390, 768, 1280	280-3840 px
Max wait	5 s	30 s
Concurrent	3	15
Batch size	500	5000
Render regions	fr-paris	+ ca-montreal, sg-singapore, au-sydney, vn-hanoi
Pro options	-	dismiss_cookies, selector, crop_height, http_auth, block_ads, cookies, scroll_before_capture, autoplay_videos

Pro subscription: https://www.shotbot.net/pro/