BrowserTap MCP

claude mcp add browsertap -- browsertap

Add --scope user to make it available across all projects. For a virtualenv install:

claude mcp add browsertap -- /absolute/path/to/.venv/bin/browsertap

On Windows PowerShell, use the absolute path to .venv\Scripts\browsertap.exe instead.

Verify with /mcp.

Follow the MCP install guide and use the standard config above. An example file is included at examples/claude-desktop-config.json.

Put the standard config in .cursor/mcp.json for one project, or ~/.cursor/mcp.json globally. An example file is included at examples/cursor-mcp.json.

code --add-mcp '{"name":"browsertap-mcp","command":"browsertap"}'

Or write it into .vscode/mcp.json by hand — note that VS Code's key is servers, not mcpServers.

Add to ~/.hermes/config.yaml:

mcp_servers:
  browsertap:
    command: browsertap
    timeout: 120
    connect_timeout: 60

browsertap print-hermes-config prints this snippet. An example file is included at examples/hermes-config.yaml. Verify with hermes mcp list.

Any MCP client that speaks stdio will work. Follow its own install guide and use the standard config above.

• get_setup_status — report package_version, bridge_version, extension_version, protocol_version, connection state, ports, tabs, and the required recovery action. A missing bridge listener is started automatically when spawning is enabled; restart_bridge_required=true means a bridge that is still running must be replaced with browsertap bridge --restart. reload_extension_required=true identifies the unpacked-extension platform limit and requires a manual Reload. restart_mcp_session_required=true is the opposite direction: a component is newer than the running server, so the stale build is this process and only restarting the MCP session or client clears it — the other two flags stay false, because a restart or reload would report the same mismatch again. No parameters.
• get_automation_profile — inspect whether the current MCP process uses lab or safe.
• set_automation_profile — switch the current MCP process between lab|safe; the override is not persisted and does not reload the extension.
  • mode (string): lab or safe
• list_tabs — list connected tabs. Each carries a browser field. No parameters.
• list_all_tabs — (no tab needed) list every open tab, including chrome-extension:// pages that list_tabs hides. Those never become sessions, so they have no session id; drive them with cdp_command(tab_id=...).
  • session_id (string, optional): which browser to ask.
• switch_tab — set the target tab for later calls. A url_pattern must match exactly one tab; if several match, select one with its full session_id. It does not raise the tab or focus the browser: activate defaults to false, so retargeting never disturbs what you are looking at. Pass activate=true, or call activate_tab, when you actually need the tab in front.
  • session_id (string, optional), url_pattern (string, optional): substring match, browser (string, optional): chrome, edge, or opera, activate (boolean, optional): default false.
• activate_tab — bring a tab to the foreground and focus its window. This is the explicit way to raise a tab, and the only one that does not involve approving physical input. Check on_screen in the reply: BTAP first asks Windows to restore a minimised browser, but on_screen=false means visibility still could not be confirmed and screen-coordinate input must not be sent.
  • session_id (string, optional)
• open_url — navigate the current tab. Global behavior remains dismiss; lab automatically accepts beforeunload on configured shell/IDE hosts. If the extension's navigate route is unavailable on a heavy SPA, BTAP falls back to Page.navigate. A CDP result with isDownload=true returns {type:"download",status:"triggered"} instead of only navigation_failed; the accompanying ERR_ABORTED is normal for that download navigation.
  • url (string), session_id (string, optional), timeout (number, optional): default 15, beforeunload (string, optional): default dismiss, intent_leave (boolean, optional): false forces page preservation
• download_file — download an HTTP(S) URL through Chrome's native download manager, using that browser profile's cookies and authenticated session. It waits by default and returns status="completed" plus a verified absolute path; interrupted downloads return failed, while a timeout or wait=false returns in_progress with download_id. An explicit session_id must still be live and is never replaced with another profile. Use this for attachments instead of page fetch.
  • url (string), filename (string, optional): relative download name, directory (string, optional): arbitrary absolute destination directory; creates parents, wait (boolean, optional): default true; directory requires true, timeout (number, optional): default 60 seconds, maximum 1800, session_id (string, optional): selects the browser profile, overwrite (boolean, optional): default false; an existing final destination raises an error unless explicitly true. If a directory download times out, directory_applied=false: the move is no longer tracked and Chrome may finish into its default download directory.
