Based Browser Debug Server
No description available
Ask AI about Based Browser Debug Server
Powered by Claude Β· Grounded in docs
I know everything about Based Browser Debug Server. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
π§ 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
.webmexport- 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/.gitignoreis 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
