MCP reference

Every MCP tool browserlane exposes to agents over stdio JSON-RPC — generated from bl v0.1.14. 127 tools total. Start the server with bl mcp.

See the CLI ↔ MCP mapping for how the tools relate to the bl CLI — same capabilities, different surface ergonomics (not a 1:1 syntax mirror).

The catalog is curated: tools represent useful user intentions, not one tool per WebDriver BiDi primitive. Engine-level spec coverage is tracked separately in the BiDi parity matrix — a capability without a dedicated tool is not necessarily an engine gap.

Browser

Tool	Description
`browser_quit`	Quit the browser entirely: close EVERY session on this server (not just the current one — including isolated sessions and sessions other agents created) and shut down the browser process. The server itself keeps running; the next browser tool call launches a fresh browser. Idempotent — safe to call when nothing is running. To end only the current session, use browser_stop.
`browser_get_window`	Get the OS browser window dimensions and state
`browser_set_window`	Set the OS browser window size, position, or state

Session

Tool	Description
`browser_start`	Start/activate the current session's browser without navigating (opens about:blank), creating the session if a named one does not yet exist. If the MCP server is configured with a remote WebDriver-BiDi endpoint, this connects to that endpoint instead of launching locally. To navigate to a page, use browser_open; to stop the session, use browser_stop.
`browser_stop`	Stop the current session's run: close its tabs/context and end its trace. The shared browser process and other sessions keep running (an isolated session closes its own dedicated browser). No-op if the session has no active browser. To start or re-run a session, use browser_start; to navigate, use browser_open; to close the browser entirely, use browser_quit.
`browser_session_create`	Create a named browser session with isolated cookies/storage (its own user context). Does not switch to it — use browser_session_use.
`browser_session_use`	Switch this agent's current session: subsequent browser tools run in it unless they pass an explicit session argument.
`browser_session_list`	List active browser sessions with status, tab count, and idle time.
`browser_session_close`	Close a named browser session, its tabs, and its isolated storage.
`browser_session_reset`	Reset a named browser session: fresh storage and a fresh tab under the same name.

Tabs

Tool	Description
`browser_tab_list`	List all open browser tabs with their URLs
`browser_tab_new`	Open a new browser tab, optionally navigating to a URL
`browser_tab_switch`	Switch to a browser tab by index or URL substring
`browser_tab_close`	Close a browser tab by index (default: the active tab)
`browser_context_tree`	Inspect open tabs and their nested frame hierarchy (each top-level tab with its child iframes)

Page

Tool	Description
`browser_open`	Navigate the browser to a URL. `url` is required; a bare host (e.g. example.com) is prefixed with https://. To launch (or connect to) a browser without navigating, use browser_start; to close it, use browser_stop. (The CLI `open` is url-optional and lazy-launches when bare — this agent tool is url-required by design: same capabilities, different surface ergonomics, not a 1:1 syntax mirror.)
`browser_back`	Navigate back in browser history (like clicking the back button)
`browser_forward`	Navigate forward in browser history (like clicking the forward button)
`browser_reload`	Reload the current page. Waits for the page to fully load.
`browser_get_url`	Get the current page URL
`browser_get_title`	Get the current page title
`browser_get_text`	Get the text content of the page or a specific element
`browser_get_html`	Get the HTML content of the page or a specific element
`browser_markdown`	Return a page as agent-readable text (markdown). With a `url`, fetches it over HTTP without the browser (negotiates markdown/plain, retries a .md path, discovers llms.txt, extracts readable text from HTML). WITHOUT a `url`, renders the active tab's live DOM, capturing client-rendered/authenticated state a plain fetch cannot.
`browser_set_content`	Replace the page HTML content
`browser_a11y_tree`	Get the accessibility tree of the current page. Returns a tree of ARIA roles, names, and states — useful for understanding page structure without visual rendering.
`browser_evaluate`	Execute JavaScript in the browser to extract data, query the DOM, or inspect page state. Returns the evaluated result. Use this to get text content, attributes, element data, or any information from the page.
`browser_wait`	Wait for an element to reach a specified state (attached, visible, or hidden)
`browser_wait_for_url`	Wait until the page URL contains a given substring
`browser_wait_for_load`	Wait until the page reaches the "complete" ready state (all resources loaded)
`browser_wait_for_text`	Wait until specific text appears on the page
`browser_wait_for_fn`	Wait until a JavaScript expression returns a truthy value
`browser_console_list`	List buffered browser console messages and page errors (WebDriver BiDi log.entryAdded). Optional filters narrow the result without clearing the buffer.
`browser_console_wait`	Wait for the next matching browser console message or page error (log.entryAdded). Returns immediately if a matching buffered entry already exists; consumes the matched entry.
`browser_console_clear`	Clear the buffered browser console / page-error history for this session

Frames

Tool	Description
`browser_frames`	List all child frames (iframes) on the current page
`browser_frame`	Find a frame by name (exact match) or URL (substring match)

Elements