• open_new_tab — open a background tab by default with a unique operation_id and wait a bounded time for exact session/generation registration; pass active=true only when foreground work is genuinely required. Returns {operation_id,tab_id,session_id,generation,ready,owned,opener,owner_id,load_status}. The extension deduplicates repeated requests with the same operation id. Ownership is registered only from a completed record containing the exact client_id+tab_id+generation, even when ready=false; ready only says whether session-scoped tools can be used immediately. A pre-create registry uncertainty returns status="unknown",may_have_created=false,retry_safe=true; after create dispatch, an unresolved ACK/reconciliation returns status="unknown",may_have_created=true,retry_safe=false. Keep its random owner_id capability and use it only for that task's cleanup. For an unresolved dispatched create, do not call open_new_tab again for the same request; retain operation_id as diagnostic/support evidence.
  • url (string), timeout (number, optional): default 15, active (boolean, optional): default false, session_id (optional browser/profile selector), owner_id (optional capability to group several tabs under one task owner)
• close_tabs — (no tab needed) accept native numeric tab ids or full client:tabId session ids, including chrome-extension:// tabs. The default only_if_agent_owned=true requires the owner_id returned by open_new_tab and verifies the current lifecycle generation before closing, so pre-existing user tabs and another agent's tabs are refused. If the user already closed an owned tab, cleanup returns status=already_gone, closed_by=user without reusing its native id. An actual owned close returns closed_by=agent; an explicit unowned/operator override returns closed_by=none so it is not counted as task-owned cleanup. Set only_if_agent_owned=false only when the operator explicitly asked to close an unowned/user tab.
  • tab_id, session_id (optional browser constraint), owner_id (required by the safe default), only_if_agent_owned (boolean, default true)

• scan_page — read the page as simplified HTML or text. Returns links mapping each #rN ref in the content to its absolute URL, and offscreen + hint when content was left outside the viewport.
  • session_id (string, optional), text_only (boolean, optional): default false, cutlist (boolean, optional): default true; collapse repetitive lists, maxchars (integer, optional): default 35000, instruction (string, optional), extra_js (string, optional), timeout (number, optional): default 15
• wait_for — wait until a condition holds, then return. Use this instead of polling scan_page, which re-serializes the whole DOM each time. Polling happens inside the page, so a 30s wait still costs one bridge roundtrip. Exactly one condition is required. selector accepts legacy CSS or the structured locator object described under background page input.
  • selector (string/object, optional): CSS or structured locator, text (string, optional): substring of body text, url_pattern (string, optional): regex on the URL, js (string, optional): expression to become truthy, gone (boolean, optional): wait for the condition to stop holding; default false, timeout (number, optional): default 15, session_id (string, optional)
• wait_for_url — wait for navigation to settle: blocks until the tab URL matches url_pattern (regex, or plain substring — both are tried) and, unless wait_ready=false, document.readyState is complete; then returns final url, title and ready_state. Use after a click or open_url that navigates; wait_for(url_pattern=...) only checks the URL and can return while the new document is still blank. Polls in-page across navigation chunks, so a long wait is still cheap.
  • url_pattern (string): regex or substring to match against the URL, timeout (number, optional): default 15, wait_ready (boolean, optional): require readyState === 'complete', default true, session_id (string, optional)
• scroll_page — scroll and report the new position, so a long page can be read in passes.
  • to (string, optional): default bottom; also accepts top, a pixel offset, or a CSS selector to bring into view, session_id (string, optional), timeout (number, optional): default 15
