TypeScript redesign of nodriver: Chrome, Chromium and Edge automation over the Chrome DevTools Protocol (CDP), with no WebDriver and no Runtime.enable, plus a built-in Model Context Protocol server for agents.
If you like nodriver-ts, please give it a ⭐ on GitHub: it helps others find the project and keeps it going.
- Quiet CDP. The library never sends
Runtime.enable,Runtime.addBinding,Console.enableorDebugger.enable, and never falls back to them. It finds the main world through the frame's document andDOM.resolveNode, injects nothing into the page, and leaves Chrome's sandbox and site isolation on. - Frames and shadow DOM. Same-process and out-of-process iframes (OOPIF), nested ones included, each use the right CDP session. Queries pierce open and closed shadow roots.
- Input. Clicks wait until the target is visible, stable and unobscured, and actions are never replayed. An optional seeded
humanpolicy adds pointer paths, key-event typing and wheel scrolling. - MCP for agents. Tools act on stable element refs (
e12) from an indented accessibility snapshot and report what an action caused: navigations, new tabs, dialogs. HTTP leases keep browser state across requests and reconnects. Streamable HTTP, stdio and a local socket share one implementation.
flowchart LR
app["Your code"] --> api["Browser · Context · Tab<br/>Frame · Element · Locator"]
agent["AI agent"] -->|"MCP: HTTP, stdio, socket"| mcp["nodriver-mcp"]
mcp --> api
api --> input["Input layer<br/>queue · checks · cleanup"]
api --> conn["CDP connection<br/>sessions · deadlines"]
input --> conn
conn -->|"WebSocket or pipe"| chrome["Chrome · Chromium · Edge"]
chrome --- pages["Pages, OOPIFs, workers"]
Your code and the MCP server use the same objects. Every command goes through one connection, which routes it to the browser, page or frame session it belongs to, applies the caller's timeout and signal, and names that session in a ProtocolError.
Pages can observe input events, browser settings and network characteristics. See automation traces for the default behavior and available configuration.
- Node.js 24.22.0 or newer.
- A local Chrome, Chromium or Edge. It is found automatically on Windows, macOS and Linux, including on
PATH; otherwise setCHROME_PATHorexecutablePath. - A display for the default headful mode. On servers and in CI, pass
headless: true(--headlessfor the MCP server); on Linux,virtualDisplay: true(--virtual-display) runs headful Chrome on its own Xvfb server instead. On Linux, run as a normal user with Chrome's shared libraries installed: the library never adds--no-sandbox. Headful mode on WSL needs WSLg or another display server.
Supported platforms are listed in docs/support.md.
npm install nodriver-tsimport { Browser } from 'nodriver-ts';
await using browser = await Browser.launch({ headless: true }); // closed at the end of scope
const tab = await browser.newTab('https://example.com');
console.log(await (await tab.waitForSelector('h1')).text());
await tab.screenshot({ path: 'page.png', fullPage: true });- Elements that re-render.
tab.locator('#save')queries again before each action, so a click reaches the current button after a single-page app redraws it. Input that was already sent is never repeated. - Requests in the page.
tab.fetch('/api/me', { responseType: 'json' })runsfetch()with the page's cookies, origin and proxy. A timeout or abort also aborts the request in the page. - Evaluation.
tab.evaluate()runs in the page's main world, or in an isolated world with{ world: 'isolated' }. Functions are serialized into the page. - Frames.
tab.frameslists every frame, OOPIFs included. Queries never cross frames silently. - Contexts and proxies.
browser.newContext({ proxy })isolates cookies and storage, and supports authenticated HTTP(S) and SOCKS upstream proxies. - Network.
tab.network.route()intercepts and fulfils requests,authenticate()answers auth challenges andresponsessubscribes to responses.Network.enableis sent only when you subscribe to responses, callenable()or set headers, cache or offline mode. - Human input.
Browser.launch({ inputPolicy: { mode: 'human' } })applies to every tab and popup, andtab.setInputPolicy()changes one tab. It turns on reproducible pointer paths, key events for US-layout characters and wheel scrolling; other text, such as CJK or emoji, is inserted withinsertText.fill()replaces a value with one insertion,type(text, { replace: true })types over it key by key. See input. - Existing browsers.
Browser.connect({ endpoint })attaches to every tab, or, withattach: 'created', only to the tabs this client opens and their popups.close()then only disconnects. A remote debugging endpoint gives full control of the browser, so restrict access to it. - Handoff. Launched with
detached: trueover WebSocket, Chrome can outlive this process:browser.release()returns an endpoint to reconnect to later. Addsupervised: trueto have a helper end Chrome if the host dies before releasing it. See browser handoff and supervised launch. - Raw sessions.
attach: 'none'discovers targets without creating tabs, andattachSession()returns independent sessions with an explicit lifecycle. See raw sessions. - Diagnostics.
trace(orNODRIVER_TRACE=1) records each command's method, session, duration and error code, never its parameters or results.browser.drain()waits for late replies, and launch failures report their stage and process state. See startup diagnostics. - Tests without Chrome.
nodriver-ts/testingprovidesScriptedChrome, a scripted CDP peer behind real Browser, Tab and Session objects. See testing.
The full reference is docs/api.md; runnable programs are in examples/.
Every click, hover, fill and type is one input action with one deadline. Actions on a connection run one at a time, and a failed action cleans up before the next one starts.
flowchart TD
call["element.click({ timeout, signal, guard })"] --> queue["Wait for the connection's input queue"]
queue --> scroll["Scroll into view<br/>(wheel in human mode)"]
scroll --> check{"Visible, enabled,<br/>stable, unobscured?"}
check -- "not yet" --> check
check -- yes --> move["Move the pointer"]
move --> recheck{"Still at the same point<br/>and not covered?"}
recheck -- no --> refuse["Refuse: no press is sent"]
recheck -- yes --> press["Press and release"]
press --> done["Resolve"]
check -.->|"timeout, abort or guard"| fail["InputActionError<br/>with report and cleanup"]
move -.->|"timeout, abort or guard"| fail
fail --> release["Release held keys and buttons"]
A click is never moved to another point or sent again. setChecked() reads the state, clicks the control or its label, and waits for the new state within the same deadline. A Locator may run an action again on a new element only when the old one was replaced before any press, key or text was sent.
A service that keeps one browser for many tasks can open each task's pages in a scope, clear one site's login without touching another, and prepare the profile before Chrome starts:
import { Browser, updateProfileSettings } from 'nodriver-ts';
await using browser = await Browser.launch({
userDataDir: 'data/browser-profile',
inputPolicy: { mode: 'human' },
// Runs while this process holds the profile lock, before Chrome starts.
prepareProfile: (dir) =>
updateProfileSettings(dir, { preferences: { credentials_enable_service: false } }),
});
{
await using scope = browser.tabScope();
const tab = await scope.newTab('https://platform.example/tasks');
// ... popups the task opens belong to the scope too
} // closes the task's tabs and popups; other tabs stay open
await browser.defaultContext.clearSiteData({
domains: ['platform.example'], // admin.example keeps its login
openTabs: 'blank',
});sequenceDiagram
participant App
participant Scope as TabScope
participant Ctx as BrowserContext
participant Chrome
App->>Scope: newTab(url)
Scope->>Chrome: create page
Chrome-->>Scope: popup opened by the page
Note over Scope: owns tabs, adopted tabs<br/>and their popups
App->>Scope: keep(tab) for a person to finish
App->>Scope: close()
Scope->>Chrome: close owned pages,<br/>including popups still attaching
App->>Ctx: clearSiteData({ domains })
Ctx->>Chrome: delete matching cookies
Ctx->>Chrome: clear storage through a page session
Ctx-->>App: deleted cookies, cleared origins, handled tabs
clearSiteData() refuses by default while a tab still shows the site, or still holds its sessionStorage after navigating away, because the page could keep or write the data back; openTabs: 'close' or 'blank' handles those tabs first. Origins match exactly, port included; cookies match by host. prepareProfile works with temporary and persistent profiles, and updateProfileSettings() merges settings into Local State and Preferences, keeping other keys, and reads them back. That check covers the files, not whether a given browser version honours a setting. A persistent profile serves one browser at a time; see Profiles for what a fixed profile does and does not change about Chrome's Windows password check.
flowchart TD
launch["Browser.launch()"] --> profile{"userDataDir?"}
profile -- no --> temp["Create a temporary profile"]
profile -- yes --> lock["Take the profile lock<br/>and refuse a profile in use"]
temp --> prepare["prepareProfile(dir)"]
lock --> prepare
prepare --> spawn["Start Chrome<br/>(supervised: helper process)"]
spawn --> ready["Connect over CDP<br/>and attach tabs"]
ready --> work["Use the browser"]
work --> close["close()"]
work --> release["release(): Chrome keeps running,<br/>reconnect with its endpoint"]
close --> exit["Confirm Chrome has exited"]
exit --> clean["Remove the temporary profile<br/>and release the lock"]
The package installs the nodriver-mcp command. For a stdio MCP client:
{
"mcpServers": {
"browser": {
"command": "npx",
"args": ["-y", "nodriver-mcp"]
}
}
}As a long-lived local HTTP service:
export NODRIVER_MCP_TOKEN="$(openssl rand -hex 32)" # at least 32 characters
nodriver-mcp --mcp-transport http --port 3100
# clients connect to http://127.0.0.1:3100/mcp with "Authorization: Bearer $NODRIVER_MCP_TOKEN"- Leases. HTTP listens on loopback only. A request without a
Browser-Lease-Idheader uses the token'sdefaultlease. Any other name of letters, digits and. _ -creates a separate lease on first use, so several agents can keep separate browser state. - Protocol versions. The default entry point requires MCP 2026-07-28. With the official TypeScript client 2.3.1, pin
versionNegotiation: { mode: { pin: '2026-07-28' } }. For 2025-11-25 and 2025-06-18 clients, add--mcp-compat; HTTP clients then connect to/mcp/compat. See agent compatibility and Pi. - Browser. Chrome starts with the first
browser_open, using theagentlaunch preset: no first-run or search-engine-choice screens, crash-restore bubble or background throttling, and--password-store=basic, with which Chrome on Linux encrypts saved passwords and cookies with its built-in key instead of the system keyring.
nodriver-mcp --help lists every flag. Commonly used:
--headless,--virtual-display,--user-data-dir,--endpoint http://127.0.0.1:9222,--proxy URL--lang,--window-size 1280x800,--user-agent--input-policy human,--read-only,--disable-tool NAME--upload-dir,--download-dir,--state-dir: each enables the matching file tool, restricted to that directory--state-key-env NAME: encrypts the files of--state-dirwith the passphrase in that environment variable--remote-handoff(HTTP only): lets a user operate a tab through a private viewer link; see remote handoff
The 26 default tools:
- Tabs and navigation:
browser_tabs,browser_open,browser_navigate,browser_history,browser_close_tab,browser_close - Observation:
browser_snapshot,browser_find(CSS, XPath or text),browser_wait,browser_screenshot,browser_network - Actions:
browser_click,browser_click_at,browser_hover,browser_drag,browser_fill,browser_type,browser_press_key,browser_select,browser_check,browser_scroll,browser_dialog - Other:
browser_evaluate,browser_input_policy,browser_environment,browser_handoff(asks the user to finish a step by hand, in the browser window or through a remote viewer link)
browser_upload, browser_downloads and browser_storage_state appear only when their directory flag is set, and browser_handoff_wait only with --remote-handoff.
Actions other than browser_scroll and browser_dialog accept waitFor: "auto" | "load" | "none" and snapshot: true, and return what happened (navigated, newTabs, dialog, tabClosed), so an agent needs no extra round trip after each step. An action that a JavaScript dialog interrupts returns at once with pending: true; answer the dialog with browser_dialog.
See MCP, MCP over HTTP and MCP over socket.
What the defaults do:
- No automatic
Runtime,ConsoleorDebuggerdomain, no bindings and no init scripts in the main world. - Chromium's
AutomationControlledfeature is disabled, sonavigator.webdriveris nativelyfalse. No getter is patched. - Headless mode keeps the native user agent.
maskHeadless: trueremoves HeadlessChrome from the page's UA and UA-CH and from dedicated workers; shared and service workers and their requests can keep native values. See the browser comparison benchmark. - Input brings a tab to the front only when it is not already there, and a held mouse button reports a pressure of 0.5, as a real mouse does. Human mode also sends keyDown/keyUp pairs that match the US layout and starts the pointer at a random point instead of (0, 0).
Fonts, WebGL, canvas, audio and hardware values come from the browser and host. CAPTCHA handling is left to the application. Environment overrides (timezone, locale, UA-CH, viewport, geolocation) are explicit opt-ins; see environment. On Linux, nativeEnvironment sets the timezone and language of the launched process instead; see native launch environment. The browser behavior lists which signals remain observable.
In the repository, Node runs the TypeScript sources directly:
git clone https://github.com/jaykwok/nodriver-ts.git
cd nodriver-ts
npm ci
npm run check # strict type check (src and tests)
npm test # unit tests
npm run test:integration # real Chrome, both CDP transports
npm run test:dist # build, then a smoke test of the package and MCP over HTTP
npm run format:checkSimplified Chinese translations are in docs/zh-CN.
| Document | Contents |
|---|---|
| API | Objects, deadlines, queries, locators, page fetch, tab scopes, storage |
| Input | The human input policy, typing, pointer checks, cancellation |
| Environment | Environment sampling, diagnostics, explicit alignment, WebRTC |
| Native launch environment | Linux process timezone and language, startup check, timezone through a proxy |
| Browser handoff | Detached launch, release and reconnect, CDP event subscriptions |
| Supervised launch | Process supervision, bounded stderr, explicit release |
| Raw sessions | Unmanaged targets, session lifetime, drain, send observation |
| Startup diagnostics | Launch and connect failure stages and process information |
| Browser behavior | Default protocol behavior, execution worlds and observable events |
| Browser comparison benchmark | Native, masked and configured launches, pages and workers |
| MCP | CLI, tools, refs, page JavaScript, embedding |
| MCP over HTTP | Leases, authentication, limits, resources, hand-off |
| MCP over socket | Unix socket / named pipe service and client |
| Agent compatibility | MCP 2025-11-25 / 2025-06-18 clients |
| Support | Platforms, capabilities, limitations |
| Performance · Soak | Benchmark method and baseline, long-running resource test |
| Scripted testing | ScriptedChrome for testing code without launching Chrome |
| Upstream API map | nodriver members and their TypeScript counterparts |
| API test map | Tests that call each public member and MCP tool (generated) |
Changes are recorded in CHANGELOG.md.
Apache-2.0. See LICENSE.