Tthanh2k6/turbo-browser-mcp: High-speed Playwright MCP server with multi-tab batching, compact delta DOM snapshots, React/Shadow DOM/iframe form filling, disk file uploads, and submit guards · GitHub

• act_fast actions: click, dblclick, hover, focus, clear, fill, type (slowly, delayMs, submit), select, check, uncheck, drag, drop (file, files, or custom MIME dropData), press (key + modifiers: Alt, Control, ControlOrMeta, Meta, Shift), scroll (dx, dy), wait (ms, state, loadState, text, textGone, url), and upload.
• Targeting options: compact [eN] ref, CSS selector, visible text, label, or viewport (x, y) coordinates, with button (left, right, middle) and frameIdx.
• batch_actions: runs an ordered list of DOM actions and nested smart_fill_form steps in one MCP call, stopping safely if blocked by the Submit guard or optionally continuing on step errors (continueOnError).

• extract_clean_text: extracts readable plain text or compact Markdown (format: "text" | "markdown") from main/article containers and iframes, stripped of script and style noise.
• evaluate_js: runs JS expressions or (el, arg) element functions in any frame (frameIdx) with JSON-serialized results and optional savePath export.
• capture_page: full-page or element-scoped screenshots (png or jpeg with quality, css or device scale, optional returnImage) and PDF generation saved to a confined savePath.

• network_session presets: turbo, no-images, no-media, and clean (unblock all), alongside custom blockResources and blockUrls patterns.
• Session & storage management: read/write/clear browser cookies, localStorage/sessionStorage, and export or reload full Playwright storageState JSON files (saveStorageStatePath, loadStorageStatePath).
• page_diagnostics: defaults to errors-only (level: "errors", statusFilter: "errors") to surface failures cleanly without flooding context, while supporting all, includeStatic, urlFilter, deep request/response inspection (reqId + part), completed downloads, and dialog auto-handling (dialogPolicy: accept/dismiss).

Run the benchmark suite yourself with Chromium and Playwright installed:

Environment & methodology: Headless Chromium via playwright-core, counting exact OpenAI o200k_base tokens via Python tiktoken (approx-bpe fallback if tiktoken is unavailable). Cumulative workflow tokens model standard chat-history replay across $N$ sequential turns: $sum_{i=1}^{N} (N – i + 1) cdot T_i$, plus a one-shot baseline where the first turn captures context before acting.

Measured against installed MCP JSON schemas on disk (compact parameter schemas without annotations):

When to keep Chrome DevTools MCP alongside turbo-browser-mcp: chrome-devtools-mcp provides Lighthouse audits, performance trace analysis, CSS computed style panels, and V8 heap snapshots. turbo-browser-mcp focuses on fast multi-step UI automation, forms, and scraping with minimal token overhead.

1. Human-in-the-loop Submit Guard (allowSubmit=false by default):
   • smart_fill_form (stopBeforeSubmit: true), act_fast, and batch_actions inspect matching elements, W3C AccName labels (isSafeSubmitter), implicit HTML form Enter submissions, key chords (Shift+Enter, Enter+Shift), HTMLFormElement.prototype.submit/requestSubmit, and same-origin iframe contentWindow/contentDocument proxies.
   • Final actions resembling Submit, Publish, Send, Post, Apply, Confirm, or payment triggers are blocked unless allowSubmit: true is explicitly passed or --allow-submit is enabled at startup.
   • Trade-off: pre-existing closed Shadow roots on already-open CDP tabs (attached before the init script ran) or strict cross-origin sandboxed frames fall back to Playwright frame handles, coordinate actions, and keyboard input.
2. Workspace Path Confinement (TURBO_BROWSER_SAVE_ROOT):
   • File outputs (savePath, saveStorageStatePath) and state inputs (loadStorageStatePath) are strictly confined to the current working directory or TURBO_BROWSER_SAVE_ROOT.
   • Lexical checks, lstatSync/readlinkSync symlink verification, and realpathSync validation block .. traversal, UNC network paths, dangling symlinks, cyclic symlinks, and Windows junctions before reading or writing.

{
  "name": "smart_fill_form",
  "arguments": {
    "fields": [
      { "selector": "#full_name", "value": "Alex Nguyen" },
      { "selector": "#email", "value": "[email protected]" },
      { "selector": "#country", "option": "United States" },
      { "selector": "#skills", "values": ["TypeScript", "Playwright"] },
      { "selector": "#agree_terms", "check": true },
      { "selector": "#resume_pdf", "file": "./assets/resume.pdf" }
    ],
    "stopBeforeSubmit": true,
    "returnSnapshot": true
  }
}

{
  "name": "inspect_compact",
  "arguments": {
    "mode": "interactive",
    "onlyChanged": true,
    "maxChars": 3000
  }
}

{
  "name": "tabs_batch",
  "arguments": {
    "operations": [
      { "action": "open", "url": "https://example.com/app", "isolatedContext": "acct-a" },
      { "action": "open_many", "urls": ["https://example.com/docs", "https://example.com/pricing"], "concurrency": 4 }
    ]
  }
}

git clone https://github.com/Tthanh2k6/turbo-browser-mcp.git
cd turbo-browser-mcp
npm install
npm run doctor

If you need Playwright’s bundled Chromium (or have no system Chrome/Edge/Brave installed):

npx playwright-core install chromium

Using local clone:

{
  "mcpServers": {
    "turbo-browser": {
      "command": "node",
      "args": ["/absolute/path/to/turbo-browser-mcp/src/index.mjs"],
      "env": {
        "TURBO_BROWSER_SAVE_ROOT": "/absolute/path/to/allowed/workspace"
      }
    }
  }
}

Using npx / binary entrypoint:

{
  "mcpServers": {
    "turbo-browser": {
      "command": "npx",
      "args": ["-y", "turbo-browser-mcp"]
    }
  }
}

In Chrome 136+/144+, enabling chrome://inspect/#remote-debugging on the default User Data directory exposes a WebSocket in DevToolsActivePort that displays an “Allow remote debugging?” prompt whenever a new WebSocket client connects. turbo-browser-mcp provides two built-in solutions so overnight AFK multi-agent runs never hang on a prompt:

1. Automatic CDP Keep-Alive Bridge Daemon (npm run bridge / --bridge, enabled automatically on DevToolsActivePort):
   • Spawns a detached background multiplexer (src/cdp-bridge.mjs on http://127.0.0.1:9224) that holds one persistent upstream WebSocket to Chrome open indefinitely and intercepts Browser.close so downstream scripts never terminate your browser.
   • You click Allow once when starting your session; afterwards, any number of MCP servers, CLI scripts, or subagents can connect and disconnect all night with 0 additional prompts.
2. Zero-Prompt Dedicated Profile Launcher (npm run launch-chrome / --launch-chrome):
   • Launches Chrome with --remote-debugging-port=9222 and a dedicated --user-data-dir (~/.turbo-browser-mcp/chrome-profile), where Chrome exposes standard HTTP/WS CDP with 0 confirmation dialogs even on the very first connection.

npm test            # 407 passing tests across 86 suites (26 test files under test/*.test.mjs)
npm run doctor      # Environment check for Node, Playwright, Chromium, and CDP
npm run bridge      # Start/verify persistent CDP Keep-Alive Bridge daemon
npm run benchmark   # Local Chromium speed & exact o200k_base token benchmark

Tested automatically on GitHub Actions (ubuntu-latest) across Node 20 and Node 22.

MIT