WebsiteScreenshot.online MCP Server

A Model Context Protocol server that wraps the WebsiteScreenshot.online REST API and exposes it as three MCP tools any MCP-compatible host (Claude Desktop, Claude Code, Cursor, Cline, Continue, Zed, Raycast, …) can call directly.

---

⚡ Most users don't need this package

If you just want your AI assistant to take screenshots and record videos, use the hosted endpoint instead — zero install, one line of JSON:

https://websitescreenshot.online/api/mcp

See the per-host configuration snippets for Claude Code, Claude Desktop, Cursor, Cline, Codex CLI, Gemini CLI, Continue, Windsurf, and Zed.

You only need this npm package if one of the following applies:

• 🛰️ Air-gapped or restricted network — your AI host cannot reach websitescreenshot.online directly.
• 🏠 Self-hosted WebsiteScreenshot — you run your own instance and need SCREENSHOT_API_BASE pointing at it.
• 🔧 You want to audit / modify the server — this is the same code the hosted endpoint runs, just without the Next.js wrapper.

In every other case, the hosted endpoint is strictly better (no Node dependency, automatic updates, no maintenance burden).

---

1. Prerequisites

• Node.js ≥ 18.18 (LTS recommended)
• A free or paid WebsiteScreenshot.online account
• A WebsiteScreenshot.online API key (see § 2)

---

2. Get an API key

1. Sign up at https://websitescreenshot.online (GitHub OAuth or email).
2. Switch to your locale if needed (e.g. /en/dashboard/api-keys, /zh-CN/dashboard/api-keys).
3. Open Dashboard → API Keys → Create new key.
4. Copy the key. It starts with ws_ followed by 64 hex chars (e.g. ws_<your-key-here>) and is shown once — store it somewhere safe.

The MCP server only ever reads the key from the environment. It is never logged, never sent to the model, and never written to disk by this package.

---

3. Install & build

git clone https://github.com/Website-Screenshot-Online/websitescreenshot-mcp.git
cd websitescreenshot-mcp
npm install
npm run build

That's it — build/index.js is a self-contained executable you can wire into any MCP host.

---

4. Configure your MCP host

Claude Desktop — claude_desktop_config.json

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

{
  "mcpServers": {
    "websitescreenshot": {
      "command": "node",
      "args": ["/absolute/path/to/websitescreenshot-mcp/build/index.js"],
      "env": {
        "SCREENSHOT_API_KEY": "ws_replace_with_your_real_api_key",
        "SCREENSHOT_REQUEST_TIMEOUT_MS": "60000"
      }
    }
  }
}

Claude Code — ~/.claude.json

{
  "mcpServers": {
    "websitescreenshot": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/websitescreenshot-mcp/build/index.js"],
      "env": {
        "SCREENSHOT_API_KEY": "ws_replace_with_your_real_api_key"
      }
    }
  }
}

Cursor / VS Code (.cursor/mcp.json)

{
  "mcpServers": {
    "websitescreenshot": {
      "command": "node",
      "args": ["/absolute/path/to/websitescreenshot-mcp/build/index.js"],
      "env": { "SCREENSHOT_API_KEY": "ws_replace_with_your_real_api_key" }
    }
  }
}

Cline / Continue / Zed / Raycast

All accept the same command + args + env shape — just point them at build/index.js and pass SCREENSHOT_API_KEY through env.

Restart the host after editing its config and the three tools will show up in its tool palette.

---

5. Self-hosted WebsiteScreenshot

If you run your own WebsiteScreenshot instance, point the server at it:

"env": {
  "SCREENSHOT_API_KEY": "ws_replace_with_your_real_api_key",
  "SCREENSHOT_API_BASE": "https://your-self-hosted.example.com"
}

---

6. Usage examples

You don't write JSON manually — the model does. These are the payloads the model will actually send.

Screenshot — viewport of a landing page

