BrowserLoop
About
A Model Context Protocol (MCP) server for taking screenshots of web pages using Playwright.
Details
- License
- AGPL-3.0 license
Explore
- 📸 High-quality screenshot capture using Playwright
- 🌐 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
- ⚡ TypeScript with Biome for fast development
- 🧪 Comprehensive testing with Node.js built-in test runner
Setting up with Highlight
This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:
- Download and install Highlight from highlightai.com/download
- Navigate to the plugins tab and select "Add Custom Plugin"
-
Configure the plugin with the settings below
Plugin Name
BrowserLoopCommand (node, npx, python, etc.)Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
- Enable "Start Automatically" if you want the plugin to start when Highlight launches
From the repository
BrowserLoop can be configured using environment variables:
The easiest way to get started - no installation required!
npx playwright install chromium
Add BrowserLoop to your MCP configuration file (e.g. ~/.cursor/mcp.json):
{
"mcpServers": {
"browserloop": {
"command": "npx",
"args": ["-y", "browserloop@latest"],
"description": "Screenshot capture server for web pages using Playwright"
}
}
}
💡 Using @latest ensures you always get the newest features and bug fixes automatically.
🚨 Critical: BrowserLoop requires Chromium to be installed via Playwright before it can take screenshots.
Install Chromium browser:
npx playwright install chromium
Verify installation:
npx playwright --version
For contributors or advanced users who want to build from source:
npm install
npx playwright install chromium
{
"mcpServers": {
"browserloop": {
"command": "node",
"args": [
"/absolute/path/to/browserloop/dist/src/index.js"
],
"description": "Screenshot capture server for web pages using Playwright"
}
}
}
Replace /absolute/path/to/browserloop/ with your actual project path.
Once configured, you can use natural language commands in your AI tool:
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
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:
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
| 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 |
| Variable | Default | Description |
|----------|---------|-------------|
| BROWSERLOOP_DEFAULT_COOKIES | - | Default cookies as file path or JSON string (see Cookie Authentication Guide) |
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
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
```bash
node --version && npm --version
npx playwright --version
Claude Desktop / Cursor
Paste into your MCP client config file to install this server.
{
"mcpServers": {
"browserloop": {
"browserloop": {
"command": "npx",
"args": [
"playwright",
"install",
"chromium"
]
}
}
}
}McpServers
{
"browserloop": {
"command": "npx",
"args": [
"playwright",
"install",
"chromium"
]
}
}
A Model Context Protocol (MCP) server for taking screenshots of web pages using Playwright. This tool allows AI agents to automatically capture and analyze screenshots for UI verification or other 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
- 🌐 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
- ⚡ 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!
```bash
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
