pybrowser

Python headless browser library with built-in MCP server for AI agent tooling. Inspired by Lightpanda — reimagined for the Python ecosystem.

What is pybrowser?

Lightpanda is a blazing-fast headless browser written in Zig with a built-in MCP server. pybrowser brings the same concept to Python — with a clean API, 25+ MCP tools, and the full Python AI ecosystem at your fingertips.

Lightpanda (Zig)         pybrowser (Python)
─────────────────        ──────────────────────────
11x faster than Chrome   Playwright-powered (full JS)
9x less memory           + Screenshots (Lightpanda can't!)
11 MCP tools             25+ MCP tools
No screenshots           + PDF export
Single tab               + Multi-tab

Quick Start

# Install
pip install pybrowser

# Install Chromium (first time)
playwright install chromium

# Run MCP server
pybrowser serve --port 9222

As a Python library

import asyncio
from pybrowser import Browser

async def main():
    async with Browser() as browser:
        page = await browser.new_page()
        await page.goto("https://example.com")

        # Get semantic DOM tree (like Lightpanda's semantic_tree tool)
        tree = await page.semantic_tree(max_depth=4)

        # Convert to Markdown
        md = await page.to_markdown()

        # Screenshot (NOT available in Lightpanda!)
        screenshot = await page.screenshot()

        # Click
        await page.click("button.submit")

        # Fill form
        await page.fill("input[name=email]", "user@example.com")

        print(md)

asyncio.run(main())

As an MCP server (for Claude/GPT)

from pybrowser.mcp import create_server

mcp = create_server()
mcp.run()  # Connects to Claude Desktop, Cursor, etc.

Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "pybrowser": {
      "command": "python",
      "args": ["-m", "pybrowser.mcp"]
    }
  }
}

Lightweight mode (no JS, no Chromium)

from pybrowser import LiteBrowser

async with LiteBrowser() as browser:
    page = await browser.fetch("https://example.com")
    md = page.to_markdown()    # Pure Python, no Chrome needed
    links = page.extract_links()

MCP Tools (25+)

Tool	Description	Lightpanda
goto	Navigate to URL	✅
back / forward	Browser history	✅
reload	Reload page	✅
markdown	Page → Markdown	✅
links	Extract all links	✅
evaluate	Execute JavaScript	✅
semantic_tree	DOM → AI-friendly tree	✅
interactive_elements	Buttons, inputs, links	✅
structured_data	JSON-LD, OpenGraph	✅
click	Click element	✅
fill	Fill form field	✅
scroll	Scroll page	✅
wait_for_selector	Wait for element	✅
screenshot	Capture screenshot	❌ Python only
pdf	Export to PDF	❌ Python only
new_tab	Open new tab	❌ Python only
close_tab	Close tab	❌ Python only
cookies	Get/set cookies	❌ Python only
network_intercept	Intercept requests	❌ Python only
accessibility_tree	ARIA accessibility tree	❌ Python only
highlight	Highlight element	❌ Python only
select	Select dropdown option	❌ Python only
hover	Hover over element	❌ Python only
drag_drop	Drag and drop	❌ Python only
upload_file	Upload file	❌ Python only

Architecture

pybrowser/
├── src/pybrowser/
│   ├── browser/      # BrowserContext, Page, Tab (← Lightpanda: browser/)
│   ├── cdp/          # CDP WebSocket server (← Lightpanda: cdp/)
│   ├── mcp/          # MCP server + 25 tools (← Lightpanda: mcp/)
│   ├── network/      # HTTP client, event handling (← Lightpanda: network/)
│   └── parser/       # HTML parser, DOM, content extraction (← Lightpanda: html5ever/)
├── docs/             # Deep documentation
├── tests/            # pytest test suite
└── examples/         # Usage examples

Documentation

• 01 Feasibility Analysis — Python vs Lightpanda deep comparison
• 02 Architecture — System design
• 03 Components — Module specs
• 04 MCP Tools — Tool reference
• 05 Roadmap — Development plan
• 06 Tech Stack — Dependencies

License

MIT