turbo-browser-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@turbo-browser-mcp Go to example.com/signup, fill the form with test@example.com, and show the compact page snapshot."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
turbo-browser-mcp
An MCP server for browser automation, built on Playwright. It has 11 tools, and each one does more per call than the usual one-action-per-call design:
smart_fill_formfills a whole form in one call, 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, form steps and page reads as one call.
Fewer calls means fewer model turns and less page text replayed in the conversation. The numbers, and their limits, are under 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-mcpClients 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 chromiumBy 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 --doctorRelated MCP server: Playwright MCP
Tools
Tool | Purpose | Key parameters |
| Tab and browser lifecycle |
|
| Size-capped snapshot of elements, forms or article text |
|
| Fill a form, editors and file inputs in one call |
|
| One action on the page |
|
| Ordered actions, form steps, and multi-page navigate/extract |
|
| Page text or compact Markdown |
|
| JS expression, or a function called with |
|
| Console, network, downloads and dialogs |
|
| PNG/JPEG screenshot or PDF |
|
| Resource blocking, cookies and storage |
|
| Hand a step to a person, resume in the same session |
|
The server also sends short instructions in the MCP initialize result: batch fields with smart_fill_form, chain steps with batch_actions, use onlyChanged after the first snapshot, and use refs from the latest snapshot.
With --tools core (or TURBO_BROWSER_TOOLS=core) only tabs_batch, inspect_compact, smart_fill_form, act_fast, batch_actions and extract_clean_text are listed, and calls to the other tools are refused. The default lists all 11.
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": "alex@example.com" },
{ "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.
Behavior notes
Connection.
--mode auto(default) probes--cdp http://127.0.0.1:9222and falls back to launching Chromium.cdpattaches to a running browser,persistentreuses a--user-data-dirprofile,launchstarts a clean session (headless unless--headed). The browser is found in the Playwright cache, in system installs of Chrome, Edge, Brave and Chromium, or at--executable <path>.Tabs.
isolatedContextgives a tab its own cookies and storage.open_manyopens up to 10 URLs at once.emulatesetscolorScheme,media,reducedMotion,contrast,forcedColorsor auserAgent. In CDP mode an isolated context closes with the process that opened it (and, via the bridge, with its client); tabs another process holds in its own isolated context are listed asisolatedContext:"other".Snapshots.
inspect_compactreads the main frame, child iframes (includeFrames,frameIdx) and open Shadow DOM. WithonlyChanged: truea*before a line marks a ref that is new since the last snapshot, and aRemoved:line lists refs that went away. An unchanged Submit-like button is still listed so the model knows it exists, and the submit guard still blocks it.queryfilters by regex or substring,boxes: trueadds[box=x,y,w,h],maxCharscaps the output, andsavePathwrites the full output to disk.Forms.
smart_fill_formhandles text-like inputs,<input type="range">, checkboxes, radio groups,<select>and<select multiple>, ARIA comboboxes and switches,contenteditableeditors, and Gmail compose (gmail: { to, subject, body }). Setall: trueto fill matching controls across frames.fileandfilespaths go straight to Playwright'ssetInputFiles, so file contents never enter the model's context.Actions.
act_fasttakesclick,dblclick,hover,focus,clear,fill,type,select,check,uncheck,drag,drop,press,scroll,waitandupload. A target is areffrom the latest snapshot, a CSSselector, visibletext, alabel, or(x, y)coordinates.Settle step. After a click, double click or key press with
returnSnapshotorobserveAftermath, the server waits up to 150 ms for a navigation to start, then fordomcontentloadedif one did, then until the DOM has been quiet for 80 ms and no request younger than 1.5 s is pending, at most 800 ms. There is no fixed sleep. The result hasoutcome:navigated(the URL changed),changed(the DOM changed) ornone.Errors. A missing ref lists the 3 nearest current refs with labels. An intercepted click names the covering element. A missing
selectoption lists up to 5 close options.fillreads the value back and addsmismatchwhen the field holds something else (a mask ormaxlength; a password value is not echoed).batch_actionsstops when the submit guard blocks a step, unlesscontinueOnErroris set.page_diagnosticsreturns errors only by default. Uselevel: "all",statusFilter: "all"orincludeStaticfor more, andreqIdwithpartto read one request.network_sessionpresets areturbo,no-images,no-mediaandclean(unblock everything), plus customblockResourcesandblockUrls. It reads, writes and clears cookies and web storage, and saves or loads a PlaywrightstorageStatefile.
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); if Python and tiktoken are missing, the script falls back to an approximate count and prints that. The figures 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.
Timings change from run to run. Character counts, turn counts and token counts do not.
Scenario | Step-by-step baseline |
| Saved |
140-button console snapshot ( | 61,010 chars HTML (18,654 tok); 12,771 chars full ARIA (3,568 tok) | 3,968 chars (1,135 tok) | 68.2% vs ARIA, 93.9% vs HTML |
Snapshot after a click ( | 12,825 chars full ARIA (3,582 tok) | 168 chars (56 tok) | 98.4% vs ARIA |
Article to Markdown ( | 10,844 chars HTML (3,595 tok) | 641 chars (156 tok) | 95.7% |
Diagnostics, 32 requests and 26 console lines | 9,651 chars (3,460 tok, | 1,761 chars (601 tok, | 82.6% |
10-field form and check ( | 11 turns, 12,197 tok direct, 72,614 cumulative | 1 turn, 811 tok | 93.4% direct, 98.9% cumulative; 574 ms vs 82 ms |
48 KiB PDF upload via | 65,679 chars (44,728 tok) as Base64 | 263 chars (85 tok) disk path | 99.8% |
6-step UI flow ( | 6 turns, 955 tok direct, 3,162 cumulative | 1 turn, 406 tok | 57.5% direct, 87.2% cumulative |
Open 6 tabs ( | 6 turns, 998 ms | 1 turn, 420 ms | 5 turns fewer |
Page with 8 images and a font | 9 media requests (304 KiB), 252 ms | 0 media requests with the | all media bytes |
The table is one run. On the 6-step flow, batching was about as fast as separate calls in that run (357 ms vs 411 ms) and slower in two later runs (0.43x and 0.49x speed). Its gain is in turns and tokens, not wall time.
Tool schema size
The tool definitions are sent to the model on every turn. npm run benchmark prints the size of the current schema (all 11 tools, full and compact) and of the --tools core set, plus the server instructions. The figures move with each change to a tool description, so they are not copied here. Run it before and after a schema change; CONTRIBUTING.md asks for that in pull requests. expect, submissionKey and allowDuplicate are declared only on batch_actions, and the network guard is turned on by environment variable, to keep the schema small.
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 had the lowest total time and browse the lowest cost. One trial per cell cannot rank them, and headless and headed browsers are not equally fast. The application task took turbo-browser-mcp 23 turns, the most of any trial. The transcript showed why: the agent filled each field with a separate act_fast call, and smart_fill_form could not pick an option that sat behind the list's own search box.
The unreleased main branch steers the agent to smart_fill_form and was run once more with the same harness: 23 turns, 0.256 USD and 61.6 s in total, down from 42 turns, 0.395 USD and 85.8 s. Still one trial per cell, and the other stacks were not run again. The search-box fix for smart_fill_form landed after that run and has not been measured yet. Per-task numbers, how tokens are counted, and the harness fixes made during the run are in benchmarks/E2E_RESULTS.md.
When to keep chrome-devtools-mcp as well: it offers Lighthouse audits, performance traces and heap snapshots, which turbo-browser-mcp does not.
Safety
Submit guard and file path limits
Submit guard (
allowSubmit=falseby default).smart_fill_form(withstopBeforeSubmit: true),act_fastandbatch_actionscheck the target element's role and label, Enter in a form, key chords such asShift+Enter, calls toform.submit()andrequestSubmit(), and the same calls made through a same-origin iframe. Final actions that look likeSubmit,Publish,Send,Post,Apply,Confirmor a payment trigger are blocked unlessallowSubmit: trueis passed or--allow-submitis set at startup. Closed Shadow roots that were attached before the server's init script ran (for example on a tab that was already open over CDP) and strict cross-origin sandboxed frames cannot be inspected this way. Actions there fall back to frame handles, coordinates and keyboard input.Path confinement (
TURBO_BROWSER_SAVE_ROOT).savePath,saveStorageStatePathandloadStorageStatePathwork only inside the working directory orTURBO_BROWSER_SAVE_ROOT. The check rejects..traversal, UNC paths, and symlink and junction tricks before reading or writing.
Commit checks: expect, submissionKey, modal and network guards
A label-based guard has three gaps, and each has an opt-in answer. expect, submissionKey and allowDuplicate appear in the batch_actions schema; act_fast accepts them 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 click that landed is not a confirmed submission: use
expect. After an allowed submit, passexpect: { urlMatches?, textMatches?, textNew?, selector?, timeoutMs? }.textMatchesalso matches text that was already on the page before the click, so prefertextNewfor verifying a submit: it counts only elements whose text matches and did not match when the batch started. 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: use
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 can be wrong. 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 ýand others) insidedialog,[role=dialog],[role=alertdialog]or[aria-modal=true]count as commits (blockedBy: "modal"). Cookie banners (dialog text mentions cookies) and date or time pickers (the 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()orrequestSubmit(), or fire asubmitevent, and the guard stops it, the result 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 are covered (
제출,신청,등록,결제,送信,確定,提交,Hoàn tấtand others), and다음,次へand下一步are treated likeNext.TURBO_BROWSER_NETWORK_GUARD=truedoes not depend on labels. While submitting is not allowed, non-GET navigations and same-sitefetch/XHRPOST,PUT,PATCHandDELETEare stopped and reported (blockedBy: "network",networkBlocked[]). A blocked navigation gets a204, so 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 environment values. It is off by default because multi-step wizards oftenPOSTon every "Next".
Every blocked result says which mechanism stopped it: blockedBy is label, modal, network or ledger.
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, service-worker requests 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.
An
expect.selectorthat is not a valid selector never matches, so the call reportssubmitVerified: falseafter the timeout.
Restricting navigation
By default the server can open any URL. To limit where the browser may go, set TURBO_BROWSER_ALLOW_HOSTS (or --allow-hosts a.com,b.com; the flag wins over the variable). Each entry matches that host and its subdomains, case-insensitively, and *.example.com means the same as example.com. Spaces and empty entries are ignored. TURBO_BROWSER_ALLOW_ORIGINS (or --allow-origins) takes exact origins such as http://localhost:3000. When both are set, a URL must pass both. With neither set (or only empty entries) nothing changes: no listeners, no request interception and no extra fields in any result.
What is enforced:
Every URL you pass in (
tabs_batchopen,open_manyandnavigate, andnavigatesteps inbatch_actions) is checked before it loads. A denied URL is not requested and that operation fails withhost not allowed: evil.com (TURBO_BROWSER_ALLOW_HOSTS). Inopen_manyonly the denied URL fails.Main-frame navigations that no URL input started (link clicks, form submits, script redirects, server redirects, including every hop of a redirect chain) are stopped when they target a disallowed host. The server uses CDP
Fetchlimited to document requests, so the cost is one round trip per document request. The page stays where it was, and the next result for that tab carries"blocked":"host-not-allowed"once, with the denied address inurl(tabs_batchresults) orblockedUrl(other tools). If that result already has a booleanblockedfrom the submit guard, it getsnavBlockedinstead.about:blank,data:,blob:andchrome-error:are always allowed.file:is blocked while a policy is set, as is any scheme other than http and https.
What is not enforced by default: images, scripts, stylesheets, fetch, XHR, WebSocket and other sub-resources load from any host, and iframes are not restricted. This is a navigation allowlist, not a data-exfiltration barrier. Set TURBO_BROWSER_ALLOW_STRICT=1 (or --allow-strict) to also abort sub-resource and iframe requests to disallowed hosts and to wrap WebSocket, EventSource and navigator.sendBeacon in the page. Strict mode is still best effort: page script can restore the original constructors, a document that was already loaded when the guard attached is not wrapped until its next navigation, WebRTC and requests made by service workers or other workers are not covered, and the first request of a popup can start before the guard attaches.
Scope: the guard is installed only on tabs the server opens or acts on. In CDP mode attached to your own Chrome, other tabs are never touched, but a tab you point a tool at (by tabId, or the active tab) is guarded from that point on. Treat the setting as a guard rail for an agent, not as a security boundary.
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.
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 person 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 TURBO_BROWSER_OBSERVE_AFTERMATH=true) to watch for navigation and mutating fetch/XHR requests after each click: at least 400 ms, longer while the page is still active, at most 800 ms. It is off by default.
The result includes aftermath: { beforeUrl, afterUrl, navigated, mutatingRequests, unexpectedSubmit }. Each request lists its method, URL and a finalSubmit classification. A main-frame origin or path change, or a commit-like request, produces a warning when allowSubmit is false.
This reports an action that has already happened. It cannot prevent a commit or prove that a submission succeeded. Wizard navigation can trigger a warning, and opaque endpoints or requests outside the window can be missed. Use the network guard to prevent and expect to verify. Fixture and classification details are in test/COMMUNITY_FIXTURES.md.
CLI options and environment variables
CLI flag | Environment variable | Default | Description |
|
|
| Connection strategy ( |
|
|
| Chrome DevTools Protocol HTTP endpoint |
|
|
| Persistent profile directory |
| - | auto-detected | Custom Chromium, Chrome, Edge or Brave executable |
|
|
| Default Playwright action and navigation timeout |
|
|
|
|
|
|
| Headless or visible browser window ( |
| - |
| Turn off the default Submit/Publish guard |
|
| unset | Only navigate to these hosts and their subdomains (see Restricting navigation) |
|
| unset | Only navigate to these exact origins; combined with the hosts list when both are set |
|
|
| With an allowlist, also block sub-resource requests to other hosts |
|
| unset | dotenv file of secrets for |
|
|
| Wrap page-sourced text in |
| - | - | Print the bundled |
| - | - | Print Node, Playwright, Chromium and CDP diagnostics as JSON |
|
|
| Start or verify the CDP keep-alive bridge for Chrome 144+ |
| - |
| Launch Chrome with a dedicated profile and |
|
|
| Open the profile in a normal, non-automated Chrome so a person can log in or pass a check first |
- |
|
| Turn on the network commit guard by default |
- |
|
| Comma-separated URL regexes the network guard lets through |
- |
|
| Report navigation and mutating requests after each click (see Click aftermath) |
- |
|
| Submission ledger used by |
| - | - | Print the server version |
| - | - | Print CLI usage |
- |
|
| Root directory for |
- |
| auto-resolved | Explicit path to |
Unattended runs and the Chrome 144+ remote-debugging prompt
In Chrome 136+/144+, enabling chrome://inspect/#remote-debugging on the default User Data directory makes Chrome show an "Allow remote debugging?" prompt each time a new WebSocket client connects. That stops overnight or multi-agent runs. Two ways around it:
--bridge(ornpm run bridge, started automatically when Chrome exposesDevToolsActivePort) starts a background process (src/cdp-bridge.mjs,http://127.0.0.1:9224) that keeps one WebSocket to Chrome open and ignoresBrowser.close. You click Allow once. After that, any number of MCP servers, scripts or subagents can connect and disconnect without another prompt. The bridge keeps a single upstream connection (so the prompt appears once) and gives every connected client its own CDP sessions, so two MCP servers can drive the same Chrome at the same time. Each client sees the same tabs, but its events and one-time page setup are independent.--launch-chrome(ornpm run launch-chrome) starts Chrome with--remote-debugging-port=9222and its own--user-data-dir(~/.turbo-browser-mcp/chrome-profile). That port needs no confirmation dialog, even on the first connection.
Secrets
Set --secrets <file> (or TURBO_BROWSER_SECRETS_FILE) to a dotenv-format file: KEY=value lines, # comments, optional single or double quotes. The server reads the file itself and never logs or returns its values.
In smart_fill_form field values, in act_fast fill and type values, and in batch_actions steps, a value that is exactly $secret:NAME is replaced by the value of NAME at the moment of typing. Anything else is typed as written. An unknown name fails with Unknown secret: NAME before anything is typed. Without a secrets file, $secret:NAME is typed literally and nothing changes.
Every tool result, every error and every file written through savePath has the real value replaced by its placeholder, in raw, JSON-escaped and URL-encoded form. That includes inspect_compact input values, extract_clean_text, evaluate_js results and page_diagnostics. Values shorter than 4 characters are not redacted, because that would damage ordinary output. Limits: a page that rewrites or encodes the value (a mask, base64, a hash) produces text the server cannot match, and screenshots are not redacted. The Submit guard is unchanged.
Content boundaries
Pages can contain text written to look like instructions. With --content-boundaries (or TURBO_BROWSER_CONTENT_BOUNDARIES=1), page-sourced text is wrapped as <<page:3f9a1c>> ... <</page:3f9a1c>>, with a random nonce chosen per server process. This applies to extract_clean_text, inspect_compact (all modes, one pair per result), evaluate_js results, extract and collect steps in batch_actions, and returnSnapshot text. Marker-shaped text inside a page is altered so it cannot close the block early. The server instructions gain one sentence naming the markers. The option is off by default and changes nothing when off. On a typical result the markers add about 21 tokens (measured with tiktoken o200k_base), plus 39 tokens once in the server instructions. collect adds that cost per item.
Skill for Claude Code
The package ships a short Agent Skill, skills/turbo-browser/SKILL.md, that teaches the low-token loop (one inspect_compact, then onlyChanged; whole forms with one smart_fill_form; chained steps; textNew to verify a submit). To install it for Claude Code, copy the file into ~/.claude/skills/turbo-browser/, or run:
mkdir -p ~/.claude/skills/turbo-browser
npx -y turbo-browser-mcp --print-skill > ~/.claude/skills/turbo-browser/SKILL.md--print-skill prints the file that matches the installed version.
Development
npm test # tests in 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 casesCI 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 settle step ends as soon as the page is quiet. A request a script fires later than that (for example a timer of several hundred milliseconds) falls outside the click aftermath window of 400 to 800 ms. A page that keeps mutating the DOM (a spinner or ticker) makes the step run to its 800 ms cap.
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. 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
Available Tools
11 toolsact_fastCDestructive
One action on a ref, selector, text or x/y. Supports returnSnapshot; blocks submit/publish/send unless allowSubmit=true.
Inputs: action (required), x, y, dx, +35 more.
batch_actionsBDestructive
Run actions or smart_fill_form steps in order, including navigate/extract for multi-page reading. Stops on Submit guard blocks; optional post-batch snapshot.
Inputs: steps (required), tabId, expect, allowSubmit, +8 more.
capture_pageCRead-onlyIdempotent
Screenshot (png/jpeg) or PDF of the page or an element, saved under cwd or TURBO_BROWSER_SAVE_ROOT; optional inline image.
Inputs: ref, mode, text, type, +8 more.
evaluate_jsBDestructive
Evaluate JavaScript in a frame or element (ref/selector/text passes el and arg); returns JSON.
Inputs: expression (required), arg, ref, text, +4 more.
extract_clean_textCRead-onlyIdempotent
Extract readable text or markdown from the main content and iframes, capped at maxChars.
Inputs: tabId, format, maxChars, savePath, +2 more.
inspect_compactCRead-onlyIdempotent
List interactive elements (with refs), forms or readable sections across frames and open Shadow DOM, capped at maxChars.
Inputs: mode, boxes, query, tabId, +5 more.
network_sessionC
Manage browser cookies, localStorage/sessionStorage, Playwright storageState files, quick blocking presets (turbo, no-images, no-media, clean), and custom resource/URL blocking.
Inputs: urls, items, tabId, preset, +9 more.
page_diagnosticsC
Read buffered console logs, network requests, downloads and dialogs for a tab.
Inputs: part, clear, level, reqId, +7 more.
smart_fill_formB
Fill several fields at once: inputs, editors, comboboxes, selects, checkboxes, Shadow DOM/iframe fields, file uploads. Stops before Submit by default.
Inputs: main, gmail, tabId, fields, +5 more.
tabs_batchC
Tab operations in one call: list, open/open_many, navigate, activate, resize, emulate, reload, back/forward, close.
Inputs: operations, includeTabs.
wait_for_humanBRead-onlyIdempotent
Let a human do a step (login, bot check, 2FA) in the visible browser; wait until a condition holds, then continue in the same session. Only waits.
Inputs: tabId, message, selector, textGone, +3 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 11 tools
Most tools have clearly distinct purposes: inspection, extraction, diagnostics, capture, storage, and human-wait are well separated. Some overlap exists between act_fast (single action), batch_actions (ordered actions including navigation/extraction), and smart_fill_form (multi-field filling), while navigation also appears inside tabs_batch, but the descriptions generally clarify when to use each.
All names use snake_case, but the conventions are mixed: some are verb_noun (extract_clean_text, capture_page), some noun_noun (page_diagnostics, network_session), and some adjective_verb or noun_verb (smart_fill_form, act_fast, tabs_batch). The names are readable but not a predictable pattern throughout.
Eleven tools is well-scoped for a browser automation server. The set covers tab management, inspection, actions, extraction, diagnostics, capture, storage/network control, and human handoff without excessive fragmentation.
The surface covers the major browser automation lifecycle: tabs, element discovery, form filling, actions, batching, text extraction, JS evaluation, diagnostics, screenshots/PDFs, cookies/storage, and human-in-the-loop waiting. Minor gaps remain for explicit scroll/drag/keyboard primitives, but these may be handled through act_fast or evaluate_js.
Maintenance
Related MCP Connectors
Playwright browser automation — navigate, click, fill forms, extract, screenshot — 17 agent tools.
Control a real browser from AI agents: navigate, click, type, screenshot, read the page.
Stealth web automation for AI agents. Login, signup, navigate, screenshot.
Stealth web automation for AI agents. Login, signup, navigate, screenshot.
Related MCP Servers
- AlicenseNot gradedqualityNot gradedmaintenanceEnables browser automation and web interaction through structured accessibility snapshots using Playwright. Supports clicking, typing, navigation, form filling, and other web actions without requiring screenshots or vision models.10,908,336 npm-
- AlicenseNot gradedqualityDmaintenanceEnables browser automation and web page interaction through Playwright's accessibility tree, allowing LLMs to navigate, fill forms, click elements, and extract content without requiring vision models or screenshots.10,908,336 npmApache 2.0
- FlicenseNot gradedqualityDmaintenanceEnables AI assistants to control web browsers through Playwright automation, providing 50+ tools for navigation, interaction, testing, accessibility audits, and visual testing across Chromium, Firefox, and WebKit.-
- AlicenseNot gradedqualityAmaintenanceEnables AI agents to perform Playwright-compatible browser automation through unchanged upstream tools, using a Chromium runtime with persistent profiles, proxy matching, humanized interactions, and Docker or stdio/Streamable HTTP deployment options.280 npmMIT