Claude Browser MCP

🚀 Browser MCP Server

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

🚀 Features

Core Browser Operations

• Navigate to URLs using smart waiting strategies.
• Extract page content with customizable selectors.
• Take screenshots (full page, viewport, or specific elements).
• Execute JavaScript and capture the results.
• Click elements using 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": []
    }
  }
}

💻 Usage Examples

Basic Usage

Here are some basic usage examples of the 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

🤝 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

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

📄 License

This project is under the MIT License - see the 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: Refer to the inline code documentation.
• Community: Join MCP community discussions.

⚠️ Important 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.