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).

Related MCP server: Grabbit

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

Response shape:

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

record_website_video

Same fields as above plus:

Sync response:

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

Async response:

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

check_video_status

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:

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

9. Environment variables

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