Skip to main content
Glama

turbo-browser-mcp

CI npm Node License

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_form fills a whole form in one call, including React inputs, selects, comboboxes, rich-text editors and file uploads read from disk.

  • inspect_compact can return only the elements that changed since the last snapshot.

  • batch_actions runs 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-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

Related MCP server: Playwright MCP

Tools

Tool

Purpose

Key parameters

tabs_batch

Tab and browser lifecycle

operations[] (list, open, open_many, navigate, activate, resize, emulate, reload, back, forward, close, close_browser), isolatedContext, concurrency (1-10)

inspect_compact

Size-capped snapshot of elements, forms or article text

mode (interactive, forms, article, all), onlyChanged, query, boxes, maxChars, includeFrames, savePath

smart_fill_form

Fill a form, editors and file inputs in one call

fields[] (ref, selector, value, option, values, check, not, keys, file, files, frameIdx, all), gmail, overwrite, stopBeforeSubmit, returnSnapshot

act_fast

One action on the page

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 (urlMatches, textMatches, textNew, selector), submissionKey, allowDuplicate, observeAftermath, returnSnapshot, snapshotMaxChars, snapshotQuery

extract_clean_text

Page text or compact Markdown

format (text, markdown), selector, includeFrames, maxChars, savePath

evaluate_js

JS expression, or a function called with (el, arg)

expression, arg, frameIdx, ref/selector/text, savePath

page_diagnostics

Console, network, downloads and dialogs

level (errors, all), statusFilter (errors, all), includeStatic, urlFilter, reqId, part, dialogPolicy, clear, savePath

capture_page

PNG/JPEG screenshot or PDF

mode (screenshot, pdf), type, quality, fullPage, scale (css, device), ref/selector/text, returnImage, savePath

network_session

Resource blocking, cookies and 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

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
  }
}
{
  "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:9222 and falls back to launching Chromium. cdp attaches to a running browser, persistent reuses a --user-data-dir profile, launch starts 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. isolatedContext gives a tab its own cookies and storage. open_many opens up to 10 URLs at once. emulate sets colorScheme, media, reducedMotion, contrast, forcedColors or a userAgent. 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 as isolatedContext:"other".

  • Snapshots. inspect_compact reads the main frame, child iframes (includeFrames, frameIdx) and open Shadow DOM. With onlyChanged: true a * before a line marks a ref that is new since the last snapshot, and a Removed: 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. query filters by regex or substring, boxes: true adds [box=x,y,w,h], maxChars caps the output, and savePath writes the full output to disk.

  • Forms. smart_fill_form handles text-like inputs, <input type="range">, checkboxes, radio groups, <select> and <select multiple>, ARIA comboboxes and switches, contenteditable editors, and Gmail compose (gmail: { to, subject, body }). Set all: true to fill matching controls across frames. file and files paths go straight to Playwright's setInputFiles, so file contents never enter the model's context.

  • Actions. act_fast takes click, dblclick, hover, focus, clear, fill, type, select, check, uncheck, drag, drop, press, scroll, wait and upload. A target is a ref from the latest snapshot, a CSS selector, visible text, a label, or (x, y) coordinates.

  • Settle step. After a click, double click or key press with returnSnapshot or observeAftermath, the server waits up to 150 ms for a navigation to start, then for domcontentloaded if 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 has outcome: navigated (the URL changed), changed (the DOM changed) or none.

  • Errors. A missing ref lists the 3 nearest current refs with labels. An intercepted click names the covering element. A missing select option lists up to 5 close options. fill reads the value back and adds mismatch when the field holds something else (a mask or maxlength; a password value is not echoed).

  • batch_actions stops when the submit guard blocks a step, unless continueOnError is set.

  • page_diagnostics returns errors only by default. Use level: "all", statusFilter: "all" or includeStatic for more, and reqId with part to read one request.

  • network_session presets are turbo, no-images, no-media and clean (unblock everything), plus custom blockResources and blockUrls. It reads, writes and clears cookies and web storage, and saves or loads a Playwright storageState file.

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

turbo-browser-mcp

Saved

140-button console snapshot (inspect_compact)

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 (onlyChanged)

12,825 chars full ARIA (3,582 tok)

168 chars (56 tok)

98.4% vs ARIA

Article to Markdown (extract_clean_text)

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, all)

1,761 chars (601 tok, errors)

82.6%

10-field form and check (smart_fill_form)

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 file

65,679 chars (44,728 tok) as Base64

263 chars (85 tok) disk path

99.8%

6-step UI flow (batch_actions)

6 turns, 955 tok direct, 3,162 cumulative

1 turn, 406 tok

57.5% direct, 87.2% cumulative