• execute_js — run JavaScript in the page and return the result. timeout is one end-to-end deadline covering dialog-policy setup, monitor snapshots, delivery/retry, navigation inspection, and cleanup; an explicit session_id is forwarded through every one of those roundtrips instead of relying on the shared default. When a script navigates the page, status is navigated (not success) with landed_url; the script's return value is genuinely lost in that case and is reported as such rather than substituted. dialog_policy decides what happens if the script opens alert/confirm/prompt: dismiss (default) and accept answer it and report it under dialogs, while manual pauses the script with the native dialog still open and returns blocked_by_dialog — call handle_dialog to release it. A tab already holding a manual pause returns busy immediately. Use wait_for/wait_for_url instead of delayed setTimeout or sleep Promises; no_response reports delivery_state and retry_safe, and BTAP never replays an acknowledged script whose side effects may already have run.
  • script (string), session_id (string, optional), no_monitor (boolean, optional): default false, timeout (number, optional): default 15, dialog_policy (string, optional): dismiss (default), accept, or manual
• handle_dialog — inspect or answer a dialog left open on a tab. action="manual" reports it without choosing (blocked_by_dialog, or no_dialog if nothing is open); accept/dismiss answer it and release any paused execute_js or open_url. prompt_text supplies the text for an accepted prompt.
  • action (string), prompt_text (string, optional), session_id (string, optional), timeout (number, optional): default 3, capped at three seconds
• resolve_leave_dialog — for an already-open shell/ttyd/IDE leave prompt: two protocol accepts, then physical Enter only when lab permits it.
  • session_id (string, optional)
• upload_files — set files on a file input, which JavaScript cannot do (input.files is read-only). Runs as one CDP batch so the DOM node ids stay valid across the sequence.
  • selector (string): the <input type=file>, paths (string or array of strings): absolute local paths, session_id (string, optional), timeout (number, optional): default 30
• get_cookies — read cookies for a page.
  • session_id (string, optional), tab_id (integer, optional)
• set_cookies — write cookies into the real browser profile. Takes one cookie object or a list (JSON text is accepted): name is required, plus optional value/url/domain/path/expires (Unix seconds)/httpOnly/secure/sameSite. Uses CDP Network.setCookie, so HttpOnly and cross-path cookies work; falls back to document.cookie only when CDP is unavailable, and then reports which cookies could not carry HttpOnly. Cookies with neither url nor domain are scoped to the current page.
  • cookies (string or list or dict), session_id (string, optional), tab_id (integer, optional), timeout (number, optional): default 20
• delete_cookies — delete a cookie by name. Uses CDP Network.deleteCookies, falling back to expiring it via document.cookie. Scope with domain/path, or url to target one site.
  • name (string), domain (string, optional), path (string, optional), url (string, optional), session_id (string, optional), tab_id (integer, optional), timeout (number, optional): default 20
• storage_get — read localStorage or sessionStorage. Omit key to page with offset/max_items/max_bytes; returns next_offset and truncated. The default timeout is 30s and a failed call does not close the MCP session.
  • key (string, optional), area (string, optional): local (default) or session, session_id (string, optional), timeout (number, optional): default 30, offset (integer, optional), max_items (integer, optional), max_bytes (integer, optional)
• storage_set — write one localStorage/sessionStorage value (non-string values are JSON-encoded first). Verifies by read-back, so a quota-full or privacy-mode failure is reported instead of silently lost.
  • key (string), value (string), area (string, optional): local (default) or session, session_id (string, optional), timeout (number, optional): default 30

Trusted CDP input events delivered to one named tab. They do not activate the tab, focus its window, or move the desktop cursor — every reply carries foreground_changed: false and input_mode: "cdp". All coordinates are viewport CSS pixels (relative to the top-left of the page area, the space getBoundingClientRect reports), never desktop pixels and never the device pixels capture_page_screenshot returns.

Pass session_id explicitly: the call binds the driver to that tab for its duration and restores the shared default afterwards, so a directed call cannot leave another task's target moved. A session_id naming a dead tab is refused rather than redirected to a live one.

selector remains backward-compatible with CSS strings and also accepts a locator object with exactly one primary key: css, role (optional name), text, or label. exact applies to role/name or text matching; frame walks one or more same-origin iframe locators; shadow walks open Shadow DOM hosts. Zero matches return not_found, multiple matches return ambiguous, and cross-origin or closed roots are reported without dispatching input.

