mcp-playwright-screenshot

MCP server that captures webpage screenshots using Playwright and returns the PNG image as base64 via MCP "image" content. Includes domain safety guards and size limits.

• Tech: TypeScript, Playwright, MCP SDK, stdio transport
• Tool name: screenshot
• Output: image/png (base64)

Features

• Playwright chromium, headless
• Full-page or viewport screenshots
• Viewport and deviceScaleFactor control
• Navigation waitUntil: load | domcontentloaded | networkidle (default)
• Security:
  • Only http/https
  • Blocks government domains (*.gov, *.gov.TLD)
  • Blocks localhost and private IP ranges (127/8, 10/8, 172.16–31/12, 192.168/16, ::1, fc00::/7, fe80::/10)
• Limits:
  • Max viewport width: 12000
  • Max viewport and full-page height: 100000

Project structure

• src/server.ts: MCP server (stdio), tool wiring, Zod input schema
• src/screenshot.ts: Playwright logic, validation, PNG base64 result
• src/types.ts: Types, ErrorCodes, CodedError
• src/security/domainGuard.ts: URL normalization and domain/IP guard
• src/security/sizeGuard.ts: Viewport/full-page size guards
• src/utils/file.ts: File utilities (not used by tool output; kept for potential file saving)

Requirements

• Node.js 18+ (ESM, NodeNext)
• npm
• Playwright browsers: install with npx playwright install

Install

npm install
npx playwright install

Scripts

# Dev (TypeScript via ts-node/esm)
npm run dev

# Build to dist/
npm run build

# Start built server
npm start

Server runs as an MCP stdio server (reads/writes JSON-RPC over stdio).

MCP tool

• Name: screenshot
• Description: Capture a URL as PNG; returns base64 image content; includes domain/size guards.

Input schema (Zod, defaults shown):

• url: string (required, http/https only)
• fullPage: boolean = true
• viewport: { width: number; height: number } (default 1280x800)
• deviceScaleFactor: number = 1 (> 0)
• waitUntil: "load" | "domcontentloaded" | "networkidle" = "networkidle"
• timeoutMs: number = 30000 (positive integer)
• darkMode: boolean = false

Output:

• content: [{ type: "image", data: , mimeType: "image/png" }]

Example (JSON-RPC over stdio)

List tools:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list"
}

Call screenshot:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "screenshot",
    "arguments": {
      "url": "https://example.com",
      "fullPage": true,
      "viewport": { "width": 1280, "height": 800 },
      "deviceScaleFactor": 1,
      "waitUntil": "networkidle",
      "timeoutMs": 30000,
      "darkMode": false
    }
  }
}

Successful result (truncated):

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [
      {
        "type": "image",
        "data": "iVBORw0KGgoAAA... (base64) ...",
        "mimeType": "image/png"
      }
    ]
  }
}

Error handling

All errors return isError: true with a text message. Error codes:

• E_INVALID_URL: URL invalid or not http/https
• E_BLOCKED_DOMAIN: Government domain or localhost/private IP is blocked
• E_SIZE_EXCEEDED: Viewport or page size out of bounds; invalid numeric params
• E_NAVIGATION_TIMEOUT: Page navigation timed out
• E_SCREENSHOT_FAILED: Navigation or screenshot failure
• E_IO_ERROR: Generic I/O error

Example error response:

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "isError": true,
    "content": [
      { "type": "text", "text": "E_BLOCKED_DOMAIN: 禁止访问政府类站点: example.gov" }
    ]
  }
}

Security notes

• Hostname normalized (lowercase, Punycode) before checks
• Blocks: *.gov and *.gov.TLD; localhost; private IP literals (IPv4, IPv6)
• No DNS resolution is performed for security checks

Behavior notes

• Headless chromium
• PNG only
• darkMode switches colorScheme to "dark"
• Full page height is validated before screenshot

Development

• ESM + TypeScript (NodeNext)
• Zod for request validation
• Stdio transport via @modelcontextprotocol/sdk

License

MIT (add a LICENSE file if required).