take_screenshot({
  url: "https://example.com",
  resolution: { width: 1440, height: 900 },
  format: "png",
  fullSize: false,
  blockAds: true,
  blockCookiesGdpr: true,
  delay: 1
})

Screenshot — full-page PDF for archival

take_screenshot({
  url: "https://news.ycombinator.com",
  fullSize: true,
  format: "pdf"
})

Synchronous video (≤ 6 min)

record_website_video({
  url: "https://stripe.com",
  format: "mp4",
  scrollMode: "smooth",
  smoothScrollSpeed: "normal",
  resolution: { width: 1280, height: 720 }
})

Async video + status polling

record_website_video({ url: "https://stripe.com", async: true })
// → { "success": true, "requestId": "f7c1..." }

check_video_status({ requestId: "f7c1..." })
// → { "status": "pending", ... }  // poll again
// → { "status": "completed", "videoUrl": "https://...", ... }

---

7. Tool reference

take_screenshot

Field	Type	Default	Notes
url	string (URL)	—	required
resolution	{ width, height }	1920×1080	Any preset or custom size
fullSize	bool	false	Capture entire scrollable page
format	png | jpeg | pdf	png
blockCookiesGdpr	bool	true	Dismiss cookie banners first
blockAds	bool	true	Block ad networks
delay	int (0–10 seconds)	1	Wait before capturing

Response shape:

{
  "success": true,
  "imageUrl": "https://websitescreenshot.online/screenshots/abc.png",
  "filename": "abc.png"
}

record_website_video

Same fields as above plus:

Field	Type	Default
format	webm | mp4 | gif	webm
scrollMode	step | smooth	step
smoothScrollSpeed	slow | normal | fast	normal
scrollDistance	int 100–1000 (px)	500
scrollDelay	int 200–5000 (ms)	1000
async	bool	false

Sync response:

{ "success": true, "videoUrl": "https://…/abc.webm", "filename": "abc.webm" }

Async response:

{ "success": true, "requestId": "f7c1…" }

check_video_status

Field	Type
requestId	string

Response:

{
  "status": "completed",
  "siteUrl": "https://…",
  "result": { "success": true, "videoUrl": "https://…", "filename": "abc.webm" },
  "updatedAt": 1730000000000
}

status is one of pending | completed | error. Results are kept for 24 hours then deleted.

---

8. Error handling

Every API error is mapped to an MCP isError: true result containing code, status, and error fields. Common codes:

Code	Meaning
UNAUTHORIZED	Missing / revoked key
RATE_LIMITED	Per-key or per-IP limit hit; retry later
USAGE_LIMIT_EXCEEDED	Plan quota exhausted
INVALID_PARAMETERS	Input failed Zod validation
INTERNAL_ERROR	Server-side bug; retry with backoff
TIMEOUT	Request took longer than SCREENSHOT_REQUEST_TIMEOUT_MS
NOT_FOUND	requestId unknown or expired

Rate limits: 10 screenshots / min and 5 videos / min per API key.

---

9. Environment variables

Variable	Required	Default	Purpose
SCREENSHOT_API_KEY	yes	—	The Bearer token sent to the API
SCREENSHOT_API_BASE	no	https://websitescreenshot.online	Override for self-hosted / staging
SCREENSHOT_REQUEST_TIMEOUT_MS	no	60000	Per-request abort timeout (ms)

---

10. Development

npm run dev       # tsx, hot reload stdio
npm run lint      # type-check only
npm run build     # emit build/index.js

To point the dev server at a self-hosted API:

SCREENSHOT_API_BASE=http://localhost:3000 \
SCREENSHOT_API_KEY=ws_dev_replace_me \
npm run dev

---

11. License

MIT © Crownbyte LTD — see LICENSE.

Website: https://websitescreenshot.online Hosted MCP: https://websitescreenshot.online/api/mcp Docs: https://websitescreenshot.online/en/docs/mcp Support: support@websitescreenshot.online