🧠 MCP Browser Debugger (Python)

Enterprise-grade Model Context Protocol (MCP) server enabling AI agents to perform real browser automation, debugging, visual testing, performance analysis, HAR export, Playwright trace replay, video recording, and OCR-based text extraction on real web applications.

Built with Playwright (Python) and FastMCP, this server allows AI clients to act as autonomous QA engineers operating on real Chromium browsers, not mock environments.

---

📌 Overview

The MCP Browser Debugger is a stateful MCP server that bridges AI reasoning with real UI behavior.

It enables AI tools (Cursor, VS Code, Windsurf, etc.) to:

• Control a real Chrome browser (non-headless)
• Automatically attach to running localhost servers
• Interact with UI without fragile selectors
• Collect screenshots, videos, HAR files, logs, and traces
• Perform visual regression testing
• Extract visible text via OCR

---

❗ What This Project Is / Is Not

✅ This project IS

• A long-running MCP server
• A browser automation backend for AI agents
• A QA / debugging system for real web apps
• A stateful, artifact-producing tool

❌ This project is NOT

• A Playwright test framework replacement
• A headless-only automation tool
• A stateless CLI utility
• A mock or simulated browser

---

🏗 Architecture

AI Client (Cursor / VS Code / Windsurf)
        │
        ▼
Model Context Protocol (MCP)
        │
        ▼
FastMCP Server (Python)
        │
        ▼
Playwright (Chromium – real browser)
        │
        ▼
Artifacts (Screenshots, Video, HAR, Trace, OCR)

---

🔍 Server Identity (Important)

Purpose	Name
MCP config name	Browser-Debugger
FastMCP internal name	Browser_Debugger

⚠️ These names are intentionally different. Do not rename either.

---

⚙️ Core Capabilities

Browser Automation

• Launches real Chrome (channel="chrome", non-headless)
• Auto-detects running localhost servers
• Automatically attaches to the most relevant server
• Creates session folders per project

Universal UI Interaction

• Intelligent form filling
• Button detection without selectors
• Semantic button scoring (submit/login/search)
• Keyboard fallback (Enter)

Debugging & Diagnostics

• Console log capture
• Network request logging
• DOM inspection
• HAR export

Performance Analysis

• LCP (Largest Contentful Paint)
• FCP (First Contentful Paint)
• CLS (Cumulative Layout Shift)
• Load (Navigation Timing based)

Visual Testing

• Full-page screenshots
• Element screenshots
• Baseline creation
• Visual diff with severity classification
• Region-based comparison
• Multi-page regression testing

Video Recording

• Start/stop mid-session
• .webm export
• Cursor & click overlay

Playwright Tracing

• Enabled by default
• Captures actions, DOM, network, screenshots, timeline
• Integrated trace viewer support

⚠️ Traces are saved only after browser_close() is called

OCR (Optical Character Recognition)

• Extracts visible text from page or elements
• Confidence scoring
• Works with canvas, images, popups
• Powered by Tesseract OCR

OCR tools exist without Tesseract installed but will return a guided error until the binary is installed.

---

✅ Requirements

Requirement	Version	Notes
Python	3.8+	Required
pip	Latest	Auto-upgraded
fastmcp	< 3.0	Installed automatically
playwright	≥ 1.40	Installed automatically
psutil	≥ 5.9	Installed automatically
Pillow	≥ 9.0	Installed automatically
numpy	≥ 1.21	Installed automatically
pytesseract	≥ 0.3	Installed automatically
Tesseract OCR	5.x	Required only for OCR
Node.js / npm	Latest	For trace viewer
Git	Latest	Recommended

---

📦 Installation

Windows (Recommended)

Run in Command Prompt or PowerShell

git clone https://github.com/Selvadinesh-giga/MCP-based-Browser-Debug-Server.git
cd MCP-based-Browser-Debug-Server
python install.py

What the installer does

• Validates Python version

• Creates a virtual environment

• Installs dependencies

• Installs Playwright Chromium

• Detects Tesseract OCR (optional)

• Registers MCP server for:

  • Cursor
  • VS Code
  • Windsurf

• Writes MCP config with absolute paths

---

Optional: Install Tesseract OCR (Windows)

Required only for OCR features.

https://github.com/tesseract-ocr/tesseract/releases/download/5.5.0/
tesseract-ocr-w64-setup-5.5.0.20241111.exe

Verify:

tesseract --version

---

macOS / Linux

python3 -m venv venv
source venv/bin/activate
pip install --upgrade pip
pip install -r requirements.txt
python -m playwright install chromium

Install Tesseract if OCR is needed:

brew install tesseract        # macOS
sudo apt-get install tesseract-ocr   # Linux

---

▶️ Usage (AI-Side)

Launch Browser

browser_launch()
browser_launch(url="http://localhost:3000")

UI Interaction

app_interact(["admin@test.com", "password"], button="Login")
app_interact(["laptop"])
app_interact(button="Search")

Debugging

debug_read_logs()
dom_get_source()
dom_inspect_element(selector="#submit")

Performance

performance_get_metrics()

Screenshots & Video

media_take_screenshot()
media_record_video("start")
media_record_video("stop")

OCR

media_read_text_ocr()
media_read_text_ocr(selector=".error")

Visual Regression

visual_diff(action="create_baseline", name="homepage")
visual_diff(action="compare", baseline_path="baselines/homepage.png")

Trace Viewer

trace_viewer(action="open")

Close Session (Required)

browser_close()

---

📁 Session Artifacts

.mcp_sessions/
 └── Chrome_Session_YYYY_MM_DD_HH_MM_SS/
     ├── screenshot_*.png
     ├── baselines/
     ├── regression_<name>_<timestamp>/
     ├── full_recording.webm
     ├── network.har
     ├── trace.zip
     └── session.log

• Screenshots are stored directly in the session folder
• .mcp_sessions/.gitignore is created automatically

---

🧹 Uninstall & Cleanup

python uninstall.py

Options:

• Remove MCP config only
• Remove config + virtual environment
• Full cleanup (Playwright cache, Tesseract)

---

🔧 Troubleshooting

• Restart IDE after installation
• Always call browser_close()
• Use absolute paths only
• OCR requires Tesseract binary
• Avoid running multiple sessions simultaneously

---

🎯 Use Cases

• AI-driven QA automation
• Bug reproduction & reporting
• Visual regression testing
• Performance audits
• Accessibility validation
• DevTools automation

---

🛣 Roadmap

• Multi-tab automation
• Headless CI execution
• AI-generated bug reports
• Cloud artifact sync
• Mobile browser testing

---

🙏 Acknowledgments

• FastMCP
• Playwright
• Tesseract OCR
• Model Context Protocol community

---