Browser MCP Server

A Model Context Protocol (MCP) server that provides comprehensive browser automation capabilities using Playwright. This server enables AI assistants to interact with web pages through standardized MCP tools for navigation, content extraction, form filling, and screenshot capture.

🚀 Features

Core Browser Operations

Navigate to URLs with smart waiting strategies
Extract page content with customizable selectors
Take screenshots (full page, viewport, or specific elements)
Execute JavaScript with result capture
Click elements by CSS selectors
Fill forms automatically with validation

Advanced Capabilities

Multi-browser support (Chromium, Firefox, WebKit)
Request interception and monitoring
Viewport customization and responsive testing
Link extraction and URL processing
Error handling with detailed responses
Resource management and cleanup

📦 Installation

Prerequisites

Python 3.8 or higher
Node.js (for Playwright browser installation)

Install from Source

# Clone the repository
git clone <repository-url>
cd claude-browser-mcp

# Install dependencies
pip install -e .

# Install Playwright browsers
playwright install

Install from PyPI (when available)

pip install claude-browser-mcp
playwright install

🛠 Usage

As MCP Server

Start the server with stdio transport:

browser-mcp
# or
python -m src.server

Configuration

Configure the browser through environment variables:

export BROWSER_HEADLESS=true          # Run in headless mode
export BROWSER_TYPE=chromium          # Browser type (chromium/firefox/webkit)
export BROWSER_TIMEOUT=30000          # Default timeout in milliseconds

MCP Client Integration

Add to your MCP client configuration:

{
  "mcpServers": {
    "browser-automation": {
      "command": "browser-mcp",
      "args": []
    }
  }
}

🔧 Available Tools

`navigate_to`

Navigate to a specified URL with optional waiting.

{
  "name": "navigate_to",
  "arguments": {
    "url": "https://example.com",
    "wait_for": "selector", 
    "timeout": 30
  }
}

`get_page_content`

Extract text content from the current page.

{
  "name": "get_page_content", 
  "arguments": {
    "include_links": true,
    "selector": ".main-content"
  }
}

`click_element`

Click on elements by CSS selector.

{
  "name": "click_element",
  "arguments": {
    "selector": "button#submit",
    "timeout": 10
  }
}

`fill_form`

Fill form fields with data.

{
  "name": "fill_form",
  "arguments": {
    "fields": {
      "#email": "user@example.com",
      "#password": "secretpass"
    },
    "submit": true
  }
}

`take_screenshot`

Capture page screenshots.

{
  "name": "take_screenshot",
  "arguments": {
    "full_page": true,
    "selector": ".dashboard"
  }
}

`execute_javascript`

Run JavaScript in the browser context.

{
  "name": "execute_javascript", 
  "arguments": {
    "code": "document.title",
    "return_value": true
  }
}

📁 Project Structure

claude-browser-mcp/
├── src/
│   ├── __init__.py          # Package initialization
│   ├── server.py            # MCP server implementation
│   ├── browser.py           # Browser management
│   ├── actions.py           # High-level browser actions
│   └── utils.py             # Utility functions
├── requirements.txt         # Python dependencies
├── setup.py                 # Package configuration
└── README.md               # This file

🏗 Architecture

Server (`server.py`)

MCP server implementation with tool registration
Request routing and response formatting
Error handling and logging
Async tool execution

Browser Manager (`browser.py`)

Playwright browser lifecycle management
Context creation and configuration
Resource cleanup and recovery
Multi-browser support

Actions (`actions.py`)

High-level browser automation methods
Content extraction and processing
Form interaction and validation
Screenshot and JavaScript execution

Utils (`utils.py`)

HTML sanitization and cleaning
URL validation and normalization
Image processing and encoding
Data formatting utilities

🔒 Security Considerations

HTML sanitization removes dangerous scripts and attributes
URL validation prevents malicious redirects
Input validation for all user-provided data
Resource limits prevent excessive memory usage
Timeout controls prevent hanging operations

🐳 Docker Deployment

