BrowserTap MCP

Bring a tab to the foreground and focus its window. Use this explicitly after switch_tab when foreground work is required, or to re-raise a tab the user has since clicked away from.

Send a JSON message from the BTAP extension service worker to another installed extension. The target must be enabled and list this BTAP extension in externally_connectable. Works with no tabs open.

Capture the complete visible virtual desktop across all displays and return text metadata plus MCP image content; this is not a background-tab screenshot, save_path only adds a disk copy, and return_base64 is opt-in. width/height/left/top are PHYSICAL screen pixels and are exactly the range mouse_click accepts, unscaled.

Capture a viewport, full-page, or clipped screenshot of a page/tab via CDP with optional JPEG/WebP quality. Returns text metadata plus an attached MCP image even when save_path is set; save_path only controls disk output. image_width/image_height are DEVICE pixels (CSS x devicePixelRatio), not the CSS pixels page_click takes, and `size` is the byte count. If the current model cannot consume images, it has not seen the pixels and must use scan_page, execute_js, a page-specific API, or OCR instead. Base64 is included only when return_base64=true.

Run a CDP bridge batch command; pass the full JSON command object as text.

Call one Chrome DevTools Protocol command. session_id accepts client:tabId; tab_id accepts either a native number or the same composite session string.

Close one or more tabs by native tab id or composite session_id. Accepts a single identifier or a list; identifiers in one call must belong to the same browser. By default it closes only tabs created by this MCP task and requires the owner_id returned by open_new_tab; lifecycle generations are checked before removal. Set only_if_agent_owned=false only for an explicit operator request to close a user tab.

Start a bounded Runtime console and exception capture on a real-browser tab without foregrounding it. Use get_console_messages while running and console_capture_stop when done.

Stop console capture on a real-browser tab, return the remaining bounded message buffer, and release its debugger lease.

Create a bookmark or folder. Supply url for a bookmark; omit url to create a folder. parent_id is optional and uses Chrome's default bookmark location when omitted.

List every CDP-attachable target, including service workers and extension background pages that list_tabs never shows. Works with no tabs open.

Delete a cookie by name from the real browser profile. Scope defaults to the current page (url), or pass domain/path/url to target another scope. Uses CDP Network.deleteCookies, falling back to expiring it via document.cookie.

Download an http(s) URL through the real browser's native download manager, so the current browser profile's cookies and authenticated session are used. Waits for completion by default and returns the final absolute local path. directory may be any absolute local directory; completed files are moved there without replacing an existing file unless overwrite=true. A directory timeout reports directory_applied=false because Chrome may finish in its default download directory. An explicit session_id must still be live and is never replaced with another profile. Use this for attachments instead of page fetch.

Execute arbitrary JS in the requested real-browser tab under one total deadline. BTAP pins every monitor/retry/result roundtrip to an explicit session, uses the service-worker/page route first, and falls back to directed Runtime.evaluate on SPA/CSP bridge failures without retargeting. Use wait_for/wait_for_url instead of setTimeout or sleep Promises; BTAP retries only proven-undelivered work, never an acknowledged script whose side effects may already have run.

Get absolute path to the unpacked Chrome extension directory for manual installation.

Return the active safe/lab automation profile. Lab is the default and skips elicitation unless BROWSERTAP_LAB_NO_ELICIT is explicitly disabled; safe requires approval for every physical action and permission allow.

Return the browser bookmark tree. Works with no tabs open.

Read a page of captured console messages and exceptions from a real-browser tab. Set clear=true to clear the full buffer after reading. Set filter='user' to exclude extension service-worker / content-script logs and keep only the page's own main-world console output.

Get cookies for the current page or specified tab via the Chrome extension bridge.

Return component versions, stale-build actions, extension path, bridge ports, and connection status for setup/diagnostics.

Inspect or handle a JavaScript dialog on the requested real-browser tab. action is dismiss, accept, or manual; manual reports the dialog without choosing.

