Browser Loop

What is Browser Loop about?

Browser Loop provides an MCP‑compatible server that automates screenshot capture and console‑log extraction from web pages. Leveraging Playwright, it can render pages, handle authentication via cookies, and output images in WebP, PNG, or JPEG formats while also collecting logs of configurable severity.

How to use Browser Loop?

1. Install Playwright browsers – npx playwright install chromium.
2. Run via NPX – npx browserloop@latest --version to verify installation.
3. Add to MCP config (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"
       }
     }
   }
   

4. Issue natural‑language commands to your AI tool, such as:
   • Take a screenshot of https://example.com with width 1920 and height 1080
   • Read console logs from http://localhost:3000
5. Optionally configure environment variables (e.g., default viewport, format, cookie file) to customize behaviour.

Key features of Browser Loop

• High‑quality screenshot capture (full page or element specific) with configurable viewport, format, and quality.
• Console‑log monitoring with selectable log levels and automatic sanitization of sensitive data.
• Cookie‑based authentication for protected pages.
• Docker container support and non‑root execution for secure deployments.
• Full MCP protocol integration, enabling seamless use by AI agents.
• TypeScript codebase with Biome for fast development and built‑in test suite.
• Retry logic, debug logging, and metrics collection.

Use cases of Browser Loop

• Automated UI testing – generate visual diffs by capturing screenshots after each build.
• Debugging web applications – retrieve console output to diagnose client‑side errors.
• AI‑driven agents – enable agents to “see” a page and react based on visual or log data.
• Documentation generation – capture page snapshots for API docs or tutorials.
• Continuous monitoring – periodically snapshot critical pages and archive logs for compliance.

FAQ from the Browser Loop

Q: Do I need to install a browser manually? A: Yes, install Chromium via Playwright (npx playwright install chromium).

Q: Can I run Browser Loop inside Docker? A: Absolutely. Use the provided Docker image or docker-compose configuration.

Q: How are sensitive details handled in console logs? A: By default, logs are sanitized (API keys, JWTs, emails, etc.). Set BROWSERLOOP_SANITIZE_LOGS=false to disable.

Q: Where are debug logs written? A: When BROWSERLOOP_DEBUG=true, detailed logs are saved to /tmp/browserloop.log.

Q: What Node version is required? A: Node.js 20+ is recommended.

Q: How do I provide cookies for authenticated screenshots? A: Use the BROWSERLOOP_DEFAULT_COOKIES env variable (file path or JSON string) or include cookies directly in the request payload.

BrowserLoop

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

Parameter	Type	Description	Default
url	string	Target URL to capture (required)	-
width	number	Viewport width (200-4000)	1280
height	number	Viewport height (200-4000)	720
format	string	Image format (webp, png, jpeg)	webp
quality	number	Image quality (1-100)	80
fullPage	boolean	Capture full page	false
selector	string	CSS selector for element capture	-

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

Configuration

BrowserLoop can be configured using environment variables:

Basic Configuration

Variable	Default	Description
BROWSERLOOP_DEFAULT_WIDTH	1280	Default viewport width (200-4000)
BROWSERLOOP_DEFAULT_HEIGHT	720	Default viewport height (200-4000)
BROWSERLOOP_DEFAULT_FORMAT	webp	Default image format (webp, png, jpeg)
BROWSERLOOP_DEFAULT_QUALITY	80	Default image quality (0-100)
BROWSERLOOP_DEFAULT_TIMEOUT	30000	Default timeout in milliseconds
BROWSERLOOP_USER_AGENT	-	Custom user agent string

Authentication Configuration

Variable	Default	Description
BROWSERLOOP_DEFAULT_COOKIES	-	Default cookies as file path or JSON string (see Cookie Authentication Guide)

Console Log Configuration

Variable	Default	Description
BROWSERLOOP_CONSOLE_LOG_LEVELS	log,info,warn,error,debug	Comma-separated list of log levels to capture
BROWSERLOOP_CONSOLE_TIMEOUT	30000	Page navigation timeout in milliseconds (not log collection time)
BROWSERLOOP_SANITIZE_LOGS	true	Enable/disable sensitive data sanitization in logs
BROWSERLOOP_CONSOLE_WAIT_NETWORK_IDLE	true	Wait for network idle before finishing collection
BROWSERLOOP_MAX_LOG_SIZE	1048576	Maximum total log size in bytes (1MB)

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:

Pattern Type	Example Input	Masked Output
API Keys	sk_live_1234567890abcdef...	[API_KEY_MASKED]
Email Addresses	user@example.com	[EMAIL_MASKED]
JWT Tokens	eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...	[JWT_TOKEN_MASKED]
Auth Headers	Bearer abc123token...	[AUTH_HEADER_MASKED]
URLs with Auth	https://api.com/data?token=secret123	[URL_WITH_AUTH_MASKED]
Secret Variables	password: mySecretPass	password: [VALUE_MASKED]

To disable sanitization (for debugging):

BROWSERLOOP_SANITIZE_LOGS=false

Note: Sanitization preserves log structure while masking sensitive content, making logs safe for sharing and analysis.

Performance & Reliability

Variable	Default	Description
BROWSERLOOP_RETRY_COUNT	3	Number of retry attempts for failed operations
BROWSERLOOP_RETRY_DELAY	1000	Delay between retries in milliseconds