• page_click — click a CSS/structured selector or viewport coordinates. Exactly one targeting mode: either selector, or both x and y. With a selector, each omitted offset axis uses the element centre; a supplied offset_x or offset_y is measured from the element's top-left corner on that axis. Missing, ambiguous, non-interactable, cross-origin-frame, and closed-shadow targets return structured status without input dispatch. In selector mode the point is also hit-tested in the page before dispatch: a target below the fold is scrolled into view (scrolled_into_view), one whose pixel belongs to something else returns obscured with occluded_by naming the overlay, and one still off screen returns outside_viewport — in both cases nothing is clicked, because a dispatched click would have landed on the other element and reported success. A verified click carries hit_verified: true. Coordinate mode is not hit-tested: coordinates name a pixel, not an element — and a pixel read off capture_page_screenshot is a device pixel, so it needs dividing by devicePixelRatio first. Challenge replies keep the bounded challenge_detected/attempts/challenge_stalled behavior.
  • selector (string/object, optional), x (number, optional), y (number, optional), offset_x (number, optional), offset_y (number, optional), button (string, optional): default left, clicks (integer, optional): default 1, session_id (string, optional), timeout (number, optional): default 15
• page_type — insert text into a CSS/structured-locator field, or into whatever already has focus when selector is omitted. Xterm.js containers/descendants retarget to .xterm-helper-textarea. Missing, ambiguous, read-only, or otherwise unusable targets return a structured status without dispatching text or keys. clear=true selects the existing value first; submit_key sends one key afterwards.
  • text (string), selector (string/object, optional), clear (boolean, optional): default false, submit_key (string, optional), session_id (string, optional), timeout (number, optional): default 15
• page_press — press a key or a comma-separated modifier chord in the tab, e.g. enter or ctrl,shift,k.
  • keys_csv (string), session_id (string, optional), timeout (number, optional): default 15
• page_drag — drag between two viewport points as one uninterrupted event sequence.
  • x1 (number), y1 (number), x2 (number), y2 (number), duration (number, optional): default 0.3, button (string, optional): default left, session_id (string, optional), timeout (number, optional): default 15

Temporary, origin-scoped permission leases backed by chrome.contentSettings. Every lease records the prior setting and restores it — on expiry, on explicit reset, and after a service-worker restart or browser restart.

• set_site_permission — set one permission for one origin, for 60–600 seconds. Supported: notifications, geolocation (or location), camera, microphone. setting is allow, block, or ask. In safe, every allow requires approval; default lab applies it without elicitation (BROWSERTAP_LAB_NO_ELICIT=1 semantics). Declining returns requires_user_action and changes nothing. clipboard returns unsupported, because its exact prior state cannot be restored. Omit origin to use the target tab's current origin; only http/https origins are accepted.
  • permission (string), setting (string): allow, block, or ask, origin (string, optional): defaults to the tab's origin, duration_seconds (integer, optional): 60–600, default 300, session_id (string, optional)
• reset_site_permissions — restore matching leases now instead of waiting for expiry. Omit both origin and permission to restore every lease on that browser.
  • origin (string, optional), permission (string, optional), session_id (string, optional)

• cdp_command — send one CDP command.
  • method (string): e.g. Page.navigate, params_json (string, optional): JSON object as text, session_id (string, optional), tab_id (integer/string, optional), extension_id (string, optional), target_id (string, optional), timeout (number, optional): default 20
• cdp_batch — send a batch; batch_json must be a JSON object with cmd: "batch".
  • batch_json (string), session_id (string, optional)
• debugger_targets — (no tab needed) list every CDP-attachable target, including service workers and extension background pages that list_tabs never shows.
  • session_id (string, optional)
• save_pdf — bounded Page.printToPDF; validates PDF bytes and atomically writes save_path. A timeout forcibly releases its debugger lease.
  • save_path (string), session_id (string, optional), landscape (boolean, optional): default false, print_background (boolean, optional): default true, prefer_css_page_size (boolean, optional): default true, scale (number, optional): default 1.0, range 0.1–2.0, page_ranges (string, optional), timeout (number, optional): default 30

