MCP Playwright Browser Server

A production-grade Model Context Protocol (MCP) server that gives AI assistants full browser control through Playwright — using a hybrid DOM + Accessibility Tree + Visual approach. Built for real-world agentic automation: job applications, web scraping, form filling, and complex multi-tab workflows.

v2.0 is a complete rewrite. The server grew from 680 lines and 23 tools to nearly 5,000 lines and 71 tools, with a modular architecture, token-optimized capture profiles, hard payload budgets, and a full test suite.

What's New in v2.0

The Problem v1 Had

v1 was a working proof of concept. It could browse pages and extract jobs. But when used with Gemini CLI for real tasks — filling application forms, navigating multi-tab flows, handling downloads — it hit hard limits:

Token waste: Every tool response dumped everything it found. One browser.snapshot on a complex page could push 50KB+ into Gemini's context window in a single call, rapidly exhausting the budget.
No multi-tab support: If a link opened a new tab (very common in job applications), Gemini was stuck with no way to switch to it.
No form intelligence: Filling a form required manual click-by-click instructions. There was no way to ask "what fields are still empty?" or "fill all required fields."
Brittle DOM-only navigation: Shadow DOM, iframes, and obfuscated element IDs caused failures with no fallback.
No session persistence: Every run started fresh. Logging in again and again wasted time and triggered bot detection.
No safety rails: The AI could write files anywhere on disk, run arbitrary JS, or create its own automation scripts — unguarded.
Monolithic: One 680-line file with no tests.

What v2.0 Solves

Every one of those problems has a specific solution in v2.0:

Problem	v2.0 Solution
Token waste	Capture Profile System (light/balanced/full) + 280KB hard payload ceiling
Multi-tab stuck	Page Manager with stable pageIds, `browser.list_pages`, `browser.select_page`
Dumb form filling	`browser.form_audit` + `browser.fill_form` + Google Forms specialist tools
Shadow DOM / obfuscated IDs	A11y tree via CDP `Accessibility.getFullAXTree` with stable `ax-` UIDs
Session loss	Cookie export/import, `browser.export_storage_state` / `browser.import_storage_state`
No safety	Path allowlist in `src/security/paths.js`, `MCP_ALLOW_EVALUATE` guard
Monolithic	10 focused modules in `src/browser/` + `src/security/` + 18-test suite

v1 vs v2 Comparison

Dimension	v1.0	v2.0
Total MCP tools	23	71
Server size	680 lines, 1 file	4,966 lines, 11 modules
Token efficiency	Uncontrolled dumps	Capture profiles + 280KB hard ceiling
Multi-tab support	Single tab only	Full page manager (list, select, close)
Form automation	Manual click-by-click	`form_audit` + `fill_form` + Google Forms specialist
A11y / Shadow DOM	DOM-only, brittle	CDP Accessibility tree with stable UIDs
Scroll handling	Saw first viewport only	Scroll awareness + container scrolling
Session persistence	None	Cookie/storage export-import
Popup & dialog handling	None	Dialog accept/dismiss, popup pageId capture
Download management	None	Wait-for-download, save to path
File reading (CV/PDF)	None	`files.read_text`, `files.read_pdf_text`
Security	No restrictions	Allowlist-enforced read/write paths
Observability	None	Console log capture, network request log
Test coverage	2 tests	18 tests
Profiles	3	5 (+ persistent variants)
Batch scripts	5 `.bat` launchers	7 `.bat` launchers
Error handling	Raw exceptions to AI	Normalized, structured, budgeted

What stayed the same

Indeed job extractor (production-grade, multi-selector, deduplication)
Google search extractor (consent handling, URL deobfuscation)
Stealth mode (webdriver hiding, user agent spoofing)
CDP connection to real Chrome
Visual snapshot + coordinate-based clicking

How It Works

You / Gemini CLI
      │
      │ natural language prompt
      ▼
  Gemini CLI ──── loads MCP config ────► playwrightBrowser MCP server
                                               │
                              ┌────────────────┤
                              │                │
                         71 MCP Tools     Payload Budget
                         (browser.*)     (280KB ceiling)
                         (forms.*)       (capture profiles)
                         (files.*)       (retryWith hints)
                         (jobs.*)
                         (search.*)
                              │
                    ┌─────────┤──────────┐
                    │         │          │
               Playwright  CDP API   Security
               (browser)  (A11y,    (path
                          network,  allowlist)
                          clicks)
                    │
               Chrome / Chromium

