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 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

• Text Extraction: Extract all visible text or text from specific elements

• Web Interaction Tools:

  • Click page elements

  • Input text into form fields

  • Capture screenshots (full page, viewport, or specific elements)

  • Extract page links

• Resource Management: Automatic cleanup of browser resources on shutdown

Related MCP server: Cloudflare Playwright MCP

Quick Start

Prerequisites

• Python 3.10+

• Playwright (with Chromium installed)

Installation

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

# Install the package and its dependencies (mcp[cli] and playwright)
pip install -e .

# Install the Chromium browser binary
playwright install chromium

Configuration for Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "web-browser": {
      "command": "mcp-web-browser"
    }
  }
}

Alternatively, you can run the server module directly:

{
  "mcpServers": {
    "web-browser": {
      "command": "python",
      "args": ["-m", "mcp_web_browser.server"]
    }
  }
}

Usage Examples

Basic Web Navigation

# Browse to a website (returns the full page HTML)
page_content = browse_to("https://example.com")

# Extract all visible page text
text_content = extract_text_content()

# Extract text from specific elements
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 (returns PNG image content)
full_page_screenshot = get_page_screenshots(full_page=True)

# Capture viewport only
viewport_screenshot = get_page_screenshots()

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

Link Extraction

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

Security Features

• SSL certificate validation bypass (ignore_https_errors=True on the browser context)

• Configurable via environment variables: MCP_BROWSER_UA (custom User-Agent) and MCP_BROWSER_VIEWPORT (e.g. 1920x1080)

• Browser resources closed and cleaned up on server shutdown

Troubleshooting

Common Issues

• SSL Certificate Errors: Automatically bypassed

• Slow Page Load: browse_to() uses a fixed 30-second timeout and waits for networkidle

• Element Not Found: Verify CSS selectors carefully; tools raise an error if no page is loaded, so call browse_to() first

Logging

Significant events (navigation, extraction, errors, cleanup) are logged to stderr for easy debugging.

Tool Parameters

browse_to(url: str, mode: str = "text")

• url: Full URL to navigate to

• mode: "text" (default) returns the visible page text — cheaper for LLM use; "html" returns the full HTML content

• Returns the page content plus the current URL and page title

extract_text_content(selector: Optional[str] = None)

• selector: Optional CSS selector to extract text from matching elements

click_element(selector: str)

• selector: CSS selector of the element to click

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

• full_page: Capture the entire page rather than just the viewport

• selector: Optional CSS selector to screenshot a specific element

• Returns the screenshot as PNG image content

get_page_links()

• Returns a list of {"text": label, "href": absolute URL} objects

input_text(selector: str, text: str)

• selector: CSS selector of the input element

• text: Text to input

press_key(selector: str, key: str)

• selector: CSS selector of the element to focus

• key: Key to press, e.g. "Enter" to submit a form, "Escape", "Tab"

• Returns a confirmation plus the current URL and title (a key press may trigger navigation)

select_option(selector: str, values: str | list[str])

• selector: CSS selector of the <select> dropdown

• values: Value or label to select (or a list for multi-select)

• Returns a confirmation plus the current URL and title

click_element, input_text, press_key and select_option all append the current page URL and title to their result, so an agent can see where an action landed.

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

• Model Context Protocol

• Playwright

• Claude Desktop

Support

For issues and questions, please open an issue on GitHub.

Author

Robbie Wiggins — What-Security · GitHub