Send a hotkey chord like 'command,l' or 'ctrl,shift,p' via the real keyboard. Safe mode requires one-action approval; lab skips prompting by default and uses session approval only when BROWSERTAP_LAB_NO_ELICIT is explicitly disabled. By default BTAP foregrounds and verifies the selected browser tab after the quiet-input check; prefer an explicit session_id for browser input. activate_session='none' is only for intentional input to the already-visible desktop or native UI.

List every open tab, including chrome-extension:// pages that list_tabs hides. Those never become sessions (content scripts can't run there), so they have no session id — drive them with cdp_command(tab_id=...) instead. Works with no tabs open.

List installed browser extensions (id, name, enabled, type, version). Works with no tabs open.

List connected tabs across all connected browsers; each tab has a browser field (chrome/edge/opera) and a session id to pass verbatim.

Click on the real desktop at absolute virtual-desktop coordinates in PHYSICAL screen pixels — the space pointer_info and capture_desktop_screenshot report, NOT the viewport CSS pixels page_click takes; on a scaled display the two differ by devicePixelRatio. A point on no display is refused with coordinates_off_screen rather than clamped to a screen edge. Pass session_id — the same one you pass every other tool (preferred) — and that tab is raised after the quiet check so the click lands on it. Without one the current global target is raised, which another task may have changed. Approval may foreground the selected browser tab. activate_session='none' clicks the desktop as-is.

