BrowserLoop MCP Server: Playwright Full-Page Element Screenshots

Overview

BrowserLoop MCP Server is a lightweight, Playwright-backed microservice that captures high-quality screenshots and PDFs of web pages and specific DOM elements. It implements a Model Context Protocol (MCP) compatible HTTP endpoint so language models and other automation tooling can request rendered snapshots with a single JSON call — without having to manage headless browser lifecycles or Playwright configuration directly.

This server is useful for developers building web scrapers, visual regression pipelines, monitoring tools, or AI agents that need precise visual context. It supports full-page captures, element clipping by selector, configurable viewports and device pixel ratios, cookie-based authentication, and output formats suitable for automation (PNG, JPEG, WebP, PDF).

Features

• Playwright-based rendering for Chromium/Firefox/WebKit
• Full-page and element-specific screenshots
• PDF export (print-style) in addition to bitmap formats
• Format options: PNG, JPEG, WebP, PDF
• Configurable viewport size, deviceScaleFactor and quality
• Cookie-based authentication for logged-in pages
• Optional transparent background (omitBackground)
• Waiting strategies: fixed delay or wait-for-selector
• MCP-compatible HTTP API designed for model/tool integrations
• Runs locally or in containers; suitable for CI, servers, and agents

Installation / Configuration

Clone the repository and run the server locally, or use the provided Docker image.

Install and run locally (Node.js):

# clone
git clone https://github.com/mattiasw/browserloop.git
cd browserloop

# install & build (if using Node)
npm install
npm run build
npm start

Run with environment variables (examples):

# start on port 8080 with headless mode and limited concurrency
PORT=8080 HEADLESS=true MAX_CONCURRENCY=4 npm start

Docker example:

# Pull and run (image name may vary by project release)
docker run -p 8080:8080 \
  -e HEADLESS=true \
  -e MAX_CONCURRENCY=4 \
  mattiasw/browserloop:latest

Common environment variables

Note: If you want to use a custom Playwright browser binary, provide the appropriate Playwright environment variables or mount browser artifacts into the container.

Available Resources

• GitHub repository: https://github.com/mattiasw/browserloop
• Playwright docs: https://playwright.dev
• MCP (Model Context Protocol): general MCP tooling and client libraries (useful when integrating with LLM agents)

API (MCP) — Screenshot Tool

The server exposes an MCP-compatible JSON HTTP endpoint. The request contains the tool name and an arguments object describing the capture. The following example demonstrates the most common fields.

Example request (curl):

curl -X POST http://localhost:8080/ \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "screenshot",
    "arguments": {
      "url": "https://example.com",
      "format": "png",
      "fullPage": true,
      "viewport": { "width": 1280, "height": 800 },
      "deviceScaleFactor": 2,
      "waitFor": 1000,
      "cookies": [
        { "name": "session", "value": "abc123", "domain": "example.com", "path": "/" }
      ]
    }
  }'

A typical response returns a base64-encoded payload with content-type metadata:

{
  "status": "ok",
  "result": {
    "mimeType": "image/png",
    "data": "<base64-encoded-image>"
  }
}

Parameters reference

Use Cases

• Scheduled visual monitoring