On driving other extensions: Chrome refuses cross-extension debugging at attach time, and all three addressing forms (tab_id, extension_id, target_id) are rejected alike unless Chrome was started with --silent-debugger-extension-api. These parameters are for this extension's own targets and for diagnosis.

• extension_path — absolute path of the unpacked extension, for manual install. No parameters.
• list_extensions — (no tab needed) installed extensions with id, name, enabled state, type, and version.
  • session_id (string, optional)
• set_extension_enabled — (no tab needed) enable or disable an installed extension. Chrome exposes no API to install one, so this only toggles what is already there.
  • extension_id (string), enabled (boolean), session_id (string, optional)
• uninstall_extension — (no tab needed) uninstall another extension. Confirmation defaults on; set it off only for an explicitly selected disposable/test extension. BTAP cannot uninstall itself through its active response channel.
  • extension_id (string), show_confirm_dialog (boolean, optional): default true, session_id (string, optional)
• get_bookmarks — (no tab needed) read the bookmark tree.
  • session_id (string, optional)
• create_bookmark — (no tab needed) create a bookmark or folder.
  • title (string), url (string, optional): omit to create a folder, parent_id (string, optional), session_id (string, optional)
• remove_bookmark — (no tab needed) remove a bookmark or folder subtree.
  • bookmark_id (string), recursive (boolean, optional): default false, session_id (string, optional)
• call_extension — (no tab needed) send JSON to another enabled extension; the target must allow BTAP via externally_connectable.
  • extension_id (string), message_json (string): JSON payload as text, session_id (string, optional)

• network_capture_start — start collecting bounded request/response records and optional bodies. Defaults: 500-entry ring and 256 KiB per body.
  • session_id (string, optional), include_bodies (boolean, optional): default true, max_entries (integer, optional): default 500, range 10–2000, max_body_bytes (integer, optional): default 262144, range 1024–2097152, body_timeout (number, optional): default 5, range 0.1–10 seconds, timeout (number, optional): default 10
• network_capture_stop — return the current capture and release its debugger lease; always call it in cleanup. Returned records can be filtered without changing capture bounds or cleanup. url_pattern is compiled by the browser as a JavaScript RegExp; invalid patterns return a structured error and leave the capture running for retry.
  • session_id (string, optional), url_pattern (string, optional): JavaScript RegExp, resource_type (string, optional), status_min/status_max (integer, optional): 100–599, include_response_bodies (boolean, optional): default true, timeout (number, optional): default 10
• console_capture_start — start collecting console.* and uncaught exceptions.
  • session_id (string, optional), max_entries (integer, optional): default 500, range 10–5000, timeout (number, optional): default 10
• get_console_messages — page through or clear the current console buffer. filter='user' retains page MAIN/default-context output and excludes isolated extension/content-script contexts; empty/all preserves the complete buffer.
  • session_id (string, optional), offset (integer, optional): default 0, max_items (integer, optional): default 200, clear (boolean, optional): default false, filter (string, optional): user or all, timeout (number, optional): default 10
• console_capture_stop — return the remaining console messages and release its debugger lease.
  • session_id (string, optional), timeout (number, optional): default 10

• capture_page_screenshot — page capture via CDP with viewport, full_page, or explicit clip modes. PNG, JPEG, and WebP are supported; quality is valid only for JPEG/WebP. Returns text metadata plus attached MCP image content; save_path only adds a disk copy. Base64 is omitted unless explicitly requested. The metadata names its own units: image_width/image_height parsed from the returned bytes and pixel_space: "device" (CSS × devicePixelRatio), so a point read off the picture is not fed straight to page_click. A header it cannot parse reports null dimensions plus a dimensions_note rather than a guess — size is the byte count, not a dimension.
  • session_id (string, optional), tab_id (integer, optional), format (string, optional): default png, full_page (boolean, optional): default false, clip (object, optional): x,y,width,height, optional scale, quality (integer, optional): 0–100 for JPEG/WebP, save_path (string, optional), return_base64 (boolean, optional): default false, timeout (number, optional): default 20
