MCP HubMCP Hub
random-robbie

mcp-web-browser

by: random-robbie

An advanced web browsing server for the Model Context Protocol (MCP) powered by Playwright, enabling headless browser interactions through a flexible, secure API.

14created 11/01/2025
Visit
Playwright
API

📌Overview

Purpose: The MCP Web Browser Server is designed to facilitate advanced web browsing interactions through a flexible and secure API, leveraging the capabilities of the Model Context Protocol (MCP) and Playwright.

Overview: This framework allows users to programmatically navigate websites, extract content, and interact with web elements in a headless browser environment. It supports diverse functionalities, enabling automated web interactions while maintaining security and performance.

Key Features:

  • Headless Web Browsing: Provides the ability to visit any website with SSL validation bypass for seamless navigation.

  • Full Page Content Extraction: Allows retrieval of entire HTML content, including any dynamically generated data through JavaScript.

  • Multi-Tab Support: Users can create, manage, and switch between multiple browser tabs efficiently.

  • Advanced Web Interaction Tools: A comprehensive suite of tools for diverse interactions like clicking elements, inputting data, capturing screenshots, filtering links, scrolling, executing JavaScript, and refreshing pages.

  • Resource Management: Automatically cleans up unused resources after a specified period of inactivity, ensuring optimized performance.

  • Enhanced Page Information: Offers detailed metadata about the currently loaded page for better context and information retrieval.

MCP Web Browser Server

An advanced web browsing server for the Model Context Protocol (MCP) powered by Playwright, enabling headless browser interactions through a flexible, secure API.

🌐 Features

  • Headless Web Browsing: Navigate to any website with SSL certificate validation bypass
  • Full Page Content Extraction: Retrieve complete HTML content, including dynamically loaded JavaScript
  • Multi-Tab Support: Create, manage, and switch between multiple browser tabs
  • Advanced Web Interaction Tools:
    • Extract text content
    • Click page elements
    • Input text into form fields
    • Capture screenshots
    • Extract page links with filtering capabilities
    • Scroll pages in any direction
    • Execute JavaScript on pages
    • Refresh pages
    • Wait for navigation to complete
  • Resource Management: Automatic cleanup of unused resources after inactivity
  • Enhanced Page Information: Get detailed metadata about the current page

🚀 Quick Start

Prerequisites

  • Python 3.10+
  • MCP SDK
  • Playwright

Installation

# Install MCP and Playwright
pip install mcp playwright

# Install browser dependencies
playwright install

Configuration for Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "web-browser": {
      "command": "python",
      "args": [
        "/path/to/your/server.py"
      ]
    }
  }
}

💡 Usage Examples

Basic Web Navigation

# Browse to a website
page_content = browse_to("https://example.com")

# Extract page text
text_content = extract_text_content()

# Extract text from a specific element
title_text = extract_text_content("h1.title")

Web Interaction

# Navigate to a page
browse_to("https://example.com/login")

# Input text into a form
input_text("#username", "your_username")
input_text("#password", "your_password")

# Click a login button
click_element("#login-button")

Screenshot Capture

# Capture full page screenshot
full_page_screenshot = get_page_screenshots(full_page=True)

# Capture specific element screenshot
element_screenshot = get_page_screenshots(selector="#main-content")

Link Extraction

# Get all links on the page
page_links = get_page_links()

# Get links matching a pattern
filtered_links = get_page_links(filter_pattern="contact")

Multi-Tab Browsing

# Create a new tab
tab_id = create_new_tab("https://example.com")

# Create another tab
another_tab_id = create_new_tab("https://example.org")

# List all open tabs
tabs = list_tabs()

# Switch between tabs
switch_tab(tab_id)

# Close a tab
close_tab(another_tab_id)

Advanced Interactions

# Scroll the page
scroll_page(direction="down", amount="page")

# Execute JavaScript on the page
result = execute_javascript("return document.title")

# Get detailed page information
page_info = get_page_info()

# Refresh the current page
refresh_page()

# Wait for navigation to complete
wait_for_navigation(timeout_ms=5000)

🛡️ Security Features

  • SSL certificate validation bypass
  • Secure browser context management
  • Custom user-agent configuration
  • Error handling and comprehensive logging
  • Configurable timeout settings
  • CSP bypass control
  • Protection against cookie stealing

🔧 Troubleshooting

Common Issues

  • SSL Certificate Errors: Automatically bypassed
  • Slow Page Load: Adjust timeout in browse_to() method
  • Element Not Found: Verify selectors carefully
  • Browser Resource Usage: Auto-cleanup after inactivity period

Logging

All significant events are logged with detailed information for easy debugging.

📋 Tool Parameters

browse_to(url: str, context: Optional[Any] = None)

  • url: Website to navigate to
  • context: Optional context object (currently unused)

extract_text_content(selector: Optional[str] = None, context: Optional[Any] = None)

  • selector: Optional CSS selector to extract specific content
  • context: Optional context object (currently unused)

click_element(selector: str, context: Optional[Any] = None)

  • selector: CSS selector of the element to click
  • context: Optional context object (currently unused)

get_page_screenshots(full_page: bool = False, selector: Optional[str] = None, context: Optional[Any] = None)

  • full_page: Capture entire page screenshot
  • selector: Optional element to screenshot
  • context: Optional context object (currently unused)

get_page_links(filter_pattern: Optional[str] = None, context: Optional[Any] = None)

  • filter_pattern: Optional text pattern to filter links
  • context: Optional context object (currently unused)

input_text(selector: str, text: str, context: Optional[Any] = None)

  • selector: CSS selector of input element
  • text: Text to input
  • context: Optional context object (currently unused)

create_new_tab(url: Optional[str] = None, context: Optional[Any] = None)

  • url: Optional URL to navigate to in the new tab
  • context: Optional context object (currently unused)

switch_tab(tab_id: str, context: Optional[Any] = None)

  • tab_id: ID of the tab to switch to
  • context: Optional context object (currently unused)

list_tabs(context: Optional[Any] = None)

  • context: Optional context object (currently unused)

close_tab(tab_id: Optional[str] = None, context: Optional[Any] = None)

  • tab_id: Optional ID of the tab to close (defaults to current tab)
  • context: Optional context object (currently unused)

refresh_page(context: Optional[Any] = None)

  • context: Optional context object (currently unused)

get_page_info(context: Optional[Any] = None)

  • context: Optional context object (currently unused)

scroll_page(direction: str = "down", amount: str = "page", context: Optional[Any] = None)

  • direction: Direction to scroll ('up', 'down', 'left', 'right')
  • amount: Amount to scroll ('page', 'half', or a number)
  • context: Optional context object (currently unused)

wait_for_navigation(timeout_ms: int = 10000, context: Optional[Any] = None)

  • timeout_ms: Maximum time to wait in milliseconds
  • context: Optional context object (currently unused)

execute_javascript(script: str, context: Optional[Any] = None)

  • script: JavaScript code to execute
  • context: Optional context object (currently unused)

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Development Setup

# Clone the repository
git clone https://github.com/random-robbie/mcp-web-browser.git

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows use `venv\Scripts\activate`

# Install dependencies
pip install -e .[dev]

📄 License

MIT License

🔗 Related Projects

💬 Support

For issues and questions, please open an issue on GitHub: https://github.com/random-robbie/mcp-web-browser/issues