Tool	Description
`browser_find`	Find an element and return its info (tag, text, bounding box). Use a CSS selector or a semantic locator (role, text, label, placeholder, testid, xpath, alt, title). Combine role with text or other locators to narrow results.
`browser_find_all`	Find all elements matching a CSS selector and return their info (tag, text, bounding box)
`browser_map`	Map interactive page elements with @refs for targeting. Returns a list of interactive elements (buttons, links, inputs, etc.) each with a short @ref like @e1, @e2. Use these refs as selectors in other commands (click, fill, etc.).
`browser_get_attribute`	Get the value of an HTML attribute on an element
`browser_get_value`	Get the current value of an input, textarea, or select element
`browser_count`	Count the number of elements matching a CSS selector
`browser_is_visible`	Check if an element is visible on the page. Returns true/false; an element that does not exist is false. Errors only when the check itself cannot run (invalid selector, lost browser connection).
`browser_is_enabled`	Check if an element is enabled (not disabled). Returns true/false.
`browser_is_checked`	Check if a checkbox or radio button is checked. Returns true/false.
`browser_expect`	Assert a condition about the current page (URL, title, text, element state, count, or a JS expression). Returns a PASS message when the assertion holds; fails with the actual value otherwise. Use this to verify a browser flow reached the expected state.
`browser_click`	Click an element by CSS selector. Waits for element to be visible, stable, and enabled.
`browser_dblclick`	Double-click an element by CSS selector or @ref
`browser_hover`	Hover over an element by CSS selector
`browser_type`	Type text into an element by CSS selector. Waits for element to be visible, stable, enabled, and editable.
`browser_fill`	Clear an input field and type new text. Waits for element to be editable, clears existing value, then types. Use this instead of browser_type when you want to replace the field contents.
`browser_press`	Press a key or key combination on a specific element or the focused element. If selector is given, clicks the element first to focus it, then presses the key.
`browser_keyboard_type`	Type text at the current focus, generating real key events. No selector — acts on the focused element.
`browser_keyboard_inserttext`	Insert text at the current focus WITHOUT synthesizing key events (IME/paste-like). No selector.
`browser_keyboard_down`	Press and hold a key without releasing it (pair with browser_keyboard_up for held-modifier sequences).
`browser_keyboard_up`	Release a held key (pair with browser_keyboard_down).
`browser_select`	Select an option in a <select> element by value
`browser_check`	Check a checkbox or radio button. Idempotent — does nothing if already checked.
`browser_uncheck`	Uncheck a checkbox. Idempotent — does nothing if already unchecked.
`browser_focus`	Focus an element by CSS selector or @ref
`browser_scroll`	Scroll the page or a specific element
`browser_scroll_into_view`	Scroll an element into view, centering it on screen
`browser_mouse_click`	Click at coordinates or at the current mouse position. If x and y are provided, moves the mouse there first.
`browser_mouse_move`	Move the mouse to specific coordinates
`browser_mouse_down`	Press a mouse button down at the current position
`browser_mouse_up`	Release a mouse button at the current position
`browser_drag`	Drag from one element to another
`browser_upload`	Set files on an input[type=file] element
`browser_highlight`	Highlight an element with a red outline for 3 seconds. Useful for visual debugging.

Dialogs

Tool	Description
`browser_dialog_accept`	Accept a dialog (alert, confirm, prompt). Optionally provide text for prompt dialogs.
`browser_dialog_dismiss`	Dismiss a dialog (cancel/close)
`browser_dialog_info`	Show the currently open JS dialog (type, message, defaultValue), or report that no dialog is open
`browser_dialog_wait`	Wait for a JS dialog (alert, confirm, prompt, beforeunload) to open and return its details (type, message, defaultValue). Returns immediately if one is already open. Inspect before accepting/dismissing when the dialog content matters.

Capture

Tool	Description
`browser_screenshot`	Capture a screenshot of the current page
`browser_pdf`	Save the current page as a PDF file
`browser_record_start`	Start a browser recording (screenshots and/or HTML snapshots). Output is Playwright trace viewer compatible.
`browser_record_stop`	Stop recording and save to a Playwright-compatible trace ZIP file
`browser_record_start_group`	Start a named group in the recording (groups nest actions in the trace viewer)
`browser_record_stop_group`	End the current recording group
`browser_record_start_chunk`	Start a new chunk within the current recording (for splitting long recordings)
`browser_record_stop_chunk`	Package the current recording chunk into a ZIP file (recording remains active)
`browser_screencast_start`	Start a native video recording of the page viewport (WebDriver BiDi browsingContext.startScreencast). The browser writes the video to a file it chooses; browser_screencast_stop returns the path. One active screencast per session. Separate from browser_record_start (per-action trace recording). Fails cleanly if the browser does not support native screencast.
`browser_screencast_stop`	Stop a native screencast (WebDriver BiDi browsingContext.stopScreencast) and return the browser-written video file path. Optionally copy the file to outputPath when it is locally readable; the browser-created source file is never deleted.
`browser_diff_map`	Compare current page state vs last map. Shows additions (+) and removals (-) since the last browser_map call.
`browser_diff_snapshot`	Compare the current accessibility snapshot vs the last one. Shows removals (-) and additions (+) since the last browser_a11y_tree or browser_diff_snapshot call; pass baseline to diff against a saved snapshot file instead.
`browser_diff_screenshot`	Compare a current screenshot against a baseline image file, pixel by pixel. Reports match, changed/total pixel counts and mismatch percent; optionally writes a visual diff image.
`browser_diff_url`	Compare two pages: navigates to url1, snapshots, navigates to url2, snapshots, and diffs the accessibility snapshots (optionally screenshots too). The browser is left on url2.

