BrowserLoop

⚠️ ARCHIVED: This project is archived and will not receive any further updates. With the release of Chrome DevTools MCP, a dedicated MCP server for browser automation is no longer necessary as that project provides more comprehensive browser interaction capabilities including screenshots, console monitoring, and much more.

A Model Context Protocol (MCP) server for taking screenshots and reading console logs from web pages using Playwright. This tool allows AI agents to automatically capture screenshots and monitor browser console output for debugging, testing, and development tasks.

NOTE: Almost all of the code in this repository has been auto-generated. That means you should probably not trust it too much. That being said, it does work and I'm using it myself.

NOTE: If the documentation is incorrect, please let me know or send a PR. If you too want to use a code generation tool to update the code for this project, PROJECT_CONTEXT.md has been used as context to give a good overview of the various parts of the project. It might be a bit messy now but it's a good starting point and you're welcome to update it.

Features

• 📸 High-quality screenshot capture using Playwright
• 📝 Console log monitoring and collection from web pages
• 🌐 Support for localhost and remote URLs
• 🍪 Cookie-based authentication for protected pages
• 🐳 Docker containerization for consistent environments
• ⚡ PNG, JPEG, and WebP format support with configurable quality
• 🛡️ Secure non-root container execution
• 🤖 Full MCP protocol integration with AI development tools
• 🔧 Configurable viewport sizes and capture options
• 📱 Full page and element-specific screenshot capture
• ⚠️ Browser warning and error capture (Permissions-Policy, security warnings)
• ⚡ TypeScript with Biome for fast development
• 🧪 Comprehensive testing with Node.js built-in test runner

Quick Start

📦 NPX Usage (Recommended)

The easiest way to get started - no installation required!

# Install Chromium browser (one-time setup)
npx playwright install chromium

# Test that BrowserLoop works
npx browserloop@latest --version

That's it! The latest version of BrowserLoop will be downloaded and executed automatically. Perfect for MCP users who want zero-maintenance screenshots.

MCP Configuration

Add BrowserLoop to your MCP configuration file (e.g. ~/.cursor/mcp.json):

{
  "mcpServers": {
    "browserloop": {
      "command": "npx",
      "args": ["-y", "browserloop@latest"],
      "description": "Screenshot and console log capture server for web pages using Playwright"
    }
  }
}

💡 Using @latest ensures you always get the newest features and bug fixes automatically.

🚀 One-Click Install for Cursor

Add BrowserLoop to Cursor with a single click using this deeplink:

🔗 Add BrowserLoop to Cursor

This deeplink will automatically configure BrowserLoop in your Cursor MCP settings with the optimal configuration using npx and the latest version.

Prerequisites: Make sure you have Chromium installed first:

npx playwright install chromium

Browser Installation Requirements

🚨 Critical: BrowserLoop requires Chromium to be installed via Playwright before it can take screenshots.

First-Time Setup (All Users)

Install Chromium browser:

npx playwright install chromium

Verify installation:

# Check Playwright installation
npx playwright --version

# Test BrowserLoop (if using NPX)
npx browserloop@latest --version

🐳 Docker Alternative

For containerized environments:

# Pull and run with Docker
docker run --rm --network host browserloop

# Or use docker-compose for development
git clone <repository-url>
cd browserloop
docker-compose -f docker/docker-compose.yml up

💻 Development Installation

For contributors or advanced users who want to build from source:

# Clone the repository
git clone <repository-url>
cd browserloop

# Install dependencies
npm install

# Install Playwright browsers (required for screenshots)
npx playwright install chromium
# OR use the convenient script:
npm run install-browsers

# Build the project
npm run build

MCP Configuration for Development

{
  "mcpServers": {
    "browserloop": {
      "command": "node",
      "args": [
        "/absolute/path/to/browserloop/dist/src/index.js"
      ],
      "description": "Screenshot and console log capture server for web pages using Playwright"
    }
  }
}

Replace /absolute/path/to/browserloop/ with your actual project path.

Basic Usage

Once configured, you can use natural language commands in your AI tool:

Screenshots

Take a screenshot of https://example.com
Take a screenshot of https://example.com with width 1920 and height 1080
Take a screenshot of https://example.com in JPEG format with 95% quality
Take a full page screenshot of https://example.com
Take a screenshot of http://localhost:3000 to verify the UI changes

Console Log Reading

Read console logs from https://example.com
Check for console errors on https://example.com
Monitor console warnings from http://localhost:3000
Read only error and warning logs from https://example.com
Capture console output from https://example.com for debugging

🔐 Cookie Authentication

BrowserLoop supports cookie-based authentication for capturing screenshots of login-protected pages during development:

Take a screenshot of http://localhost:3000/admin/dashboard using these cookies: [{"name":"connect.sid","value":"s:session-id.signature","domain":"localhost"}]

📖 For cookie extraction methods and development workflows, see:

📖 Cookie Authentication Guide

Common development use cases:

• Local development servers with authentication
• Staging environment testing
• API documentation tools (Swagger, GraphQL Playground)
• Custom web applications during development
• Admin panels and protected routes

Documentation

• 🔐 Cookie Authentication Guide - Complete guide for authenticated screenshots
• 📚 Complete API Reference - Detailed parameter documentation, examples, and response formats

Key API Parameters

📖 See docs/API.md for complete parameter details, usage examples, and configuration options.

Configuration

BrowserLoop can be configured using environment variables:

Basic Configuration

Authentication Configuration

Console Log Configuration

Note: Console log collection always waits exactly 3 seconds after page load to capture console messages. The timeout setting only affects how long the page has to initially load.

Log Sanitization

Console log sanitization is enabled by default (BROWSERLOOP_SANITIZE_LOGS=true) to protect sensitive information. When enabled, the following patterns are automatically masked:

---