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.

Table of Contents

• What's New in v2.0

• v1 vs v2 Comparison

• How It Works

• Quick Start

• Installation

• Profile Launchers

• All 71 MCP Tools

• Architecture

• Token Efficiency: Capture Profiles

• Common Use Cases

• Environment Variables

• Project Structure

• Troubleshooting

• Security & Privacy

• Ethical Use

• License

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:

v1 vs v2 Comparison

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

The Capture Ladder

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

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:

1. Measure response size in bytes

2. If under 280KB → send as-is

3. If over → progressively truncate: arrays shrink, strings truncate, fields drop

4. Always include retryWith hints telling Gemini exactly what parameters to reduce next time

5. Absolute floor: {truncated: true} — Gemini never gets a context-crashing response

Quick Start

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

2. Configure the MCP server path

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

3. (Optional) Disable Chrome background apps

Prevents profile locking:

4. Verify

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

Interactive Mode (Chat)

One-Shot Mode (Automation)

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

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

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

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:

Two Detail Levels Per Profile

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

The Capture Ladder in Practice

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

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)

In Gemini:

Bulk Job Scraping (Headless)

Session Persistence (Login Once, Reuse)

In Gemini:

Next time:

Google Form Automation

In Gemini:

PDF CV Reading

Gemini can read your CV directly without you pasting it:

Debugging with Visual Mode

In Gemini:

Environment Variables

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

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

Running Tests

Troubleshooting

"Chrome is already running" / Profile locked

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:

1. Chrome is fully closed before starting (--kill-chrome)

2. The launch response shows "persistent": true and your profile path

3. 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:

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:

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

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.

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

1. Fork the repository

2. Create a feature branch (git checkout -b feature/your-feature)

3. Run npm run test:local to verify nothing breaks

4. Commit (git commit -m 'Add your feature')

5. 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