The Capture Ladder

Every profile instructs Gemini to try tools in order, cheapest first:

1. browser.snapshot     → plain text summary       (cheapest, ~6KB in light mode)
2. browser.list         → interactive elements      (structured, ~8KB)
3. browser.query_dom    → targeted selector query   (focused, ~10KB)
4. browser.take_snapshot→ A11y tree with UIDs       (rich, only when uid-clicking needed)
5. browser.visual_snapshot → screenshot + bbox map  (most expensive, last resort)

Gemini only escalates to a more expensive tool when the cheaper one doesn't have what it needs. This is the core of why v2.0 uses far fewer tokens than v1.0.

The Payload Budget

Every single tool response passes through enforcePayloadCeiling() before being sent to Gemini:

Measure response size in bytes
If under 280KB → send as-is
If over → progressively truncate: arrays shrink, strings truncate, fields drop
Always include retryWith hints telling Gemini exactly what parameters to reduce next time
Absolute floor: {truncated: true} — Gemini never gets a context-crashing response

Quick Start

# Clone
git clone https://github.com/Mhrnqaruni/mcp-playwright-browser.git
cd mcp-playwright-browser

# Install
npm install
npx playwright install chromium

# Run (interactive mode - chat with Gemini)
scripts\run-dom-headless.bat

# Run (one-shot automation)
scripts\run-dom-headless.bat -p "Go to https://example.com and extract the page title"

# Run with real Chrome (for logged-in sessions)
scripts\run-chrome-profile.bat --kill-chrome

Installation

Prerequisites

Node.js 18+
npm
Gemini CLI: npm install -g @google/gemini-cli then gemini auth login
Google Chrome (for CDP and chrome-profile modes)

Setup

1. Install dependencies

npm install
npx playwright install chromium

2. Configure the MCP server path

Edit .gemini/settings.json and set cwd to your repo location:

{
  "mcpServers": {
    "playwrightBrowser": {
      "command": "node",
      "args": ["src/mcp-browser-server.js"],
      "cwd": "C:/path/to/mcp-playwright-browser"
    }
  }
}

3. (Optional) Disable Chrome background apps

Prevents profile locking:

Chrome Settings → Advanced → System →
☐ Continue running background apps when Google Chrome is closed

4. Verify

scripts\run-dom-headless.bat -p "Use MCP server playwrightBrowser. Launch browser. Go to https://example.com. Take a snapshot. Close."

Profile Launchers

Each .bat file pre-configures everything (browser type, stealth, profile, environment variables) and starts Gemini with the right system instructions. You never need to configure Gemini manually.

Available Profiles

Script	Browser	Mode	Best For
`run-dom-headless.bat`	Chromium	Headless	⚡ Bulk scraping, fastest
`run-visual-headful.bat`	Chromium	Visible + Screenshots	Debugging, visual verification
`run-chrome-profile.bat`	Real Chrome	Your profile	Logged-in sessions, form filling
`run-cdp-profile.bat`	Real Chrome	CDP	Maximum stealth
`run-cdp-profile-screen.bat`	Real Chrome	CDP + Visual	CDP with screenshot analysis
`run-cdp-profile-persist.bat`	Real Chrome	CDP + Persistent	Long sessions, multi-step flows
`run-cdp-profile-screen-persist.bat`	Real Chrome	CDP + Visual + Persistent	Full power mode

Interactive Mode (Chat)

# Start Gemini and chat with it
scripts\run-chrome-profile.bat --kill-chrome

# Then just type:
# "Fill out the job application at [URL] using my CV"
# "Go to LinkedIn and apply to the first 5 jobs"
# "Extract all AI engineer jobs from Indeed and save them"

One-Shot Mode (Automation)

# Run a task and get a log file
scripts\run-dom-headless.bat -p "Your full task here"

# With custom output
scripts\run-dom-headless.bat -p "Extract 50 jobs from Indeed" --output logs\jobs.log

# Chrome profile one-shot
scripts\run-chrome-profile.bat --kill-chrome -p "Submit application at [URL]" --output logs\apply.log

Logs are auto-saved to logs/ with timestamps.

Profile Details

`run-dom-headless.bat` — Fastest

Chromium headless (no GUI)
Best for: bulk extraction, scraping, background tasks
Token usage: lowest (no screenshots)

`run-visual-headful.bat` — Debugging

Chromium with visible window
Screenshot-based navigation available
Best for: troubleshooting, visual verification