• capture_desktop_screenshot — captures the currently visible OS virtual desktop across all displays and returns metadata plus MCP image content. This is not a selected/background-tab capture; it may include other applications. save_path only adds a disk copy. width/height/left/top and the image itself are physical screen pixels (pixel_space: "physical"), unscaled, so they are the same space mouse_click takes.
  • save_path (string, optional), return_base64 (boolean, optional): default false

Real OS-level input at desktop screen coordinates, in physical pixels on the virtual desktop (not CSS pixels, not device pixels). It moves your actual cursor and types into whatever has focus. Prefer the page_* tools: they are precise, do not interrupt you, and work on a background tab. Reach for these only when page input genuinely cannot work — browser chrome, native file pickers, extension popups, OS dialogs.

In safe, each of these five direct tools asks through MCP elicitation. Default lab uses BROWSERTAP_LAB_NO_ELICIT=1 semantics and does not prompt; setting it false restores session-level lab approval. Decline, cancel, or unavailable elicitation returns requires_user_action; every profile still enforces the lock, quiet window, ownership, activation, and foreground check. resolve_leave_dialog is a sixth physical-input path, limited to a final Enter fallback after two protocol-level attempts and subject to the same gate.

After approval the sequence is fixed: take the cross-process lock (contended → busy, returned immediately, never queued), check the coordinates against the real display geometry, wait out a short quiet window (you touched the mouse or keyboard → input_activity_detected, nothing sent), then raise the target tab, then act. What that window can actually detect depends on the OS: only Windows exposes a last-input timestamp, and the pointer position is unavailable under Wayland, in a headless container, and on macOS without the accessibility permission. With no signal at all the window still elapses but has nothing to compare, so every result carries an input_quiet block naming the markers it sampled, with enforced: false when there were none — on such a machine read a pass as unverified rather than as an idle desktop. All five direct tools take session_id — the same one you pass every other tool — and raise that tab; without one they fall back to the shared global target, which another task may have changed. Use activate_session="none" only for intentional input to the already-visible desktop or native UI. If the tab cannot be confirmed on screen the result is activation_failed and no input is sent, so a minimised window produces an error rather than a click into the wrong place.

A point on no display at all is refused with coordinates_off_screen, before the tab is raised and before anything is dispatched: SetCursorPos silently clamps an out-of-range point and reports success, so (2400, 1300) on a 1920×1080 panel becomes a click at (1919, 1079) — the hot corner that can minimise every window — and nothing in the reply would have said so. The rectangle it checks against is the virtual desktop across all displays, reported as screen_bounds on every physical result and by pointer_info. Where the geometry cannot be read the call proceeds with screen_bounds.enforced: false and a note, the same way the quiet gate reports a vacuous pass rather than taking physical input away from a machine where it works.

• mouse_move — x (integer), y (integer), duration (number, optional): glide time in seconds, default 0 (jumps straight to the point), session_id (string, optional): tab to raise, activate_session (string, optional): default current (raise the target tab first), a session id to raise a different tab, or none
• mouse_click — x (integer, optional), y (integer, optional): omit both to click wherever the cursor already is, button (string, optional): default left, also right or middle, clicks (integer, optional): default 1, interval (number, optional): seconds between clicks, default 0.1, session_id (string, optional): the tab to raise, and what you should normally pass, activate_session (string, optional): default current, a session id, or none
• mouse_drag — x1 (integer), y1 (integer), x2 (integer), y2 (integer), duration (number, optional): seconds spent moving with the button held, default 0.3, button (string, optional): default left, session_id (string, optional): tab to raise, activate_session (string, optional): default current, a session id, or none
• type_text — text (string), interval (number, optional): seconds per keystroke, default 0.01, click_x (integer, optional), click_y (integer, optional): click there first to focus the field, session_id (string, optional): the tab to raise, and what you should normally pass, activate_session (string, optional): default current, a session id, or none
• hotkey — keys_csv (string): comma-separated, e.g. ctrl,c, session_id (string, optional): tab to raise, activate_session (string, optional): default current, a session id, or none
• pointer_info — current cursor position, primary-display size, and the screen_bounds rectangle spanning every display (with the probe that answered in source, or null when the geometry cannot be read). Read-only, no approval needed. No parameters.