Logging & Debugging

Variable	Default	Description
BROWSERLOOP_DEBUG	false	Enable debug logging to /tmp/browserloop.log
BROWSERLOOP_ENABLE_METRICS	true	Enable error metrics collection
BROWSERLOOP_DISABLE_FILE_WATCHING	false	Disable automatic cookie file monitoring

Debug Logging

When BROWSERLOOP_DEBUG=true, detailed logs are written to /tmp/browserloop.log including:

• Cookie file loading and automatic refresh events
• File watching status and recreation events
• Screenshot operation details
• Configuration changes and errors

Monitor logs in real-time:

tail -f /tmp/browserloop.log

Note: Logs are written to a file (not console) to maintain compatibility with MCP's stdio protocol.

Example MCP Configuration with Default Cookies

Method 1: JSON File (Recommended)

Create a cookies file:

// ~/.config/browserloop/cookies.json
[
  {
    "name": "connect.sid",
    "value": "s:your-dev-session.signature",
    "domain": "localhost"
  }
]

Reference in MCP config:

{
  "mcpServers": {
    "browserloop": {
      "command": "node",
      "args": ["dist/src/mcp-server.js"],
      "env": {
        "BROWSERLOOP_DEFAULT_COOKIES": "/home/username/.config/browserloop/cookies.json",
        "BROWSERLOOP_DEFAULT_FORMAT": "webp",
        "BROWSERLOOP_DEFAULT_QUALITY": "85"
      }
    }
  }
}

Method 2: JSON String (Legacy)

{
  "mcpServers": {
    "browserloop": {
      "command": "node",
      "args": ["dist/src/mcp-server.js"],
      "env": {
        "BROWSERLOOP_DEFAULT_COOKIES": "[{\"name\":\"session_id\",\"value\":\"your_session_value\",\"domain\":\"example.com\"},{\"name\":\"auth_token\",\"value\":\"your_auth_token\"}]",
        "BROWSERLOOP_DEFAULT_FORMAT": "webp",
        "BROWSERLOOP_DEFAULT_QUALITY": "85"
      }
    }
  }
}

Console Log Configuration Examples

# Only capture warnings and errors
BROWSERLOOP_CONSOLE_LOG_LEVELS="warn,error"

# Debug mode with all logs, no sanitization
BROWSERLOOP_DEBUG="true"
BROWSERLOOP_SANITIZE_LOGS="false"
BROWSERLOOP_CONSOLE_LOG_LEVELS="log,info,warn,error,debug"

Troubleshooting

Common Issues

"Executable doesn't exist" Error

# Install Chromium browser (most common fix)
npx playwright install chromium

MCP Server Not Starting

1. Test manually: npx browserloop@latest --version
2. Verify requirements:
   • Node.js 20+: node --version
   • npm: npm --version
   • npx: npx --version
3. Check MCP config JSON syntax

Screenshots Show Login Pages

• Use cookie authentication (see Cookie Authentication Guide)
• Check cookie expiration and domain settings

Console Logs Are Empty

• Some production websites have no console output (this is normal)
• Test with development sites that have console activity
• Enable debug logging: BROWSERLOOP_DEBUG=true and check /tmp/browserloop.log
• Check log level filtering: BROWSERLOOP_CONSOLE_LOG_LEVELS=log,info,warn,error,debug

Console Log Collection Timing

• Collection always waits exactly 3 seconds after page load
• BROWSERLOOP_CONSOLE_TIMEOUT controls page loading timeout, not log collection time
• Fast sites will still take ~3-4 seconds total (load + 3s collection + processing)

Network/Connection Issues

• Test with external URLs first: https://example.com
• For localhost: ensure your dev server is running
• Check firewall settings

Updating BrowserLoop

• NPX: Automatically uses latest version with @latest - no manual updates needed!
• Check current version: npx browserloop@latest --version

Quick Diagnosis

# Test complete setup
node --version && npm --version
npx playwright --version

# Test BrowserLoop
npx browserloop@latest --version

Enable debug logging: Set BROWSERLOOP_DEBUG=true in your MCP config and monitor /tmp/browserloop.log

📖 See docs/API.md#error-handling for detailed troubleshooting.

License

BrowserLoop is licensed under the GNU Affero General Public License v3.0 or later (AGPL-3.0-or-later).

What this means:

• ✅ Free to use - Personal and commercial use allowed
• ✅ Free to modify - You can adapt the code to your needs
• ✅ Free to distribute - Share copies with others
• ✅ Patent protection - Contributors provide patent grants
• ⚠️ Copyleft - Derivative works must also be open source under AGPL-3.0
• ⚠️ Network clause - If you run a modified version on a server, you must provide source code to users

For Network Services

Important: If you modify BrowserLoop and run it as a network service (e.g., web app, API server, or cloud service), the AGPL requires you to:

1. Offer the complete source code to all users of your service
2. Include a prominent notice about how users can access the source
3. Use a compatible license for the entire service

License Files

• LICENSE - Full license text

Commercial Use

Organizations can use BrowserLoop under the AGPL for commercial purposes, but must comply with the copyleft requirements. If you need to keep modifications private, consider:

1. Using BrowserLoop without modifications
2. Contributing improvements back to the community
3. Contacting the maintainers about potential alternative licensing arrangements

For questions about licensing, please open an issue or contact the maintainers.