Browser MCP Server

# Browser MCP Server A **Model Context Protocol (MCP)** server that provides comprehensive browser automation capabilities using [Playwright](https://playwright.dev/). 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 ```bash # 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) ```bash pip install claude-browser-mcp playwright install ``` ## 🛠 Usage ### As MCP Server Start the server with stdio transport: ```bash browser-mcp # or python -m src.server ``` ### Configuration Configure the browser through environment variables: ```bash 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: ```json { "mcpServers": { "browser-automation": { "command": "browser-mcp", "args": [] } } } ``` ## 🔧 Available Tools ### `navigate_to` Navigate to a specified URL with optional waiting. ```json { "name": "navigate_to", "arguments": { "url": "https://example.com", "wait_for": "selector", "timeout": 30 } } ``` ### `get_page_content` Extract text content from the current page. ```json { "name": "get_page_content", "arguments": { "include_links": true, "selector": ".main-content" } } ``` ### `click_element` Click on elements by CSS selector. ```json { "name": "click_element", "arguments": { "selector": "button#submit", "timeout": 10 } } ``` ### `fill_form` Fill form fields with data. ```json { "name": "fill_form", "arguments": { "fields": { "#email": "user@example.com", "#password": "secretpass" }, "submit": true } } ``` ### `take_screenshot` Capture page screenshots. ```json { "name": "take_screenshot", "arguments": { "full_page": true, "selector": ".dashboard" } } ``` ### `execute_javascript` Run JavaScript in the browser context. ```json { "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 ```bash # Build and run with Docker Compose docker-compose up browser-mcp # Or build manually ./scripts/docker-build.sh ./scripts/start-container.sh ``` ### Production Deployment ```bash # 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 ```bash # 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 ```bash # 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: ```json { "success": true, "url": "https://example.com", "title": "Page Title", "data": "...", "metadata": { "timestamp": "...", "execution_time": "..." } } ``` Error responses include: ```json { "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 ```bash # 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 MIT License - see LICENSE file for details. ## 🙏 Acknowledgments - [Playwright](https://playwright.dev/) for browser automation - [MCP](https://modelcontextprotocol.io/) for the protocol specification - [Anthropic](https://anthropic.com/) 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.