Skip to content
Back to search

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

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 15 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/Tthanh2k6/turbo-browser-mcp with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/Tthanh2k6/turbo-browser-mcp'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/tthanh2k6--turbo-browser-mcp/badge.svg)](/listings/tthanh2k6--turbo-browser-mcp)

HTML

<a href="/listings/tthanh2k6--turbo-browser-mcp"><img src="/api/listings/tthanh2k6--turbo-browser-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Install & Check Environment

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

MCP Client Config (Claude Code, Cursor, Antigravity, Codex)

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"]
    }
  }
}

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 341 lines
  1. # turbo-browser-mcp
  2. [![CI](https://github.com/Tthanh2k6/turbo-browser-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/Tthanh2k6/turbo-browser-mcp/actions/workflows/ci.yml)
  3. ![Version](https://img.shields.io/badge/version-0.4.0-blue)
  4. ![Tests](https://img.shields.io/badge/tests-407%20passing%20(86%20suites)-brightgreen)
  5. ![Node](https://img.shields.io/badge/node-%3E%3D20.0.0-brightgreen)
  6. ![License](https://img.shields.io/badge/license-MIT-lightgrey)
  7. `turbo-browser-mcp` is a Playwright-based Model Context Protocol (MCP) server built to cut LLM token waste and multi-turn latency in browser automation. It consolidates 25-33 fine-grained browser primitives into **10 batched tools** featuring delta DOM snapshots, single-turn React/Shadow DOM/iframe form prefill, direct disk file uploads (no Base64 in context), parallel tab sessions, network blocking presets, and a default human-in-the-loop Submit guard.
  8. ---
  9. ## At-a-Glance Performance & Token Scorecard
  10. All figures below come from [`benchmarks/benchmark.mjs`](benchmarks/benchmark.mjs) (`npm run benchmark`) running headless Chromium locally with exact OpenAI `o200k_base` tokenization (`tiktoken 0.14.0`):
  11. | Capability | Typical Baseline | `turbo-browser-mcp` | Speed / Turn Gain | Token Savings (`o200k_base`) |
  12. | :--- | :--- | :--- | :--- | :--- |
  13. | **Dense UI Snapshot** (140-btn SaaS console) | `18,654` tok HTML / `3,568` tok full ARIA | **`1,135` tok** compact (`28 ms`) | `1` call | **`93.9%` vs HTML** (`68.2%` vs ARIA) |
  14. | **Post-Click Delta Snapshot** (`onlyChanged: true`) | `3,582` tok full ARIA rescan | **`56` tok** changed lines (`18 ms`) | `1` call | **`98.4%` vs ARIA** (`99.7%` vs HTML) |
  15. | **10-Field Complex Form + Snapshot** (`smart_fill_form`) | `11` turns (`574 ms`, `12,197` dir / `72,614` cum tok) | **`1` turn** (`82 ms`, **`811` tok**) | **`7x` faster**, `11 -> 1` turns | **`93.4%` direct / `98.9%` cumulative** |
  16. | **48 KiB PDF Upload** (`49,152` bytes) | `44,728` tok inline Base64 tool arg | **`85` tok** disk path (`68 ms`) | Zero Base64 generation | **`99.8%` saved** |
  17. | **6-Step Interactive UI Flow** (`batch_actions`) | `6` turns (`411 ms`, `955` dir / `3,162` cum tok) | **`1` turn** (`357 ms`, **`406` tok**) | **`1.15x` faster**, `6 -> 1` turns | **`57.5%` direct / `87.2%` cumulative** |
  18. | **Open 6 Tabs Concurrently** (`open_many`) | `6` turns sequential (`998 ms`) | **`1` turn** batched (`420 ms`) | **`2.38x` faster**, `6x` fewer turns | `5` fewer prompt replays |
  19. | **Heavy Media Load** (`preset: "turbo"`, `304 KiB` assets) | `252 ms`, `9` media requests (`304 KiB`) | **`165 ms`**, `0` media requests (`0 KiB`) | **`1.53x` faster** | **`100%` media bandwidth cut** |
  20. | **Article Markdown Scraping** (`extract_clean_text`) | `3,595` tok raw HTML (`10,844` chars) | **`156` tok** clean Markdown (`641` chars) | Clean reader output | **`95.7%` saved** |
  21. | **Diagnostics Triage** (`page_diagnostics` errors-only) | `3,460` tok unfiltered (`32` req / `26` console) | **`601` tok** default errors (`2` req / `6` console) | Zero noise scrolling | **`82.6%` saved** |
  22. | **Static MCP Tool Schema** (every turn overhead) | `3,917` tok Playwright / `6,737` tok DevTools | **`3,010` tok** stripped (`3,314` full w/ annotations) | `10` tools vs `25` / `33` | **`23.2%` vs Playwright / `55.3%` vs DevTools** |
  23. > **Note on latency vs LLM inference turns:** Eliminating `10` round-trips on a 10-field form saves both `7x` in browser execution (`574 ms -> 82 ms`) and `10` separate LLM inference round-trips (`2-5s` per turn in agent loops) plus `~71,800` replayed history tokens.
  24. ---
  25. ## Why Browser Agents Stall: Side-by-Side Workflow
  26. Standard MCP servers charge an LLM round-trip for every snapshot, field fill, `<select>` choice, upload, and verification check. Each turn re-sends the growing conversation history back into the model.
  27. ```mermaid
  28. sequenceDiagram
  29. autonumber
  30. participant Agent as LLM Agent
  31. participant Std as Standard MCP (Playwright / DevTools)
  32. participant Turbo as turbo-browser-mcp
  33. Note over Agent,Std: Standard MCP (12+ LLM turns, full ARIA tree + history replay each step)
  34. Agent->>Std: 1. snapshot() -> full ARIA (~3,568 tok)
  35. loop Repeats 10+ times across fields, selects, checkboxes, upload
  36. Agent->>Std: fill / select_option / click
  37. Std-->>Agent: full ARIA or confirmation re-added to history
  38. end
  39. Agent->>Std: 12. upload inline or click chooser
  40. Note over Agent,Turbo: turbo-browser-mcp (2 LLM turns total, delta & inline snapshot)
  41. Agent->>Turbo: 1. inspect_compact(mode: "forms") -> compact refs (1,135 tok)
  42. Agent->>Turbo: 2. smart_fill_form(fields: [...10 fields + disk PDF...], returnSnapshot: true)
  43. Turbo-->>Agent: Filled 10 fields + guarded before Submit + inline snapshot (811 tok)
  44. ```
  45. ---
  46. ## What `turbo-browser-mcp` Supports
  47. ### 1. Connection & Session Isolation
  48. - **4 connection modes (`--mode auto|cdp|persistent|launch`):**
  49. - `auto` (default): probes `--cdp http://127.0.0.1:9222` first so agents can reuse an existing signed-in browser session, then falls back to launching Chromium.
  50. - `cdp`: attach directly to a running Chromium/Chrome/Edge remote debugging port.
  51. - `persistent`: launch with a reusable `--user-data-dir` profile across runs.
  52. - `launch`: start a clean browser session (`--headless` by default, or `--headed`).
  53. - **Auto binary discovery (`src/playwright-loader.mjs`):** checks `playwright-core` cache revisions across Windows, macOS, and Linux, system installs of Google Chrome, Microsoft Edge, Brave, and Chromium, or an explicit `--executable <path>`.
  54. - **Per-tab isolation (`tabs_batch`):** open tabs inside named `isolatedContext` sandboxes with separate cookies and storage, batch-open up to 10 concurrent URLs (`open_many`), activate, reload, go `back`/`forward`, `resize` viewport, and emulate `colorScheme`, `media`, `reducedMotion`, `contrast`, `forcedColors`, or custom `userAgent`.
  55. ### 2. DOM, Iframe & Shadow DOM Inspection (`inspect_compact`)
  56. - **Snapshot modes:** `interactive`, `forms`, `article`, and `all`.
  57. - **Cross-boundary traversal:** flattens main frame DOM, child iframes (`includeFrames`, `frameIdx`), and open Shadow DOM. Injects an init script hooking `Element.prototype.attachShadow` (`WeakMap` + `WeakRef`/`FinalizationRegistry` + `window.__tbmGetShadowRoot`) to keep post-init closed Shadow roots inspectable and guarded, traverses `<slot>` `assignedNodes({ flatten: true })`, and supports Form-Associated Custom Elements.
  58. - **Token controls:** `onlyChanged: true` emits only elements added or changed since the prior snapshot; `query` filters by regex or substring; `boxes: true` adds `[box=x,y,w,h]` only when needed; `maxChars` caps payload size; `savePath` writes full output to disk.
  59. ### 3. Single-Turn Smart Form Engine (`smart_fill_form`)
  60. Prefills an entire form in one MCP call while flushing microtasks and macrotasks between controlled inputs:
  61. - **Standard & framework inputs:** text, email, password, number, date, textarea, `<input type="range">`, checkboxes, radio groups (`check`, `not`, `overwrite`). Triggers React-controlled state updates via native property setters and synthetic events.
  62. - **Selects & custom widgets:** `<select>` and `<select multiple>` (`option` / `values`), ARIA comboboxes, ARIA switches, `contenteditable` rich editors, and Gmail compose dialogs (`gmail: { to, subject, body }`).
  63. - **Frame & wildcard targeting:** target specific iframes via `frameIdx`, or set `all: true` to populate matching controls across frames.
  64. - **Direct disk uploads:** pass `file` or `files` paths directly to Playwright `setInputFiles` without loading binary files or Base64 strings into LLM context.
  65. - **Atomic verification:** pass `returnSnapshot: true` to inspect the updated form state in the same tool response.
  66. ### 4. 16 Interactive Actions & Multi-Step Chaining (`act_fast`, `batch_actions`)
  67. - **`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`.
  68. - **Targeting options:** compact `[eN]` `ref`, CSS `selector`, visible `text`, `label`, or viewport `(x, y)` coordinates, with `button` (`left`, `right`, `middle`) and `frameIdx`.
  69. - **`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`).
  70. ### 5. Clean Extraction, Evaluation & Media Capture (`extract_clean_text`, `evaluate_js`, `capture_page`)
  71. - **`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.
  72. - **`evaluate_js`:** runs JS expressions or `(el, arg)` element functions in any frame (`frameIdx`) with JSON-serialized results and optional `savePath` export.
  73. - **`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`.
  74. ### 6. Network Blocking, Storage State & Diagnostics (`network_session`, `page_diagnostics`)
  75. - **`network_session` presets:** `turbo`, `no-images`, `no-media`, and `clean` (unblock all), alongside custom `blockResources` and `blockUrls` patterns.
  76. - **Session & storage management:** read/write/clear browser `cookies`, `localStorage`/`sessionStorage`, and export or reload full Playwright `storageState` JSON files (`saveStorageStatePath`, `loadStorageStatePath`).
  77. - **`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`).
  78. ---
  79. ## Reproducible Benchmarks (`npm run benchmark`)
  80. Run the benchmark suite yourself with Chromium and Playwright installed:
  81. ```bash
  82. npm run benchmark
  83. ```
  84. **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.
  85. ### 1. Snapshot & Reader Extraction (Chars & Exact `o200k_base` Tokens)
  86. | Scenario | Raw HTML | Full Playwright ARIA | `turbo-browser-mcp` Output | Saved vs ARIA | Saved vs HTML |
  87. | :--- | :--- | :--- | :--- | :--- | :--- |
  88. | **140-Button SaaS Console** (`inspect_compact`) | `61,010` chars (`18,654` tok) | `12,771` chars (`3,568` tok) | **`3,968` chars (`1,135` tok)** | **`68.2%`** | **`93.9%`** |
  89. | **Post-Click Delta** (`onlyChanged: true`) | `61,010` chars (`18,654` tok) | `12,825` chars (`3,582` tok) | **`168` chars (`56` tok)** | **`98.4%`** | **`99.7%`** |
  90. | **Article Markdown Extraction** (`extract_clean_text`) | `10,844` chars (`3,595` tok) | n/a | **`641` chars (`156` tok)** | n/a | **`95.7%`** |
  91. | **Diagnostics Filter** (`32` reqs, `26` console logs) | `9,651` chars (`3,460` tok, `all`) | n/a | **`1,761` chars (`601` tok, `errors`)** | n/a | **`82.6%`** |
  92. ### 2. Multi-Turn Forms, Workflows, Uploads & Network Speed
  93. | Scenario | Step-by-Step Baseline | `turbo-browser-mcp` | Execution Speedup | Token Savings |
  94. | :--- | :--- | :--- | :--- | :--- |
  95. | **10-Field Complex Form + Verify** (`smart_fill_form`) | `11` turns, `574 ms`, `12,197` direct / `72,614` cum tok | **`1` turn**, **`82 ms`**, **`811` tok** (`filled=10`) | **`7x` faster** | **`93.4%` dir / `98.9%` cum** |
  96. | **48 KiB PDF Upload** (`49,152` bytes via `file`) | `65,679` chars (`44,728` tok) Base64 payload | **`263` chars (`85` tok)** disk path (`68 ms`) | Zero LLM Base64 encode | **`99.8%`** |
  97. | **6-Step UI Flow** (`batch_actions`) | `6` turns, `411 ms`, `955` dir / `3,162` cum tok | **`1` turn**, **`357 ms`**, **`406` tok** | **`1.15x` faster** | **`57.5%` dir / `87.2%` cum** |
  98. | **Open 6 Tabs** (`tabs_batch` `open_many`, `60 ms` TTFB) | `6` turns sequential (`998 ms`) | **`1` turn** batched (`420 ms`) | **`2.38x` faster** (`6 -> 1` turns) | Eliminates `5` turns |
  99. | **Heavy Media Load** (`8x32 KiB` imgs + `48 KiB` font) | `252 ms`, `9` media hits (`304 KiB`) | **`165 ms`**, `0` media hits (`0 KiB`) | **`1.53x` faster** | **`100%` media saved** |
  100. ### 3. Static MCP Tool Definition Footprint
  101. Measured against installed MCP JSON schemas on disk (compact parameter schemas without `annotations`):
  102. | MCP Server | Tool Count | Compact Schema Chars | Exact `o200k_base` Tokens | Savings with `turbo-browser-mcp` |
  103. | :--- | :--- | :--- | :--- | :--- |
  104. | `turbo-browser-mcp` | **`10`** (`14,186` full / `12,796` compact) | **`12,796`** | **`3,010`** (`3,314` full w/ annotations) | Baseline (`10` tools) |
  105. | `@playwright/mcp` | `25` | `18,457` | `3,917` | **`23.2%` fewer static tokens** |
  106. | `chrome-devtools-mcp` | `33` | `30,252` | `6,737` | **`55.3%` fewer static tokens** |
  107. ---
  108. ## Comparison vs `@playwright/mcp` and `chrome-devtools-mcp`
  109. | Feature | `turbo-browser-mcp` | `@playwright/mcp` | `chrome-devtools-mcp` |
  110. | :--- | :--- | :--- | :--- |
  111. | **Tool Surface Size** | **10 batched tools** | 25 granular tools | 33 granular tools |
  112. | **Delta Snapshots (`onlyChanged`)** | Built-in | Full tree every snapshot | Full tree every snapshot |
  113. | **Closed Shadow DOM Hook** | Post-init `attachShadow` hook + `<slot>` flattening | Open Shadow DOM | CDP / standard DOM access |
  114. | **Single-Call Smart Form + Contenteditable** | Yes (React, Shadow DOM, iframe, Gmail, ranges) | Multi-turn fill + separate select calls | Basic `fill_form` |
  115. | **Disk File Upload (Zero Base64)** | Native `file`/`files` path in `smart_fill_form` & `act_fast` | Dedicated `browser_file_upload` turn | Dedicated `upload_file` turn |
  116. | **Default Human-in-the-Loop Submit Guard** | Yes (`allowSubmit=false`, form/iframe/Enter hooks) | No | No |
  117. | **Parallel `open_many` + `isolatedContext`** | Single batched call | Separate sequential tab calls | Separate page calls |
  118. | **One-Call `turbo` Media Blocker** | Built-in (`turbo`, `no-images`, `no-media`) | Manual JS / routing | Network emulation |
  119. | **Performance / Heap Profiling** | Not included | Not included | **Trace, Lighthouse, Heap Snapshot** |
  120. > **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.
  121. ### Tool Parity Map
  122. | Capability | `turbo-browser-mcp` | `@playwright/mcp` | `chrome-devtools-mcp` |
  123. | :--- | :--- | :--- | :--- |
  124. | Multi-tab open, list, switch, resize, emulate | `tabs_batch` | `browser_tabs`, `browser_navigate`, `browser_resize`, ... | `new_page`, `list_pages`, `select_page`, `resize_page`, ... |
  125. | DOM / accessibility inspection | `inspect_compact` | `browser_snapshot` | `take_snapshot` |
  126. | Multi-field form & upload | `smart_fill_form` | `browser_fill_form` + `browser_select_option` + `browser_file_upload` | `fill_form` + `upload_file` |
  127. | Click, type, drag, press, scroll, wait | `act_fast` | `browser_click`, `browser_type`, `browser_drag`, ... | `click`, `type_text`, `drag`, `press_key`, `wait_for` |
  128. | Multi-step sequential macro | `batch_actions` | `browser_run_code_unsafe` or N tool calls | N separate tool calls |
  129. | Clean article extraction | `extract_clean_text` | `browser_evaluate` custom JS | `evaluate_script` custom JS |
  130. | Frame/element JS evaluation | `evaluate_js` | `browser_evaluate` | `evaluate_script` |
  131. | Errors, network & console triage | `page_diagnostics` | `browser_console_messages`, `browser_network_requests` | `list_console_messages`, `list_network_requests`, ... |
  132. | Screenshots & PDF export | `capture_page` | `browser_take_screenshot` | `take_screenshot` |
  133. | Blocking presets, cookies & storage | `network_session` | `browser_evaluate` + context config | Partial via `evaluate_script` / `emulate` |
  134. ---
  135. ## Safety: Human-in-the-Loop Submit Guard & Path Confinement
  136. 1. **Human-in-the-loop Submit Guard (`allowSubmit=false` by default):**
  137. - `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.
  138. - 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.
  139. - 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.
  140. 2. **Workspace Path Confinement (`TURBO_BROWSER_SAVE_ROOT`):**
  141. - File outputs (`savePath`, `saveStorageStatePath`) and state inputs (`loadStorageStatePath`) are strictly confined to the current working directory or `TURBO_BROWSER_SAVE_ROOT`.
  142. - 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.
  143. ---
  144. ## All 10 Tools Reference
  145. | Tool | Purpose | Key Parameters |
  146. | :--- | :--- | :--- |
  147. | `tabs_batch` | Ordered tab & browser lifecycle | `operations[]` (`list`, `open`, `open_many`, `navigate`, `activate`, `resize`, `emulate`, `reload`, `back`, `forward`, `close`, `close_browser`), `isolatedContext`, `concurrency` (1-10) |
  148. | `inspect_compact` | Token-capped element/form/article snapshot | `mode` (`interactive`, `forms`, `article`, `all`), `onlyChanged`, `query`, `boxes`, `maxChars`, `includeFrames`, `savePath` |
  149. | `smart_fill_form` | Batch form, editor & disk file prefill | `fields[]` (`ref`, `selector`, `value`, `option`, `values`, `check`, `not`, `keys`, `file`, `files`, `frameIdx`, `all`), `gmail`, `overwrite`, `stopBeforeSubmit`, `returnSnapshot` |
  150. | `act_fast` | Single targeted page action | `action` (`16` actions), `ref`/`selector`/`text`/`label`/`(x, y)`, `modifiers`, `dropData`, `allowSubmit`, `returnSnapshot` |
  151. | `batch_actions` | Ordered chain of actions + form steps | `steps[]`, `continueOnError`, `allowSubmit`, `returnSnapshot`, `snapshotMaxChars` |
  152. | `extract_clean_text` | Clean text or compact Markdown reader | `format` (`text`, `markdown`), `selector`, `includeFrames`, `maxChars`, `savePath` |
  153. | `evaluate_js` | Scoped JS expression or `(el, arg)` call | `expression`, `arg`, `frameIdx`, `ref`/`selector`/`text`, `savePath` |
  154. | `page_diagnostics` | Console, network, downloads & dialogs | `level` (`errors`, `all`), `statusFilter` (`errors`, `all`), `includeStatic`, `urlFilter`, `reqId`, `part`, `dialogPolicy`, `clear`, `savePath` |
  155. | `capture_page` | PNG/JPEG screenshots & PDF export | `mode` (`screenshot`, `pdf`), `type`, `quality`, `fullPage`, `scale` (`css`, `device`), `ref`/`selector`/`text`, `returnImage`, `savePath` |
  156. | `network_session` | Resource blockers, cookies & storage | `preset` (`turbo`, `no-images`, `no-media`, `clean`), `blockResources`, `blockUrls`, `cookieAction`, `storageAction`, `loadStorageStatePath`, `saveStorageStatePath` |
  157. ### Copy-Paste JSON Examples
  158. #### 1. Fill a 10-field form with a disk PDF & inspect result in 1 turn
  159. ```json
  160. {
  161. "name": "smart_fill_form",
  162. "arguments": {
  163. "fields": [
  164. { "selector": "#full_name", "value": "Alex Nguyen" },
  165. { "selector": "#email", "value": "alex@example.com" },
  166. { "selector": "#country", "option": "United States" },
  167. { "selector": "#skills", "values": ["TypeScript", "Playwright"] },
  168. { "selector": "#agree_terms", "check": true },
  169. { "selector": "#resume_pdf", "file": "./assets/resume.pdf" }
  170. ],
  171. "stopBeforeSubmit": true,
  172. "returnSnapshot": true
  173. }
  174. }
  175. ```
  176. #### 2. Read only changed controls after opening a modal (`onlyChanged`)
  177. ```json
  178. {
  179. "name": "inspect_compact",
  180. "arguments": {
  181. "mode": "interactive",
  182. "onlyChanged": true,
  183. "maxChars": 3000
  184. }
  185. }
  186. ```
  187. #### 3. Open tabs concurrently in isolated contexts & speed up loading with `turbo`
  188. ```json
  189. {
  190. "name": "tabs_batch",
  191. "arguments": {
  192. "operations": [
  193. { "action": "open", "url": "https://example.com/app", "isolatedContext": "acct-a" },
  194. { "action": "open_many", "urls": ["https://example.com/docs", "https://example.com/pricing"], "concurrency": 4 }
  195. ]
  196. }
  197. }
  198. ```
  199. ---
  200. ## Quick Start
  201. ### Install & Check Environment
  202. ```bash
  203. git clone https://github.com/Tthanh2k6/turbo-browser-mcp.git
  204. cd turbo-browser-mcp
  205. npm install
  206. npm run doctor
  207. ```
  208. If you need Playwright's bundled Chromium (or have no system Chrome/Edge/Brave installed):
  209. ```bash
  210. npx playwright-core install chromium
  211. ```
  212. ### MCP Client Config (Claude Code, Cursor, Antigravity, Codex)
  213. Using local clone:
  214. ```json
  215. {
  216. "mcpServers": {
  217. "turbo-browser": {
  218. "command": "node",
  219. "args": ["/absolute/path/to/turbo-browser-mcp/src/index.mjs"],
  220. "env": {
  221. "TURBO_BROWSER_SAVE_ROOT": "/absolute/path/to/allowed/workspace"
  222. }
  223. }
  224. }
  225. }
  226. ```
  227. Using `npx` / binary entrypoint:
  228. ```json
  229. {
  230. "mcpServers": {
  231. "turbo-browser": {
  232. "command": "npx",
  233. "args": ["-y", "turbo-browser-mcp"]
  234. }
  235. }
  236. }
  237. ```
  238. ---
  239. ## CLI Options & Environment Variables
  240. | CLI Flag | Environment Variable | Default | Description |
  241. | :--- | :--- | :--- | :--- |
  242. | `--mode <auto\|cdp\|persistent\|launch>` | `TURBO_BROWSER_MODE` | `auto` | Connection strategy (`cdp` first then launch in `auto`) |
  243. | `--cdp <url>` | `TURBO_BROWSER_CDP_URL` | `http://127.0.0.1:9222` | Chrome DevTools Protocol HTTP endpoint |
  244. | `--user-data-dir <path>` | `TURBO_BROWSER_USER_DATA_DIR` | `""` | Persistent profile directory path |
  245. | `--executable <path>` | - | auto-detected | Custom Chromium, Chrome, Edge, or Brave executable |
  246. | `--timeout <ms>` | `TURBO_BROWSER_TIMEOUT_MS` | `15000` | Default Playwright action/navigation timeout in ms |
  247. | `--headless` / `--headed` | `TURBO_BROWSER_HEADLESS` | `true` (headless) | Run headless or visible browser window (`"false"` for headed) |
  248. | `--allow-submit` | - | `false` | Disable default Submit/Publish confirmation guard |
  249. | `--doctor` | - | - | Print Node, Playwright, Chromium, and CDP diagnostics as JSON |
  250. | `--bridge` | `TURBO_BROWSER_BRIDGE_PORT` | `9224` | Start/verify the persistent CDP Keep-Alive Bridge daemon for Chrome 144+ `DevToolsActivePort` (approve once, reconnect unlimited times AFK) |
  251. | `--launch-chrome` | - | `~/.turbo-browser-mcp/chrome-profile` | Launch Chrome with a dedicated profile & `--remote-debugging-port=9222` (`0` approval prompts ever) |
  252. | `--version` / `-v` | - | - | Print server version (`0.4.0`) |
  253. | `--help` / `-h` | - | - | Print CLI usage summary |
  254. | - | `TURBO_BROWSER_SAVE_ROOT` | `process.cwd()` | Root directory confining `savePath` and `storageState` files |
  255. | - | `PLAYWRIGHT_CORE_PATH` | auto-resolved | Explicit path to `playwright-core/index.mjs` |
  256. ### Unattended Overnight / AFK Automation (Eliminating Chrome 144+ Approval Prompts)
  257. 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:
  258. 1. **Automatic CDP Keep-Alive Bridge Daemon (`npm run bridge` / `--bridge`, enabled automatically on `DevToolsActivePort`)**:
  259. - 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.
  260. - 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**.
  261. 2. **Zero-Prompt Dedicated Profile Launcher (`npm run launch-chrome` / `--launch-chrome`)**:
  262. - 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**.
  263. ---
  264. ## Verification
  265. ```bash
  266. npm test # 407 passing tests across 86 suites (26 test files under test/*.test.mjs)
  267. npm run doctor # Environment check for Node, Playwright, Chromium, and CDP
  268. npm run bridge # Start/verify persistent CDP Keep-Alive Bridge daemon
  269. npm run benchmark # Local Chromium speed & exact o200k_base token benchmark
  270. ```
  271. Tested automatically on GitHub Actions (`ubuntu-latest`) across **Node 20** and **Node 22**.
  272. ## License
  273. [MIT](LICENSE)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.