`run-chrome-profile.bat` — Authenticated Sessions

Real Chrome with your existing logged-in profile
Already signed into Gmail, LinkedIn, job sites
Use --kill-chrome to free profile before starting
Best for: job applications, authenticated scraping

`run-cdp-profile.bat` — Maximum Stealth

Connects to real Chrome via Chrome DevTools Protocol
Hardest for sites to detect as automation
Best for: sites that block Playwright/Chromium
Auto-closes any existing Chrome using the profile before launch

`run-cdp-profile-persist.bat` — Long Sessions

CDP mode with persistent browser (doesn't close between tasks)
Best for: multi-step workflows where browser state must survive

All 71 MCP Tools

Capture Profile Control

Tool	Description
`browser.set_capture_profile`	Set `light` / `balanced` / `full` profile. Controls token usage across all tools. Call this first.
`browser.get_capture_profile`	Show current profile settings and payload budget.

Browser Lifecycle

Tool	Description
`browser.launch`	Launch Chromium with options: headless, stealth, userDataDir, profileDirectory, channel, slowMo, args
`browser.launch_chrome_cdp`	Launch real Chrome with remote debugging + connect in one step
`browser.connect_cdp`	Connect to existing Chrome with `--remote-debugging-port`
`browser.close`	Close browser session
`browser.reload`	Reload current page

Multi-Tab Management

Tool	Description
`browser.new_page`	Open new tab, tracked by page manager
`browser.list_pages`	List all open tabs with pageId, url, title, active/closed state
`browser.select_page`	Switch active tab by pageId
`browser.close_page`	Close a specific tab by pageId
`browser.list_frames`	List all iframes on the current page

Navigation

Tool	Description
`browser.goto`	Navigate to URL with configurable waitUntil and timeout
`browser.back`	Go back in history
`browser.forward`	Go forward in history
`browser.wait`	Wait for selector or fixed ms
`browser.wait_for`	Smart wait: selector, text, or uid (A11y)

Event & Dialog Handling

Tool	Description
`browser.list_dialogs`	List pending JS dialogs (alert, confirm, prompt)
`browser.handle_dialog`	Accept or dismiss a dialog, optionally with input text
`browser.wait_for_download`	Block until a download starts, returns downloadId
`browser.save_download`	Save a captured download to a specific path
`browser.wait_for_popup`	Wait for a new tab/popup to open, returns its pageId
`browser.expect_event`	Listen for a one-time event: dialog, download, navigation, request, response

Session & Cookie Management

Tool	Description
`browser.get_cookies`	List cookies, optionally filtered by URL
`browser.set_cookies`	Inject cookies into browser session
`browser.clear_cookies`	Clear all or URL-specific cookies
`browser.export_storage_state`	Export full session state (cookies + localStorage) to JSON file
`browser.import_storage_state`	Restore session from previously exported JSON

Scroll Control

Tool	Description
`browser.get_scroll_state`	Returns scrollY, scrollHeight, atTop, atBottom, viewport info
`browser.scroll_by`	Scroll page by delta pixels (vertical + horizontal)
`browser.scroll_to`	Scroll to absolute position
`browser.get_scrollables`	Detect all scrollable containers on the page
`browser.get_container_scroll_state`	Scroll metrics for a specific container selector
`browser.scroll_container`	Scroll a specific container by selector

Page Reading & Snapshots

Tool	Description
`browser.snapshot`	Plain text page summary: title, text, links, optional headings + forms summary
`browser.take_snapshot`	A11y tree via CDP: roles, names, UIDs (`ax-{nodeId}`), depth, state
`browser.query_dom`	Flexible selector query: text, value, bbox, visibility, state, tagName
`browser.evaluate`	Execute JavaScript (requires `MCP_ALLOW_EVALUATE=true`, origin-gated)

Element Interaction

Tool	Description
`browser.list`	List visible interactive elements with elementId, tag, text, href
`browser.click`	Click by elementId, uid, selector, or text
`browser.hover`	Hover over element (triggers dropdown menus, tooltips)
`browser.type`	Simulate keypress-by-keypress typing
`browser.fill`	Direct value fill (faster, no keypress simulation)
`browser.press`	Press keyboard key (Enter, Tab, Escape, etc.)
`browser.set_input_files`	Upload file to input[type=file]
`browser.scroll_to_uid`	Scroll a UID element into view

Visual Navigation

Tool	Description
`browser.screenshot`	Save screenshot to path
`browser.visual_snapshot`	Screenshot + element map with bounding boxes and IDs
`browser.click_at`	Click at viewport-relative X/Y coordinates
`browser.click_at_page`	Click at document-absolute X/Y coordinates

Data Extraction

Tool	Description
`browser.extract_text`	Extract text from CSS selector (single or all matches)
`browser.extract_html`	Extract outerHTML from selector

Form Automation

Tool	Description
`browser.form_audit`	Scan page for all unfilled required fields: text, select, radio, checkbox, contenteditable
`browser.fill_form`	Fill a list of `{label, selector, value, kind}` fields — label-driven or selector-driven
`forms.google_audit`	Google Forms specialist: list all questions and check `aria-checked` for answers
`forms.google_set_text`	Fill a Google Forms text question by question text
`forms.google_set_dropdown`	Select option in Google Forms dropdown
`forms.google_set_checkbox`	Check/uncheck Google Forms checkbox
`forms.google_set_radio`	Select option in Google Forms radio group
`forms.google_set_grid`	Select option in Google Forms grid question

Observability

Tool	Description
`browser.list_console_messages`	Show captured `console.log/warn/error` from the page
`browser.list_network_requests`	Show all network requests (URL, method, status, timing)
`browser.get_network_request`	Get full details for a specific request by ID

File Operations

Tool	Description
`files.read_text`	Read text file (restricted to allowed paths)
`files.read_pdf_text`	Extract text from PDF — used to read CV files
`files.list_dir`	List directory contents
`files.write_text`	Write text to file (restricted to `output/` and `logs/`)

Specialized Extractors (Production Examples)

Tool	Description
`jobs.extract_indeed`	Extract Indeed job listings with multi-selector fallbacks, deduplication, access detection
`jobs.indeed_next_page`	Navigate to next Indeed page (direct URL, click, or auto mode)
`search.google`	Open Google search and extract results with consent handling
`search.extract_google`	Extract results from current Google search page

Architecture

Module Structure

src/
├── mcp-browser-server.js      # Main server: tool registration, env config, middleware
├── extractors.js              # Indeed + Google specialized extractors
├── browser/
│   ├── pages.js               # Multi-tab page manager (stable pageIds)
│   ├── snapshot.js            # A11y tree via CDP Accessibility.getFullAXTree
│   ├── capture-profiles.js    # light/balanced/full × low/high = 30 preset configs
│   ├── payload-budget.js      # Hard 280KB response ceiling with graceful truncation
│   ├── cdp.js                 # CDP session, click/hover/scroll by backendNodeId
│   ├── dom-version.js         # DOM mutation tracking, frame management
│   ├── forms.js               # Form audit + intelligent form fill
│   ├── observability.js       # Console + network request capture via CDP
│   └── wait.js                # Smart wait: selector, text, uid
└── security/
    └── paths.js               # Read/write path allowlist enforcement

Tool Registration Middleware

Every tool goes through a wrapper that runs before and after the handler:

AI calls tool
      │
      ▼
assign requestId
      │
      ▼
run handler
      │
      ▼
normalize errors (structured, no stack traces)
      │
      ▼
add envelope (ok, requestId, timestamp, url, domVersion)
      │
      ▼
enforcePayloadCeiling (truncate if > 280KB)
      │
      ▼
send to AI

This means every tool automatically benefits from error safety and payload budgeting without any extra code per tool.

UID System

The A11y snapshot (browser.take_snapshot) assigns every node a stable UID in the format ax-{nodeId}, tied to the CDP backendDOMNodeId. This UID can then be used with:

browser.click({ uid: "ax-123" }) — clicks via CDP directly on the backend node
browser.scroll_to_uid({ uid: "ax-123" }) — scrolls it into view first
browser.wait_for({ uid: "ax-123" }) — waits until it's visible

CDP-native clicks are more reliable than selector-based clicks because they bypass CSS selector resolution and work even in Shadow DOM.

Token Efficiency: Capture Profiles

This is the most important v2.0 feature for real-world use.

The Problem

AI context windows are finite. Every tool response consumes tokens. A naive implementation that dumps everything on every call quickly exhausts the budget.

The Solution: Three Profiles

Set the profile once at session start, and every subsequent tool call automatically uses appropriate limits:

browser.set_capture_profile({ profile: "light" })

Profile	Snapshot chars	List items	A11y nodes	Best For
light	6,000–9,000	120–180	220–320	Job scraping, bulk tasks
balanced	12,000–16,000	240–320	440–700	Form filling, research
full	20,000	500	1,200–2,000	Deep debugging only

Two Detail Levels Per Profile

Within each profile, tools accept detail: "low" or detail: "high":

browser.snapshot({ detail: "low" })   # minimal, fast
browser.snapshot({ detail: "high" })  # more text, links, headings, form summary

The Capture Ladder in Practice

The profile system instructions teach Gemini to escalate only when needed:

✅ "I need to find the Apply button"
→ browser.snapshot (low)           # did I find it in plain text? usually yes
→ browser.list (low)               # still looking? check interactive elements
→ browser.take_snapshot (low)      # need uid for reliable click? A11y tree
→ browser.visual_snapshot (low)    # shadow DOM / can't find it at all? visual fallback

In light mode, this entire ladder costs roughly 8x fewer tokens than v1.0's single dump approach.

Hard Payload Budget

Even with capture profiles, some pages are just huge. The payload budget is a safety net:

Default ceiling: 280KB per response
If exceeded: truncate progressively (arrays → strings → object keys)
Include retryWith field: { detail: "low", maxItems: 80, limit: 20 }
Gemini reads this and retries with smaller parameters
Absolute fallback: { truncated: true, truncationReason: "..." }

The budget is configurable: MCP_MAX_RESPONSE_BYTES=150000 for tighter contexts.

Common Use Cases

Job Application (Chrome Profile)

# Start with your real logged-in Chrome
scripts\run-chrome-profile.bat --kill-chrome

In Gemini:

Set capture profile to light.
Go to [application URL].
Run form_audit to see all required fields.
Fill them using fill_form with my details from Applied Jobs/CODEX/maincv.md.
Before submitting, take a screenshot and ask me to confirm.

Bulk Job Scraping (Headless)

scripts\run-dom-headless.bat -p "Use playwrightBrowser. Launch browser headless. Go to https://ae.indeed.com/q-ai-engineer-l-dubai-jobs.html. Extract jobs with jobs.extract_indeed limit 20, save to output/indeed/page-1. Go to next page with jobs.indeed_next_page. Extract again, save to output/indeed/page-2. Close."

Session Persistence (Login Once, Reuse)

# First time: login manually and export session
scripts\run-cdp-profile.bat

In Gemini:

Go to linkedin.com and wait for me to log in.
After I confirm logged in, run browser.export_storage_state to output/linkedin-session.json.

Next time:

Run browser.import_storage_state from output/linkedin-session.json.
Go to linkedin.com — should be logged in already.

Google Form Automation

scripts\run-dom-headless.bat

In Gemini:

Go to [Google Form URL].
Run forms.google_audit to see all questions.
Fill each question using the appropriate forms.google_set_* tool.
Run forms.google_audit again to verify all answered.
Submit.

PDF CV Reading

Gemini can read your CV directly without you pasting it:

Read my CV from Applied Jobs/CODEX/maincv.md using files.read_text.
Or read the PDF version: files.read_pdf_text from Applied Jobs/CODEX/CV.pdf.
Use that information to fill the job application form.

Debugging with Visual Mode

scripts\run-visual-headful.bat

In Gemini:

Go to [URL].
Take a visual_snapshot and save to output/debug.png.
Tell me what you see and identify any unusual elements.

Environment Variables

All variables have dual names for Gemini CLI compatibility. The launchers set both:

Variable	Alias	Description
`MCP_HEADLESS`	`GEMINI_CLI_MCP_HEADLESS`	true/false — run without GUI
`MCP_STEALTH`	`GEMINI_CLI_MCP_STEALTH`	true/false — enable anti-detection
`MCP_CHANNEL`	`GEMINI_CLI_MCP_CHANNEL`	`chrome` — use real Chrome
`MCP_EXECUTABLE_PATH`	`GEMINI_CLI_MCP_EXECUTABLE_PATH`	Absolute path to chrome.exe
`MCP_USER_DATA_DIR`	`GEMINI_CLI_MCP_USER_DATA_DIR`	Chrome profile directory
`MCP_PROFILE`	`GEMINI_CLI_MCP_PROFILE`	Profile name: `Default`, `Profile 3`
`MCP_CDP_ENDPOINT`	`GEMINI_CLI_MCP_CDP_ENDPOINT`	CDP URL: `http://127.0.0.1:9222`
`MCP_CDP_PORT`	`GEMINI_CLI_MCP_CDP_PORT`	CDP port number (default 9222)
`MCP_CDP_AUTO_CLOSE`	`GEMINI_CLI_MCP_CDP_AUTO_CLOSE`	Close Chrome on server exit
`MCP_FORCE_CDP`	`GEMINI_CLI_MCP_FORCE_CDP`	Disable `browser.launch` (CDP-only mode)
`MCP_REQUIRE_PROFILE`	`GEMINI_CLI_MCP_REQUIRE_PROFILE`	Require userDataDir (prevent bare Chromium)
`MCP_ALLOW_EVALUATE`	`GEMINI_CLI_MCP_ALLOW_EVALUATE`	Enable `browser.evaluate` tool
`MCP_EVALUATE_ALLOW_ORIGINS`	`GEMINI_CLI_MCP_EVALUATE_ALLOW_ORIGINS`	Comma-separated allowed origins for evaluate
`MCP_CAPTURE_PROFILE`	`GEMINI_CLI_MCP_CAPTURE_PROFILE`	Default profile: `light`, `balanced`, `full`
`MCP_MAX_RESPONSE_BYTES`	`GEMINI_CLI_MCP_MAX_RESPONSE_BYTES`	Override 280KB payload ceiling
`MCP_SLOWMO_MS`	`GEMINI_CLI_MCP_SLOWMO_MS`	Slow down actions by N ms (debugging)

Why dual names? Gemini CLI sanitizes environment variables and may strip MCP_* prefixed keys. The GEMINI_CLI_MCP_* variants bypass this filtering. The server reads both and uses whichever is set.

Project Structure

mcp-playwright-browser/
│
├── src/
│   ├── mcp-browser-server.js        # Main server (71 tools, middleware, env config)
│   ├── extractors.js                # Indeed + Google production extractors
│   ├── browser/
│   │   ├── pages.js                 # Multi-tab page manager
│   │   ├── snapshot.js              # A11y tree (CDP Accessibility API)
│   │   ├── capture-profiles.js      # Token budget profiles (light/balanced/full)
│   │   ├── payload-budget.js        # Hard response size ceiling
│   │   ├── cdp.js                   # CDP primitives (click, hover, scroll by nodeId)
│   │   ├── dom-version.js           # DOM mutation tracking + frame management
│   │   ├── forms.js                 # Form audit + intelligent fill
│   │   ├── observability.js         # Console + network capture
│   │   └── wait.js                  # Smart wait (selector, text, uid)
│   ├── security/
│   │   └── paths.js                 # File read/write path allowlist
│   └── tests/
│       ├── page-manager-test.js
│       ├── security-paths-test.js
│       ├── snapshot-uid-test.js
│       ├── uid-click-fill-test.js
│       ├── elementid-no-stale-test.js
│       ├── wait-for-test.js
│       ├── form-audit-fill-test.js
│       ├── console-network-test.js
│       ├── visual-coords-test.js
│       ├── frame-domversion-test.js
│       ├── cdp-hover-test.js
│       ├── browser-events-test.js
│       ├── storage-state-test.js
│       ├── capture-profiles-test.js
│       ├── payload-budget-test.js
│       ├── google-form-test.js
│       ├── google-test.js
│       └── indeed-test.js
│
├── scripts/
│   ├── run-dom-headless.bat          # Fastest: headless Chromium
│   ├── run-visual-headful.bat        # Visual: Chromium + screenshots
│   ├── run-chrome-profile.bat        # Auth: real Chrome with your profile
│   ├── run-cdp-profile.bat           # Stealth: CDP mode
│   ├── run-cdp-profile-screen.bat    # Stealth + visual
│   ├── run-cdp-profile-persist.bat   # Stealth + persistent session
│   ├── run-cdp-profile-screen-persist.bat  # Full power
│   ├── autoconnect.js                # CDP auto-connect helper
│   └── .gemini/settings.json         # Fallback MCP config
│
├── profiles/
│   ├── dom/
│   │   ├── system.md                 # Gemini system instructions (DOM mode)
│   │   └── oneshot.md                # One-shot variant (closes browser at end)
│   ├── visual/
│   │   ├── system.md
│   │   └── oneshot.md
│   ├── cdp/
│   │   ├── system.md
│   │   ├── oneshot.md
│   │   └── persistent.md
│   └── cdp-visual/
│       ├── system.md
│       ├── oneshot.md
│       └── persistent.md
│
├── .gemini/settings.json             # Main MCP config (set your cwd here)
├── GEMINI.md                         # Project-level Gemini instructions
├── LICENSE                           # ISC License
└── README.md

Running Tests

# All tests that don't need network
npm run test:local

# Live network tests (Indeed + Google)
npm run test:remote

# Everything
npm run test:all

Troubleshooting

"Chrome is already running" / Profile locked

# Use --kill-chrome
scripts\run-chrome-profile.bat --kill-chrome

# Or manually
taskkill /F /IM chrome.exe

Chrome 136+ blocks automation on the default User Data directory. Always use a dedicated profile or the ChromeForMCP data dir.

"Gmail says browser is not safe"

You're connected via Chromium, not your real Chrome. Ensure:

Chrome is fully closed before starting (--kill-chrome)
The launch response shows "persistent": true and your profile path
If not, restart Gemini and verify .bat outputs Using Chrome executable: ...

MCP tools not found in Gemini

Run any .bat from any directory — they auto-fix cwd
Verify .gemini/settings.json has the correct cwd
The scripts/.gemini/settings.json is a fallback if Gemini starts in scripts/

Responses truncated / `retryWith` hint

This is the payload budget working correctly. Gemini will read the retryWith hint and retry with lower parameters. If it keeps happening, switch to light profile:

browser.set_capture_profile({ profile: "light" })

Slow performance

Use run-dom-headless.bat for bulk operations (no GUI = 3-4x faster)
Avoid browser.extract_html — it returns full HTML and wastes tokens
Use detail: "low" on all tools unless you specifically need more

Browser opens but ignores my profile

Check .bat output for:

Using Chrome executable: C:\Program Files\Google\Chrome\Application\chrome.exe
Using Chrome profile: Profile 3

If you see a different profile or "not found", edit the .bat and set MCP_PROFILE explicitly.

Security & Privacy

Path Restrictions

browser.evaluate (arbitrary JS execution) is disabled by default. Enable it only explicitly: MCP_ALLOW_EVALUATE=true

files.read_text and files.write_text are restricted to:

Read: Applied Jobs/, Auto/output/, Auto/logs/
Write: Auto/output/, Auto/logs/

Any attempt to read or write outside these paths throws immediately. Symlinks are resolved before checking (prevents traversal attacks).

What Is Stored

Data	Location	Git-ignored
Execution logs	`logs/`	✅ Yes
Extracted jobs/data	`output/`	✅ Yes
Session state exports	`output/`	✅ Yes
Gemini CLI state	`scripts/.gemini/state.json`	✅ Yes
`.gemini/` config	root `.gemini/`	✅ Yes

What Is Never Stored

❌ Passwords or credentials
❌ Credit card or payment information
❌ Browser history
❌ Personal documents outside the allowed paths

Ethical Use

This tool is provided for:

Learning browser automation and MCP development
Testing your own web applications
Automating tasks on sites you have permission to access
Legitimate job searching and application workflows

You are responsible for:

Respecting robots.txt and website Terms of Service
Complying with data protection regulations (GDPR, CCPA, etc.)
Rate-limiting your requests to avoid service disruption
Not using this to bypass paywalls or access controls without authorization

The authors assume no liability for misuse. Use responsibly.

How This Differs from Microsoft's Official `playwright-mcp`

Microsoft's playwright-mcp focuses on accessibility-tree based automation for test development in structured environments.

Feature	Microsoft `playwright-mcp`	This project
Navigation	Accessibility tree	Hybrid: DOM + A11y + Visual
Philosophy	"Blind" automation (fast, structured)	Human-like automation (robust, adaptive)
Primary use case	QA testing, defined workflows	Open-web agents, scraping, complex UIs
Token efficiency	Not optimized	Capture profiles + hard payload budget
Session persistence	Basic	Cookie/storage export-import
Form intelligence	Manual	`form_audit` + `fill_form` + Google Forms specialist
Multi-tab	Basic	Full page manager with stable pageIds
Setup	Generic	Batteries included (stealth, profiles, launchers)

Use Microsoft's for: CI/CD test automation, structured accessibility-driven workflows Use this for: Autonomous agents operating on the open web, job application automation, anti-detection scraping

Changelog

v2.0.0 (Current)

Complete architectural rewrite: monolithic → 11 modular files
71 MCP tools (was 23)
Capture profile system (light/balanced/full) for token efficiency
Hard 280KB payload budget with graceful truncation and retryWith hints
Multi-tab page manager (list, select, close pages)
A11y tree snapshots via CDP with stable ax- UIDs
CDP-native click/hover/scroll by backendDOMNodeId (handles Shadow DOM)
Form audit + intelligent fill + Google Forms specialist (6 tools)
Session export/import (cookie + localStorage persistence)
Popup, dialog, download event handling
Scroll awareness: get state, scroll by delta, scroll containers
Network + console observability via CDP
File reading: text files + PDF extraction
Security: path allowlist enforcement, evaluate guard
18-test suite (was 2)
7 profile launchers (was 5): added persist variants for CDP
GEMINI_CLI_MCP_* dual env var support for Gemini sanitization

v1.1.0

Profile launcher system (.bat files)
Chrome profile integration
--kill-chrome flag
One-shot mode with automatic logging
GEMINI_CLI_MCP_* environment variable aliases
browser.visual_snapshot and browser.click_at

v1.0.0

Initial release
Basic MCP server with Playwright
Indeed + Google extractors
DOM and visual navigation

Contributing

Fork the repository
Create a feature branch (git checkout -b feature/your-feature)
Run npm run test:local to verify nothing breaks
Commit (git commit -m 'Add your feature')
Push and open a Pull Request

License

ISC License — see LICENSE file.

Acknowledgments

Playwright — browser automation backbone
Model Context Protocol — AI tool interface
Microsoft playwright-mcp — inspiration for the A11y approach

Support

Issues: GitHub Issues
Discussions: GitHub Discussions

Name		Name	Last commit message	Last commit date
Latest commit History 12 Commits
profiles		profiles
scripts		scripts
src		src
.gitignore		.gitignore
GEMINI.md		GEMINI.md
LICENSE		LICENSE
Mehran_Gharooni_Khoshkebar_Europass_CV.md		Mehran_Gharooni_Khoshkebar_Europass_CV.md
README.md		README.md
install.bat		install.bat
package-lock.json		package-lock.json
package.json		package.json
report.md		report.md

Folders and files

Latest commit

History

Repository files navigation

MCP Playwright Browser Server

Table of Contents

What's New in v2.0

The Problem v1 Had

What v2.0 Solves

v1 vs v2 Comparison

What stayed the same

How It Works

The Capture Ladder

The Payload Budget

Quick Start

Installation

Prerequisites

Setup

Profile Launchers

Available Profiles

Interactive Mode (Chat)

One-Shot Mode (Automation)

Profile Details

run-dom-headless.bat — Fastest

run-visual-headful.bat — Debugging

run-chrome-profile.bat — Authenticated Sessions

run-cdp-profile.bat — Maximum Stealth

run-cdp-profile-persist.bat — Long Sessions

All 71 MCP Tools

Capture Profile Control

Browser Lifecycle

Multi-Tab Management

Navigation

Event & Dialog Handling

Session & Cookie Management

Scroll Control

Page Reading & Snapshots

Element Interaction

Visual Navigation

Data Extraction

Form Automation

Observability

File Operations

Specialized Extractors (Production Examples)

Architecture

Module Structure

Tool Registration Middleware

UID System

Token Efficiency: Capture Profiles

The Problem

The Solution: Three Profiles

Two Detail Levels Per Profile

The Capture Ladder in Practice

Hard Payload Budget

Common Use Cases

Job Application (Chrome Profile)

Bulk Job Scraping (Headless)

Session Persistence (Login Once, Reuse)

Google Form Automation

PDF CV Reading

Debugging with Visual Mode

Environment Variables

Project Structure

Running Tests

Troubleshooting

"Chrome is already running" / Profile locked

"Gmail says browser is not safe"

MCP tools not found in Gemini

Responses truncated / retryWith hint

Slow performance

Browser opens but ignores my profile

Security & Privacy

Path Restrictions

What Is Stored

What Is Never Stored

Ethical Use

How This Differs from Microsoft's Official playwright-mcp

Changelog

v2.0.0 (Current)

v1.1.0

`run-dom-headless.bat` — Fastest

`run-visual-headful.bat` — Debugging

`run-chrome-profile.bat` — Authenticated Sessions

`run-cdp-profile.bat` — Maximum Stealth

`run-cdp-profile-persist.bat` — Long Sessions

Responses truncated / `retryWith` hint

How This Differs from Microsoft's Official `playwright-mcp`

Packages