turbo-browser-mcp
Health Gecti
- License — License: MIT
- Description — Repository has a description
- Active repo — Last push 0 days ago
- Community trust — 115 GitHub stars
Code Basarisiz
- spawnSync — Synchronous process spawning in benchmarks/benchmark.mjs
- fs.rmSync — Destructive file system operation in benchmarks/benchmark.mjs
- network request — Outbound network request in benchmarks/benchmark.mjs
- network request — Outbound network request in benchmarks/e2e-agent/evaluate.mjs
- spawnSync — Synchronous process spawning in benchmarks/e2e-agent/runner.mjs
- fs.rmSync — Destructive file system operation in benchmarks/e2e-agent/runner.mjs
- os.homedir — User home directory access in benchmarks/e2e-agent/runner.mjs
- process.env — Environment variable access in benchmarks/e2e-agent/runner.mjs
- network request — Outbound network request in benchmarks/e2e-agent/runner.mjs
- network request — Outbound network request in benchmarks/e2e-agent/self-test.mjs
- network request — Outbound network request in benchmarks/e2e-agent/server.mjs
- spawnSync — Synchronous process spawning in benchmarks/e2e-tasks.mjs
- fs.rmSync — Destructive file system operation in benchmarks/e2e-tasks.mjs
- process.env — Environment variable access in benchmarks/e2e-tasks.mjs
- network request — Outbound network request in benchmarks/e2e-tasks.mjs
Permissions Gecti
- Permissions — No dangerous permissions requested
Bu listing icin henuz AI raporu yok.
Playwright MCP server built to cut agent turns and tokens: one-call form filling, delta snapshots, batched steps, and a submit guard on by default
turbo-browser-mcp
An MCP server for browser automation, built on Playwright. It has 11 tools where @playwright/mcp has 25 and chrome-devtools-mcp has 33, and each tool does more per call:
- one
smart_fill_formcall fills a whole form, including React inputs, selects, comboboxes, rich-text editors and file uploads read from disk; inspect_compactcan return only the elements that changed since the last snapshot;batch_actionsruns a list of clicks, key presses and form steps as one call.
Fewer calls means fewer model turns and less page text replayed in the conversation. The numbers are in Benchmarks.
Buttons that look like a final commit (Submit, Send, Publish, Pay, Confirm, and their Korean, Japanese, Chinese and Vietnamese equivalents) are blocked by default, so an agent can prefill a form and leave the last click to a person. Pass allowSubmit: true per call or start with --allow-submit to turn this off.
The server does not hide that the browser is automated: no stealth patches, no fingerprint changes, no CAPTCHA solving. For sites with a bot check it can hand the tab to a person and continue afterwards (wait_for_human).
Install
Needs Node 20 or newer and a Chromium-based browser (Chrome, Edge, Brave, or Playwright's Chromium).
Claude Code:
claude mcp add turbo-browser -- npx -y turbo-browser-mcp
Clients that read an mcpServers JSON config (Cursor, Claude Desktop, Antigravity and others):
{
"mcpServers": {
"turbo-browser": {
"command": "npx",
"args": ["-y", "turbo-browser-mcp"],
"env": { "TURBO_BROWSER_SAVE_ROOT": "/absolute/path/to/workspace" }
}
}
}
TURBO_BROWSER_SAVE_ROOT is the only folder the server may write screenshots, PDFs and storage files to, or read storage files from. Leave it out and the current working directory is used.
Check the setup, and install Chromium if no browser is found:
npx -y turbo-browser-mcp --doctor
npx playwright-core install chromium
By default the server first tries a Chrome that is already listening on http://127.0.0.1:9222, so the agent can use a browser you are signed in to, and otherwise launches its own headless Chromium. --mode, --headed and the other options are listed under CLI options.
From source:
git clone https://github.com/Tthanh2k6/turbo-browser-mcp.git
cd turbo-browser-mcp
npm install
node src/index.mjs --doctor
Tools
| Tool | Purpose | Key Parameters |
|---|---|---|
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) |
inspect_compact |
Token-capped element/form/article snapshot | mode (interactive, forms, article, all), onlyChanged, query, boxes, maxChars, includeFrames, savePath |
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 |
act_fast |
Single targeted page action | action (16 actions), ref/selector/text/label/(x, y), modifiers, dropData, allowSubmit, observeAftermath, returnSnapshot |
batch_actions |
Ordered actions, form steps and multi-page navigate/extract | steps[] (including navigate with url, extract with format, selector, maxChars), continueOnError, allowSubmit, expect, submissionKey, allowDuplicate, observeAftermath, returnSnapshot, snapshotMaxChars |
extract_clean_text |
Clean text or compact Markdown reader | format (text, markdown), selector, includeFrames, maxChars, savePath |
evaluate_js |
Scoped JS expression or (el, arg) call |
expression, arg, frameIdx, ref/selector/text, savePath |
page_diagnostics |
Console, network, downloads & dialogs | level (errors, all), statusFilter (errors, all), includeStatic, urlFilter, reqId, part, dialogPolicy, clear, savePath |
capture_page |
PNG/JPEG screenshots & PDF export | mode (screenshot, pdf), type, quality, fullPage, scale (css, device), ref/selector/text, returnImage, savePath |
network_session |
Resource blockers, cookies & storage | preset (turbo, no-images, no-media, clean), blockResources, blockUrls, cookieAction, storageAction, loadStorageStatePath, saveStorageStatePath |
wait_for_human |
Hand a step to a person, resume in the same session | message, urlMatches, selector, textMatches, textGone, timeoutMs, pollMs |
Examples
Fill a form, attach a PDF from disk, return the result in the same call
{
"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
}
}
Read only what changed after opening a modal
{
"name": "inspect_compact",
"arguments": {
"mode": "interactive",
"onlyChanged": true,
"maxChars": 3000
}
}
Open tabs in parallel in separate cookie contexts
{
"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 }
]
}
}
Allow the final click, check for a receipt, refuse a repeat
{
"name": "batch_actions",
"arguments": {
"steps": [
{ "action": "smart_fill_form", "fields": [{ "selector": "#name", "value": "홍길동" }] },
{ "action": "click", "text": "다음" },
{ "action": "click", "text": "확인" }
],
"allowSubmit": true,
"expect": { "textMatches": "접수번호\\s*R-\\d+", "timeoutMs": 8000 },
"submissionKey": "photo-contest:2026-11-15:entry-1"
}
}
Extract several pages in one call
{
"name": "batch_actions",
"arguments": {
"steps": [
{ "action": "navigate", "url": "https://example.com/catalog?page=2" },
{ "action": "extract", "format": "text", "selector": "main", "maxChars": 3000 },
{ "action": "navigate", "url": "https://example.com/catalog?page=3" },
{ "action": "extract", "format": "markdown", "selector": "main", "maxChars": 3000 }
]
}
}
Navigation uses GET in the same tab and waits for domcontentloaded. Each extract step returns the same output as extract_clean_text in its step result.
What each tool does
Connection and sessions (tabs_batch)
- 4 connection modes (
--mode auto|cdp|persistent|launch):auto(default): probes--cdp http://127.0.0.1:9222first so agents can reuse an existing signed-in browser session, then falls back to launching Chromium.cdp: attach directly to a running Chromium/Chrome/Edge remote debugging port.persistent: launch with a reusable--user-data-dirprofile across runs.launch: start a clean browser session (--headlessby default, or--headed).
- Auto binary discovery (
src/playwright-loader.mjs): checksplaywright-corecache revisions across Windows, macOS, and Linux, system installs of Google Chrome, Microsoft Edge, Brave, and Chromium, or an explicit--executable <path>. - Per-tab isolation (
tabs_batch): open tabs inside namedisolatedContextsandboxes with separate cookies and storage, batch-open up to 10 concurrent URLs (open_many), activate, reload, goback/forward,resizeviewport, and emulatecolorScheme,media,reducedMotion,contrast,forcedColors, or customuserAgent.
Page snapshots (inspect_compact)
- Snapshot modes:
interactive,forms,article, andall. - Cross-boundary traversal: flattens main frame DOM, child iframes (
includeFrames,frameIdx), and open Shadow DOM. Injects an init script hookingElement.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. - Token controls:
onlyChanged: trueemits only elements added or changed since the prior snapshot;queryfilters by regex or substring;boxes: trueadds[box=x,y,w,h]only when needed;maxCharscaps payload size;savePathwrites full output to disk.
Forms in one call (smart_fill_form)
Prefills an entire form in one MCP call while flushing microtasks and macrotasks between controlled inputs:
- 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. - Selects & custom widgets:
<select>and<select multiple>(option/values), ARIA comboboxes, ARIA switches,contenteditablerich editors, and Gmail compose dialogs (gmail: { to, subject, body }). - Frame & wildcard targeting: target specific iframes via
frameIdx, or setall: trueto populate matching controls across frames. - Direct disk uploads: pass
fileorfilespaths directly to PlaywrightsetInputFileswithout loading binary files or Base64 strings into LLM context. - Atomic verification: pass
returnSnapshot: trueto inspect the updated form state in the same tool response.
Actions and chains (act_fast, batch_actions)
act_fastactions:click,dblclick,hover,focus,clear,fill,type(slowly,delayMs,submit),select,check,uncheck,drag,drop(file,files, or custom MIMEdropData),press(key+modifiers:Alt,Control,ControlOrMeta,Meta,Shift),scroll(dx,dy),wait(ms,state,loadState,text,textGone,url), andupload.- Targeting options: compact
[eN]ref, CSSselector, visibletext,label, or viewport(x, y)coordinates, withbutton(left,right,middle) andframeIdx. batch_actions: runs an ordered list of DOM actions, nestedsmart_fill_formsteps, andnavigate/extractsteps for multi-page reading in one MCP call, stopping safely if blocked by the Submit guard or optionally continuing on step errors (continueOnError).
Text, JavaScript and screenshots (extract_clean_text, evaluate_js, capture_page)
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 optionalsavePathexport.capture_page: full-page or element-scoped screenshots (pngorjpegwithquality,cssordevicescale, optionalreturnImage) and PDF generation saved to a confinedsavePath.
Network, storage and diagnostics (network_session, page_diagnostics)
network_sessionpresets:turbo,no-images,no-media, andclean(unblock all), alongside customblockResourcesandblockUrlspatterns.- Session & storage management: read/write/clear browser
cookies,localStorage/sessionStorage, and export or reload full PlaywrightstorageStateJSON files (saveStorageStatePath,loadStorageStatePath). page_diagnostics: defaults to errors-only (level: "errors",statusFilter: "errors") to surface failures cleanly without flooding context, while supportingall,includeStatic,urlFilter, deep request/response inspection (reqId+part), completed downloads, and dialog auto-handling (dialogPolicy:accept/dismiss).
Benchmarks
Per-tool measurements (npm run benchmark)
These come from benchmarks/benchmark.mjs on local fixture pages in headless Chromium. Tokens are counted with tiktoken (o200k_base). They measure the size of tool output and the time spent in the browser. Model time is not included, so read them as an upper bound on what an agent gains, not as an agent result.
"Cumulative" tokens model a chat agent that re-reads every earlier tool result on each turn: over N turns, the output of turn i is read N − i + 1 times. Each call saved is also one model round-trip, which in most agent loops takes longer than the browser work itself.
Snapshots and text extraction
| Scenario | Raw HTML | Full Playwright ARIA | turbo-browser-mcp Output |
Saved vs ARIA | Saved vs HTML |
|---|---|---|---|---|---|
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% |
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% |
Article Markdown Extraction (extract_clean_text) |
10,844 chars (3,595 tok) |
n/a | 641 chars (156 tok) |
n/a | 95.7% |
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% |
Forms, multi-step flows, uploads and page loading
| Scenario | Step-by-Step Baseline | turbo-browser-mcp |
Execution Speedup | Token Savings |
|---|---|---|---|---|
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 |
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% |
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 |
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 |
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 |
Tool schema size (sent to the model on every turn)
Measured against installed MCP JSON schemas on disk (compact parameter schemas without annotations):
| MCP Server | Tool Count | Compact Schema Chars | Exact o200k_base Tokens |
Savings with turbo-browser-mcp |
|---|---|---|---|---|
turbo-browser-mcp |
11 (15,144 full / 13,631 compact) |
13,631 |
3,170 (3,541 full w/ annotations) |
Baseline (11 tools) |
@playwright/mcp |
25 |
18,457 |
3,917 |
19.1% fewer static tokens |
chrome-devtools-mcp |
33 |
30,252 |
6,737 |
52.9% fewer static tokens |
v0.5.0 added wait_for_human and the commit-safety parameters for about 160 tokens per turn (v0.4.0: 3,010 compact). To keep that small, expect / submissionKey / allowDuplicate are declared only on batch_actions (a one-step batch works for a single click), and the network guard is switched on by environment variable, so it costs no schema tokens. The label lists for other languages run inside the page and are never sent to the model.
Scripted end-to-end task (npm run benchmark:e2e)
benchmarks/E2E_COMPARISON.md runs a fixed script against a Korean-language contest wizard (6 fields, a 다음 step, a 확인 inside a modal, a receipt page). One action per call with a full ARIA snapshot after each takes 9 calls and 32,942 cumulative context tokens. inspect_compact plus one batch_actions call with expect takes 2 calls and 1,430 tokens, and confirms the receipt number itself. The same file covers the commit-safety cases.
Agent benchmark against other browser stacks (stage 1)
benchmarks/e2e-agent/ gives a coding agent three tasks on local fixture sites (a job application with a file upload, a catalog search over several pages, a booking with a draft step and a confirmation) and runs it with each stack. The fixture server decides success: one committed record with the right fields and file bytes, and a receipt in the answer that matches it. Host agent: Claude Code with Claude Sonnet 5.5, one trial per cell, 16 Nov 2026.
| Stack | Tasks passed | Turns | Cost (USD) | Seconds |
|---|---|---|---|---|
| turbo-browser-mcp 0.6.1 (headless) | 3/3 | 42 | 0.395 | 85.8 |
| agent-browser 0.43.0 (headless) | 3/3 | 33 | 0.440 | 196.8 |
| browse 0.0.17 (headed Chrome, extension) | 3/3 | 20 | 0.237 | 118.6 |
| browser-use 1.0.5 (headed Chrome) | 3/3 | 33 | 0.344 | 120.6 |
Every stack passed every task. turbo-browser-mcp was fastest in total and browse was cheapest. One trial per cell is not enough to rank them, and the headless and headed browsers are not equally fast. The application task cost turbo-browser-mcp 23 turns, the most of any trial; that is being looked into. Per-task numbers, how tokens are counted, and the harness fixes made during the run are in benchmarks/E2E_RESULTS.md.
Comparison with @playwright/mcp and chrome-devtools-mcp
| Feature | turbo-browser-mcp |
@playwright/mcp |
chrome-devtools-mcp |
|---|---|---|---|
| Number of tools | 11 | 25 granular tools | 33 granular tools |
Delta Snapshots (onlyChanged) |
Built-in | Full tree every snapshot | Full tree every snapshot |
| Closed Shadow DOM Hook | Post-init attachShadow hook + <slot> flattening |
Open Shadow DOM | CDP / standard DOM access |
| Single-Call Smart Form + Contenteditable | Yes (React, Shadow DOM, iframe, Gmail, ranges) | Multi-turn fill + separate select calls | Basic fill_form |
| Disk File Upload (Zero Base64) | Native file/files path in smart_fill_form & act_fast |
Dedicated browser_file_upload turn |
Dedicated upload_file turn |
| Default Human-in-the-Loop Submit Guard | Yes (allowSubmit=false, form/iframe/Enter hooks) |
No | No |
Parallel open_many + isolatedContext |
Single batched call | Separate sequential tab calls | Separate page calls |
One-Call turbo Media Blocker |
Built-in (turbo, no-images, no-media) |
Manual JS / routing | Network emulation |
| Performance / Heap Profiling | Not included | Not included | Trace, Lighthouse, Heap Snapshot |
When to keep Chrome DevTools MCP alongside
turbo-browser-mcp:chrome-devtools-mcpprovides Lighthouse audits, performance trace analysis, CSS computed style panels, and V8 heap snapshots.turbo-browser-mcpfocuses on fast multi-step UI automation, forms, and scraping with minimal token overhead.
Tool mapping
| Capability | turbo-browser-mcp |
@playwright/mcp |
chrome-devtools-mcp |
|---|---|---|---|
| Multi-tab open, list, switch, resize, emulate | tabs_batch |
browser_tabs, browser_navigate, browser_resize, ... |
new_page, list_pages, select_page, resize_page, ... |
| DOM / accessibility inspection | inspect_compact |
browser_snapshot |
take_snapshot |
| Multi-field form & upload | smart_fill_form |
browser_fill_form + browser_select_option + browser_file_upload |
fill_form + upload_file |
| Click, type, drag, press, scroll, wait | act_fast |
browser_click, browser_type, browser_drag, ... |
click, type_text, drag, press_key, wait_for |
| Multi-step sequential macro | batch_actions |
browser_run_code_unsafe or N tool calls |
N separate tool calls |
| Clean article extraction | extract_clean_text |
browser_evaluate custom JS |
evaluate_script custom JS |
| Frame/element JS evaluation | evaluate_js |
browser_evaluate |
evaluate_script |
| Errors, network & console triage | page_diagnostics |
browser_console_messages, browser_network_requests |
list_console_messages, list_network_requests, ... |
| Screenshots & PDF export | capture_page |
browser_take_screenshot |
take_screenshot |
| Blocking presets, cookies & storage | network_session |
browser_evaluate + context config |
Partial via evaluate_script / emulate |
Safety
Submit guard and file path limits
- Human-in-the-loop Submit Guard (
allowSubmit=falseby default):smart_fill_form(stopBeforeSubmit: true),act_fast, andbatch_actionsinspect matching elements, W3C AccName labels (isSafeSubmitter), implicit HTML form Enter submissions, key chords (Shift+Enter,Enter+Shift),HTMLFormElement.prototype.submit/requestSubmit, and same-origin iframecontentWindow/contentDocumentproxies.- Final actions resembling
Submit,Publish,Send,Post,Apply,Confirm, or payment triggers are blocked unlessallowSubmit: trueis explicitly passed or--allow-submitis 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.
- Workspace Path Confinement (
TURBO_BROWSER_SAVE_ROOT):- File outputs (
savePath,saveStorageStatePath) and state inputs (loadStorageStatePath) are strictly confined to the current working directory orTURBO_BROWSER_SAVE_ROOT. - Lexical checks,
lstatSync/readlinkSyncsymlink verification, andrealpathSyncvalidation block..traversal, UNC network paths, dangling symlinks, cyclic symlinks, and Windows junctions before reading or writing.
- File outputs (
Commit checks: expect, submissionKey, modal and network guards
Readers who run agents on real portals pointed out three gaps in a label-based guard. v0.5.0 adds an opt-in answer to each. expect, submissionKey and allowDuplicate appear in the batch_actions schema; act_fast accepts the same arguments without advertising them. The network guard is turned on with TURBO_BROWSER_NETWORK_GUARD=true and covers act_fast, batch_actions and smart_fill_form.
- A landed click is not a confirmed submission →
expect. After an allowed submit, passexpect: { urlMatches?, textMatches?, selector?, timeoutMs? }. The result carriessubmitVerifiedandevidence(the new URL, a text snippet such as a receipt number, or the matched selector). If nothing shows up in time you getsubmitVerified: falseand a reason, so the agent does not report "done" on an empty submission list. - A re-run is a second entry, not a retry →
submissionKey. WithsubmissionKey: "portal:2026-11-15:entry-42", every allowed submit is appended to a JSONL ledger (~/.turbo-browser-mcp/submissions.jsonl, orTURBO_BROWSER_LEDGER, orledgerPathinside the save root). A later call with the same key is refused withblockedBy: "ledger"unlessallowDuplicate: true. - Labels lie → modal rule +
networkGuard. On many Korean portals the last step reads 다음 and the real commit is a 확인 inside a modal that opens afterwards.- Affirmative buttons (
확인,OK,Yes,Confirm,確認,确定,Đồng ý, …) insidedialog/[role=dialog]/[role=alertdialog]/[aria-modal=true]now count as commits (blockedBy: "modal"). Cookie banners (dialog text mentions cookies) and date/time pickers (dialog contains a calendar grid or date input) are excluded; a confirmation that only mentions "privacy" or "consent" is still blocked. - When an action makes the page call
form.submit()/requestSubmit()or fire asubmitevent and the guard stops it, the result now says so (submitSuppressed,note) instead of a bareok: true. The action itself (a select, a check) still counts as done, so batches continue. - Common Korean, Japanese, Chinese and Vietnamese submit labels were added (
제출,신청,등록,결제,送信,確定,提交,Hoàn tất, …), and다음,次へ,下一步are treated likeNext. TURBO_BROWSER_NETWORK_GUARD=trueis the safety net that does not depend on labels: while submitting is not allowed, non-GET navigations and same-sitefetch/XHRPOST/PUT/PATCH/DELETEare stopped and reported (blockedBy: "network",networkBlocked[]). Blocked navigations get a204so the page and the half-filled form stay put. Let harmless endpoints through withTURBO_BROWSER_NETWORK_GUARD_ALLOW="/autosave$,/analytics". Per call, the undeclared argumentsnetworkGuard,networkGuardAllowandnetworkGuardSettleMsoverride the env values. It is off by default because multi-step wizards oftenPOSTon every "Next".- Every blocked result now says which mechanism stopped it:
blockedByislabel,modal,networkorledger.
- Affirmative buttons (
Limits:
- The network guard watches the action plus
networkGuardSettleMs(250 ms) afterwards, so a commit fired later by a timer is not caught. WebSocket messages, requests made by a service worker, and cross-sitefetchPOSTs are not inspected (cross-site navigations are). Patterns inTURBO_BROWSER_NETWORK_GUARD_ALLOWare split on commas, so a pattern cannot contain one. - The ledger is written only when the call returns. If the call throws after the page already sent the submission (for example a navigation timeout), nothing is recorded; check the site before re-running.
expect.selectorthat is not a valid selector never matches, so the call reportssubmitVerified: falseafter the timeout.
Handing a step to a person (wait_for_human, --open-profile)
Some sites fail their bot check whenever the browser is remote-controlled, so a person has to open the same profile in a normal browser first. turbo-browser-mcp does not try to hide automation: no stealth plugins, no fingerprint or navigator.webdriver patching, no CAPTCHA solving. It supports two hand-off flows instead.
- Before the session:
turbo-browser-mcp --open-profile --url https://site.example/loginopens plain Chrome (no debugging port, no automation flags) on the dedicated profile~/.turbo-browser-mcp/chrome-profile(or--user-data-dir). The human logs in or passes the check and closes the window. Then start the server with--user-data-dir <same path>or--launch-chrome, and the agent reuses those cookies. This works for sites that check at login; a site that re-checks on every request will still see an automated browser. - During the session: the agent calls
wait_for_humanwith a message and a condition (urlMatches,selector,textMatchesortextGone). The tool brings the tab to the front and polls until the condition holds, then the agent continues in the same tab with the same cookies. KeeptimeoutMsbelow your MCP client's request timeout and call it again to keep waiting.
{
"name": "wait_for_human",
"arguments": {
"message": "Please sign in and finish the security check, then leave the tab open.",
"selector": "#account-menu",
"timeoutMs": 120000
}
}
Click aftermath reporting
Set observeAftermath: true on act_fast or batch_actions (or setTURBO_BROWSER_OBSERVE_AFTERMATH=true) to observe navigation and mutating
fetch/XHR requests for one second after each click. It is off by default.
The result includes aftermath: { beforeUrl, afterUrl, navigated, mutatingRequests, unexpectedSubmit }. Requests include their method, URL,
and a finalSubmit classification. Main-frame origin/path changes or
commit-like requests produce a warning when allowSubmit is false.
This reports an action that has already occurred. It cannot prevent a commit
or prove that a submission succeeded. Wizard navigation can trigger a warning,
and opaque endpoints or requests outside the observation window can be missed.
Use the network guard for prevention and expect for receipt verification.
See fixture and classification details.
CLI options and environment variables
| CLI Flag | Environment Variable | Default | Description |
|---|---|---|---|
--mode <auto|cdp|persistent|launch> |
TURBO_BROWSER_MODE |
auto |
Connection strategy (cdp first then launch in auto) |
--cdp <url> |
TURBO_BROWSER_CDP_URL |
http://127.0.0.1:9222 |
Chrome DevTools Protocol HTTP endpoint |
--user-data-dir <path> |
TURBO_BROWSER_USER_DATA_DIR |
"" |
Persistent profile directory path |
--executable <path> |
- | auto-detected | Custom Chromium, Chrome, Edge, or Brave executable |
--timeout <ms> |
TURBO_BROWSER_TIMEOUT_MS |
15000 |
Default Playwright action/navigation timeout in ms |
--headless / --headed |
TURBO_BROWSER_HEADLESS |
true (headless) |
Run headless or visible browser window ("false" for headed) |
--allow-submit |
- | false |
Disable default Submit/Publish confirmation guard |
--doctor |
- | - | Print Node, Playwright, Chromium, and CDP diagnostics as JSON |
--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) |
--launch-chrome |
- | ~/.turbo-browser-mcp/chrome-profile |
Launch Chrome with a dedicated profile & --remote-debugging-port=9222 (0 approval prompts ever) |
--open-profile [--url <u>] |
TURBO_BROWSER_OPEN_URL |
~/.turbo-browser-mcp/chrome-profile |
Open the profile in a normal, non-automated Chrome so a human can log in or pass a check first |
| - | TURBO_BROWSER_NETWORK_GUARD |
false |
Turn on the network commit guard by default |
| - | TURBO_BROWSER_NETWORK_GUARD_ALLOW |
"" |
Comma-separated URL regexes the network guard lets through |
| - | TURBO_BROWSER_OBSERVE_AFTERMATH |
false |
Report navigation and mutating requests after each click (see Click aftermath) |
| - | TURBO_BROWSER_LEDGER |
~/.turbo-browser-mcp/submissions.jsonl |
Submission ledger used by submissionKey |
--version / -v |
- | - | Print server version |
--help / -h |
- | - | Print CLI usage summary |
| - | TURBO_BROWSER_SAVE_ROOT |
process.cwd() |
Root directory confining savePath and storageState files |
| - | PLAYWRIGHT_CORE_PATH |
auto-resolved | Explicit path to playwright-core/index.mjs |
Unattended runs and the Chrome 144+ remote-debugging prompt
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:
- Automatic CDP Keep-Alive Bridge Daemon (
npm run bridge/--bridge, enabled automatically onDevToolsActivePort):- Spawns a detached background multiplexer (
src/cdp-bridge.mjsonhttp://127.0.0.1:9224) that holds one persistent upstream WebSocket to Chrome open indefinitely and interceptsBrowser.closeso 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.
- Spawns a detached background multiplexer (
- Zero-Prompt Dedicated Profile Launcher (
npm run launch-chrome/--launch-chrome):- Launches Chrome with
--remote-debugging-port=9222and 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.
- Launches Chrome with
Development
npm test # 437 tests in 87 suites (test/*.test.mjs)
npm run doctor # Node, Playwright, Chromium and CDP check
npm run benchmark # per-tool token and timing benchmark
npm run benchmark:e2e # scripted wizard task and commit-safety cases
CI runs the tests on Ubuntu with Node 20 and 22.
Known limits
- Portaled comboboxes (react-select, Radix, Headless UI style) have a click path and a keyboard fallback that searches up to 100 options and checks the committed value. Virtualized lists beyond the included fixtures still need testing against real apps.
- Sites with bot detection may need
wait_for_humanand a person to pass the check in the same browser. The server does not bypass those checks. - The agent benchmark has one trial per stack and task so far; the ten-trial protocol in
benchmarks/E2E_PLAN.mdhas not been run. - The network guard and click aftermath only watch a short window after each action, and do not inspect WebSocket messages or service-worker requests. Details are under commit checks.
- Closed Shadow roots that existed before the server attached to a tab cannot be reached through the hook. Actions there fall back to frame handles, coordinates and keyboard input.
Credits
Several features came from readers of the Show HN post and the dev.to article: johnnylemonny and alexcodebytes (portaled and virtualized selects), eye_java_420f1faa10ae8b86 (keyboard selection and click aftermath), amintacccp (safe submit labels), snake_doc and lukevp (end-to-end comparison, level of abstraction), vidarh (human hand-off), harrysong138759 (receipt verification and duplicate submissions).
License
Yorumlar (0)
Yorum birakmak icin giris yap.
Yorum birakSonuc bulunamadi