State

Tool	Description
`browser_cookie_list`	List cookies for the current session, optionally filtered by domain. Prints name/value plus domain/path and relevant flags.
`browser_cookie_get`	Print the cookie(s) matching a name, optionally scoped by domain. Lists every matching domain/path variant. Errors when no cookie matches.
`browser_cookie_set`	Set a cookie (name/value, plus optional domain, path, secure, httpOnly, sameSite, expiry). Domain defaults to the current page host.
`browser_cookie_delete`	Delete the cookie(s) matching a name, optionally scoped by domain. A domain-scoped delete never removes a same-named cookie on another domain.
`browser_cookie_clear`	Clear all cookies, or only those matching a domain filter.
`browser_localstorage_list`	List all localStorage keys and values for the active page origin. Requires an http(s) page.
`browser_localstorage_get`	Read a localStorage value by key for the active page origin. Errors when the key is not set.
`browser_localstorage_set`	Set a localStorage key to a value for the active page origin.
`browser_localstorage_delete`	Delete a localStorage key for the active page origin.
`browser_localstorage_clear`	Clear all localStorage for the active page origin.
`browser_sessionstorage_list`	List all sessionStorage keys and values for the active page origin. Requires an http(s) page.
`browser_sessionstorage_get`	Read a sessionStorage value by key for the active page origin. Errors when the key is not set.
`browser_sessionstorage_set`	Set a sessionStorage key to a value for the active page origin.
`browser_sessionstorage_delete`	Delete a sessionStorage key for the active page origin.
`browser_sessionstorage_clear`	Clear all sessionStorage for the active page origin.
`browser_storage_save`	Save the current session's cookies, localStorage, and sessionStorage as a named snapshot. Only the active page's origin is captured for web storage; cookies span the whole session.
`browser_storage_load`	Restore a named storage snapshot into the current session (cookies + per-origin localStorage/sessionStorage). Reports any origin-level restore failures.
`browser_storage_list`	List saved storage snapshots with redacted metadata (counts only, no values). Local registry operation — no browser required.
`browser_storage_show`	Show a saved snapshot's metadata and counts. Never prints raw cookie or storage values. Local registry operation — no browser required.
`browser_storage_delete`	Delete a saved storage snapshot. Local registry operation — no browser required.
`browser_storage_export`	Export a saved snapshot's canonical JSON to a file path. Local registry operation — no browser required.
`browser_storage_import`	Import a canonical storage JSON file into the registry under a name. Validates the JSON, rewrites the name, and updates timestamps. Local registry operation — no browser required.
`browser_download_set_dir`	Set the download directory for the browser
`browser_wait_download`	Wait for the next download to finish and return its status, URL, and filepath when available

Emulation

Tool	Description
`browser_get_viewport`	Get the current viewport dimensions
`browser_set_viewport`	Set the browser viewport size. Use browser_reset_viewport to clear the override.
`browser_reset_viewport`	Reset the viewport size and device pixel ratio overrides for the current page/context, returning control of viewport sizing to the browser (WebDriver BiDi browsingContext.setViewport with viewport: null and devicePixelRatio: null).
`browser_emulate_environment`	Emulate the browsing environment for this session: locale, timezone, user agent, offline network, disabled scripting. Overrides are scoped to the session's user context (new tabs inherit them; other sessions are unaffected) and persist until cleared. At least one setting is required. Note: page_clock_set_timezone sets a per-tab timezone that wins over this session-wide one in that tab.
`browser_emulate_media`	Override CSS media features (color scheme, reduced motion, etc.)
`browser_set_geolocation`	Override the browser geolocation
`page_clock_install`	Install a fake clock on the page, overriding Date, setTimeout, setInterval, requestAnimationFrame, and performance.now
`page_clock_fast_forward`	Jump the fake clock forward by N milliseconds, firing each due timer at most once
`page_clock_run_for`	Advance the fake clock by N milliseconds, firing all time-related callbacks systematically
`page_clock_pause_at`	Jump the fake clock to a specific time and pause — no timers fire until resumed or advanced
`page_clock_resume`	Resume real-time progression from the current fake clock time
`page_clock_set_fixed_time`	Freeze Date.now() at a specific value permanently. Timers still run.
`page_clock_set_system_time`	Set Date.now() to a specific value without triggering any timers
`page_clock_set_timezone`	Override the browser timezone. Pass an IANA timezone ID (e.g. 'America/New_York'), or empty string to reset to system default

Utilities

Tool	Description
`browser_sleep`	Pause execution for a specified number of milliseconds. Use sparingly — prefer browser_wait or browser_wait_for_url when possible.

On this page