Open 6 tabs (open_many, 60 ms simulated TTFB)

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 turbo preset, 165 ms

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

  1. Submit guard (allowSubmit=false by default). smart_fill_form (with stopBeforeSubmit: true), act_fast and batch_actions check the target element's role and label, Enter in a form, key chords such as Shift+Enter, calls to form.submit() and requestSubmit(), and the same calls made through a same-origin iframe. Final actions that look like Submit, Publish, Send, Post, Apply, Confirm or a payment trigger are blocked unless allowSubmit: true is passed or --allow-submit is 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.

  2. Path confinement (TURBO_BROWSER_SAVE_ROOT). savePath, saveStorageStatePath and loadStorageStatePath work only inside the working directory or TURBO_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.

  1. A click that landed is not a confirmed submission: use expect. After an allowed submit, pass expect: { urlMatches?, textMatches?, textNew?, selector?, timeoutMs? }. textMatches also matches text that was already on the page before the click, so prefer textNew for verifying a submit: it counts only elements whose text matches and did not match when the batch started. The result carries submitVerified and evidence (the new URL, a text snippet such as a receipt number, or the matched selector). If nothing shows up in time you get submitVerified: false and a reason, so the agent does not report "done" on an empty submission list.

  2. A re-run is a second entry, not a retry: use submissionKey. With submissionKey: "portal:2026-11-15:entry-42", every allowed submit is appended to a JSONL ledger (~/.turbo-browser-mcp/submissions.jsonl, or TURBO_BROWSER_LEDGER, or ledgerPath inside the save root). A later call with the same key is refused with blockedBy: "ledger" unless allowDuplicate: true.

  3. 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) inside dialog, [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() or requestSubmit(), or fire a submit event, and the guard stops it, the result says so (submitSuppressed, note) instead of a bare ok: 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ất and others), and 다음, 次へ and 下一步 are treated like Next.

    • TURBO_BROWSER_NETWORK_GUARD=true does not depend on labels. While submitting is not allowed, non-GET navigations and same-site fetch/XHR POST, PUT, PATCH and DELETE are stopped and reported (blockedBy: "network", networkBlocked[]). A blocked navigation gets a 204, so the page and the half-filled form stay put. Let harmless endpoints through with TURBO_BROWSER_NETWORK_GUARD_ALLOW="/autosave$,/analytics". Per call, the undeclared arguments networkGuard, networkGuardAllow and networkGuardSettleMs override the environment values. It is off by default because multi-step wizards often POST on 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-site fetch POSTs are not inspected (cross-site navigations are). Patterns in TURBO_BROWSER_NETWORK_GUARD_ALLOW are 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.selector that is not a valid selector never matches, so the call reports submitVerified: false after 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_batch open, open_many and navigate, and navigate steps in batch_actions) is checked before it loads. A denied URL is not requested and that operation fails with host not allowed: evil.com (TURBO_BROWSER_ALLOW_HOSTS). In open_many only 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 Fetch limited 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 in url (tabs_batch results) or blockedUrl (other tools). If that result already has a boolean blocked from the submit guard, it gets navBlocked instead.

  • about:blank, data:, blob: and chrome-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.

  1. Before the session: turbo-browser-mcp --open-profile --url https://site.example/login opens 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.

  2. During the session: the agent calls wait_for_human with a message and a condition (urlMatches, selector, textMatches or textGone). 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. Keep timeoutMs below 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

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

--executable <path>

-

auto-detected

Custom Chromium, Chrome, Edge or Brave executable

--timeout <ms>

TURBO_BROWSER_TIMEOUT_MS

15000

Default Playwright action and navigation timeout

--tools <all|core>

TURBO_BROWSER_TOOLS

all

core lists only tabs_batch, inspect_compact, smart_fill_form, act_fast, batch_actions, extract_clean_text

--headless / --headed

TURBO_BROWSER_HEADLESS

true (headless)

Headless or visible browser window ("false" for headed)

--allow-submit

-

false

Turn off the default Submit/Publish guard

--allow-hosts <a,b>

TURBO_BROWSER_ALLOW_HOSTS

unset

Only navigate to these hosts and their subdomains (see Restricting navigation)

--allow-origins <o,o>

TURBO_BROWSER_ALLOW_ORIGINS

unset

Only navigate to these exact origins; combined with the hosts list when both are set

--allow-strict

TURBO_BROWSER_ALLOW_STRICT

false

With an allowlist, also block sub-resource requests to other hosts

--secrets <file>

TURBO_BROWSER_SECRETS_FILE

unset

dotenv file of secrets for $secret:NAME placeholders (see Secrets)

--content-boundaries

TURBO_BROWSER_CONTENT_BOUNDARIES

false

Wrap page-sourced text in <<page:nonce>> markers (see Content boundaries)

--print-skill

-

-

Print the bundled SKILL.md for this version

--doctor

-

-

Print Node, Playwright, Chromium and CDP diagnostics as JSON

--bridge

TURBO_BROWSER_BRIDGE_PORT

9224

Start or verify the CDP keep-alive bridge for Chrome 144+ DevToolsActivePort (see below)

--launch-chrome

-

~/.turbo-browser-mcp/chrome-profile

Launch Chrome with a dedicated profile and --remote-debugging-port=9222

--open-profile [--url <u>]

TURBO_BROWSER_OPEN_URL

~/.turbo-browser-mcp/chrome-profile

Open the profile in a normal, non-automated Chrome so a person 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 the server version

--help / -h

-

-

Print CLI usage

-

TURBO_BROWSER_SAVE_ROOT

process.cwd()

Root directory for 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 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:

  1. --bridge (or npm run bridge, started automatically when Chrome exposes DevToolsActivePort) starts a background process (src/cdp-bridge.mjs, http://127.0.0.1:9224) that keeps one WebSocket to Chrome open and ignores Browser.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.

  2. --launch-chrome (or npm run launch-chrome) starts Chrome with --remote-debugging-port=9222 and 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 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_human and 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.md has 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

MIT

Available Tools

11 tools
act_fastC
Destructive

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_actionsB
Destructive

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_pageC
Read-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_jsB
Destructive

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_textC
Read-onlyIdempotent

Extract readable text or markdown from the main content and iframes, capped at maxChars.

Inputs: tabId, format, maxChars, savePath, +2 more.

inspect_compactC
Read-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_humanB
Read-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

    B3.2/5.0

    Scored across 11 tools

    Disambiguation4/5

    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.

    Naming Consistency3/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      Not graded
      maintenance
      Enables 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
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables 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 npm
      Apache 2.0
    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables 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 npm
      MIT