Drag the real mouse from one point to another, both in absolute virtual-desktop PHYSICAL screen pixels (see mouse_click for how that differs from page_drag's CSS pixels). Either endpoint on no display is refused with coordinates_off_screen. Safe mode requires one-action approval; lab skips prompting by default and uses session approval only when BROWSERTAP_LAB_NO_ELICIT is explicitly disabled. By default BTAP foregrounds and verifies the selected browser tab after the quiet-input check; prefer an explicit session_id for browser input. activate_session='none' is only for intentional input to the already-visible desktop or native UI.

Move the real mouse cursor to absolute virtual-desktop coordinates in PHYSICAL screen pixels (the space pointer_info and capture_desktop_screenshot report, not the CSS pixels page_click takes). A point on no display is refused with coordinates_off_screen rather than clamped to a screen edge. Safe mode requires one-action approval; lab skips prompting by default and uses session approval only when BROWSERTAP_LAB_NO_ELICIT is explicitly disabled. By default BTAP foregrounds and verifies the selected browser tab after the quiet-input check; prefer an explicit session_id for browser input. activate_session='none' is only for intentional input to the already-visible desktop or native UI.

Start bounded CDP Network capture on a real-browser tab. Captures requests, responses, and optionally response bodies without foregrounding the tab. Call network_capture_stop to return the buffer and release the debugger lease.

Stop Network capture on a real-browser tab, optionally filter returned records by URL, resource type, HTTP status range, or response-body inclusion, and release its debugger lease. url_pattern uses the browser's JavaScript RegExp syntax and invalid patterns return a structured error.

Open one real-browser tab in the background by default with an operation_id-backed exactly-once create. Pass active=true only when foreground work is genuinely required. If the create ACK is lost, the same operation_id is reconciled within one total deadline; a completed result is registered only with its exact client_id, tab_id, and generation. Before create is dispatched, an unresolved probe returns status=unknown, may_have_created=false, retry_safe=true; after dispatch, an unresolved operation returns status=unknown, may_have_created=true, retry_safe=false and the operation_id. Never use a URL-based guess or an unmarked create retry.

Navigate the current real-browser tab through CDP without raising its window. beforeunload defaults to dismiss, except lab mode auto-accepts configured shell/IDE hosts. Use accept to leave explicitly, manual to inspect, or intent_leave=false to force the conservative dismiss behavior even on a lab auto host.

Click a CSS/structured locator or viewport coordinates in a specific real browser tab using background CDP input. Coordinates are viewport-relative CSS pixels (the space getBoundingClientRect reports), NOT the physical screen pixels mouse_click takes and NOT the device pixels capture_page_screenshot returns -- on a scaled display divide a screenshot pixel by devicePixelRatio first. Ambiguous or unreachable targets dispatch nothing; the tab is not activated and the desktop cursor does not move. Selector offsets are measured from the element's top-left corner; an omitted axis uses the element centre. In selector mode the point is hit-tested before anything is dispatched: an element below the fold is scrolled into view, and a point owned by another element returns status 'obscured' (with occluded_by) or 'outside_viewport' having clicked nothing. Coordinate mode is not hit-tested -- coordinates name a pixel, not an element.

Drag between viewport coordinates in a specific tab using one background CDP input sequence, without activating the tab or moving the desktop cursor. Both endpoints are viewport-relative CSS pixels, like page_click's coordinate mode and unlike mouse_drag's physical screen pixels, and neither is hit-tested.

Press a key or comma-delimited modifier chord in a specific tab using background CDP input, without activating the tab.

Insert text into the focused element or a CSS/structured-locator field in a specific tab using background CDP input; xterm containers automatically retarget their helper textarea. Optionally clear and submit a key. Missing, ambiguous, or unusable targets dispatch nothing.

Report the current desktop mouse position and screen geometry in PHYSICAL pixels. screen_width/screen_height are the PRIMARY display only; screen_bounds is the virtual desktop across every display and is the range mouse_click will accept. These are not the CSS pixels the page_* tools take.

Remove a bookmark by id. Set recursive=true only for a folder whose full subtree should be removed.

Restore matching temporary site-permission leases now. Omit origin and permission to reset every lease for the selected browser; origin accepts only http/https.

Resolve an intended beforeunload leave in one bounded workflow: protocol accept twice, return immediately when no dialog exists, then use a lab-only foreground Enter fallback after the normal physical-input approval gate only when protocol handling actually fails.

Print a real-browser tab to a validated PDF file through bounded CDP. The file is written atomically only after valid non-empty PDF bytes are returned; a CDP timeout invalidates and detaches the debugger lease.

Read the current page as simplified HTML/text, preserving login state from the real browser. Defaults: cutlist=true, maxchars=35000, timeout=15 seconds.

Scroll the page and report the new position. scan_page omits anything past ±5000px from the current scroll offset, so on a long page: scan, then scroll, then scan again. Pass to='bottom'/'top', a pixel offset, or a CSS selector to bring into view. Defaults: to='bottom', timeout=15 seconds.

Set the safe or lab automation profile for this MCP process. This does not persist or reload the extension; BROWSERTAP_MODE controls the next process.

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 if CDP is unavailable, and then says which cookies could not carry HttpOnly. Cookies with neither url nor domain are scoped to the current page.

Enable or disable an installed extension by id. Chrome exposes no API to INSTALL an extension, so this only toggles ones already present; use list_extensions for ids. The BTAP bridge refuses to disable itself -- nothing would be left to re-enable it -- so ask a human to press Reload on chrome://extensions to pick up a new build.

Temporarily set an origin-scoped browser site permission for 60-600 seconds. Only http/https origins and notifications, geolocation/location, camera, microphone, or clipboard are supported. safe asks on every allow; lab skips prompts by default and restores session approval only when BROWSERTAP_LAB_NO_ELICIT is explicitly disabled. All leases restore their prior setting.

Read localStorage or sessionStorage. Give a key for one value, or omit it to dump every key (values are truncated past ~20k chars and truncated is reported). area='local' (default) or 'session'.

Write one key into localStorage or sessionStorage and read it back to confirm. area='local' (default) or 'session'. Values are strings; non-string values are JSON-encoded first.

Set the target tab for later calls by session id, URL substring, or browser name ('chrome'/'edge'/'opera') without focusing the browser. A URL substring must match exactly one tab; pass its full session_id when several tabs match. Use activate=true or activate_tab when foreground work is required.