Quick Start with Docker

# Build and run with Docker Compose
docker-compose up browser-mcp

# Or build manually
./scripts/docker-build.sh
./scripts/start-container.sh

Production Deployment

# Build production image
docker build -t browser-mcp:latest .

# Run with optimal settings
docker run -d \
  --name browser-mcp \
  --init --ipc=host --shm-size=1gb \
  --memory=2g --cpus=1.0 \
  -v $(pwd)/screenshots:/app/screenshots \
  -v $(pwd)/downloads:/app/downloads \
  browser-mcp:latest

Development with Docker

# Development container with debugging
docker-compose --profile dev up browser-mcp-dev

# Access container
docker exec -it claude-browser-mcp-dev /bin/bash

Container Management

# Health check
./scripts/health-check.sh

# View logs
docker logs -f claude-browser-mcp

# Monitor resources
docker stats claude-browser-mcp

🚨 Error Handling

The server provides detailed error responses with:

Error categorization (timeout, validation, execution)
Context information (URL, selector, arguments)
Recovery suggestions where applicable
Logging for debugging and monitoring

📊 Response Format

All tools return standardized JSON responses:

{
  "success": true,
  "url": "https://example.com",
  "title": "Page Title",
  "data": "...",
  "metadata": {
    "timestamp": "...",
    "execution_time": "..."
  }
}

Error responses include:

{
  "success": false,
  "error": "Detailed error message",
  "tool": "tool_name",
  "arguments": {...},
  "timestamp": "..."
}

🛡 Environment Variables

Variable	Default	Description
`BROWSER_HEADLESS`	`true`	Run browser in headless mode
`BROWSER_TYPE`	`chromium`	Browser engine to use
`BROWSER_TIMEOUT`	`30000`	Default timeout (ms)

🤝 Development

Setting up Development Environment

# Install in development mode
pip install -e .[dev]

# Run tests
pytest tests/

# Format code
black src/

# Type checking
mypy src/

Adding New Tools

Define tool schema in server.py
Implement action method in actions.py
Add utility functions in utils.py
Update documentation and tests

📄 License

MIT License - see LICENSE file for details.

🙏 Acknowledgments

Playwright for browser automation
MCP for the protocol specification
Anthropic for Claude and MCP development

📞 Support

Issues: Report bugs and request features on GitHub
Documentation: See inline code documentation
Community: Join MCP community discussions

Note: This is a foundational implementation. Additional features like request interception, advanced form handling, and performance optimizations can be added based on specific use cases.

This server cannot be installed

security - not tested

license - not found

quality - not tested

How are these scores calculated?

hybrid server

The server is able to function both locally and remotely, depending on the configuration or use case.

Enables AI assistants to automate web browsers through Playwright, providing capabilities for navigation, content extraction, form filling, screenshot capture, and JavaScript execution. Supports multiple browser engines with comprehensive error handling and security features.

Related MCP Servers

Playwright MCP Server
lebrodus
A
security
F
license
A
quality
A server that enables browser automation using Playwright, allowing interaction with web pages, capturing screenshots, and executing JavaScript in a browser environment through LLMs.
Last updated -
12
9,751
1
Playwright Server MCP
blackwhite084
A
security
A
license
A
quality
The server provides tools for web automation using Playwright, allowing navigation, interaction, and JavaScript execution on web pages, and supports note storage with summarization capabilities.
Last updated -
8
148
Apache 2.0
Playwright Server MCP
ziux
A
security
A
license
A
quality
A browser automation server providing Playwright capabilities for controlling web browsers, capturing screenshots, extracting content, and performing complex interactions through an MCP interface.
Last updated -
6
Apache 2.0
Cloudflare Playwright MCPofficial
cloudflare
A
security
A
license
A
quality
A server that leverages Playwright for automated browser testing and integrates with Cloudflare Workers, enabling AI assistants to control web browsers for navigation, interaction, and screenshots.
Last updated -
24
514,152
112
Apache 2.0

View all related MCP servers