MCP 服务器

Browser-Debugger

Enables AI agents to automate and debug real Chromium browsers with capabilities like screenshots, video recording, performance analysis, visual regression testing, and OCR text extraction.

README

🧠 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