# shotbot-mcp

MCP server for the [Shotbot](https://www.shotbot.net/) 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

```bash
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):

```json
{
  "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`):

```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+):
```bash
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 | avif | pdf  (Pro: all formats)
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 | mobile | tablet | 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, avif, pdf |
| Viewports | 390, 768, 1280 | 280-3840 px |
| Max wait | 5 s | 30 s |
| Concurrent | 3 | 15 |
| Batch size | 500 | 5000 |
| Advanced options | - | dismiss_cookies, selector, crop_height, http_auth, block_ads |

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