# BrowserTap MCP [Health: Active]

**Category:** 📂 Browser Automation  
**Repository:** https://github.com/LinVireo/browsertap-mcp  
**GitHub Stars:** 2  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/browsertap-mcp

## Description
MCP server that drives the real Chrome you already use, through an extension and CDP.

## Tools
Capabilities this server exposes over MCP:

- **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…
- **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.
- **list_tabs** — list connected tabs under `data.tabs`, including their full session handles and `browser` fields. Answers while another tool is still running; `default_session_id` is this request's snapshot of the MCP process default and `default_session_settled=true`. Parallel agents should still pass an explicit…
- **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=...)`.
- **switch_tab** — set this MCP process's *target* tab for later calls. A `url_pattern` must match exactly one tab; if several match, select one with its full `session_id`. A `browser` filter matching multiple profiles also requires an explicit `session_id`. It does **not** raise the tab or focus the browser: `activa…
- **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 no…
- **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",sta…
- **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_…
- **open_new_tab** — open a background tab in this MCP process's selected browser/profile, unless `session_id` or `client_id` selects another. Creates a unique `operation_id` and waits a bounded time for exact session/generation registration; pass `active=true` for foreground work. Returns `{operation_id,tab_id,session…
- **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…
- **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. A background tab may report viewport height zero; ordinary DOM/text/API work still continues there, and only visu…
- **wait_for** — wait until a condition holds, then return. Use this instead of polling `scan_page`, which re-serializes the whole DOM each time. The server schedules short synchronous page checks under one deadline, avoiding background-page timer throttling. Exactly one condition is required. `selector` accepts le…
- **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_…
- **scroll_page** — scroll and report the new position, so a long page can be read in passes.
- **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 process d…
- **get_execute_js_result** — read or briefly wait for an `operation_id`, from the same MCP session that submitted it. Accepts handles from `execute_js` and other timed-out bridge commands. Querying never replays the operation. A completed result can be read repeatedly, including after a lost query response; pending, unknown/ex…
- **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`.
- **resolve_leave_dialog** — for an already-open shell/ttyd/IDE leave prompt: two protocol accepts, then physical Enter only when lab permits it.
- **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.
- **get_cookies** — read cookies for a page.
- **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; fal…
- **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.
- **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.
- **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.
- **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. `{"frame": [...], "x"…
- **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 k…
- **page_press** — press a key or a comma-separated modifier chord in the tab, e.g. `enter` or `ctrl,shift,k`.
- **page_drag** — drag between two viewport points as one uninterrupted event sequence.
- **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` s…
- **reset_site_permissions** — attempt to restore matching leases now, including `manual_recovery` records. Omit both `origin` and `permission` to reset every lease on that browser. Unsupported restoration preserves the prior setting and recovery guidance and stops automatic retries; resolve the cause before another explicit res…
- **cdp_command** — send one CDP command to the selected tab or explicit debuggee. Listed high-risk methods return `raw_cdp_blocked` before dispatch; params must be a JSON object. Other allowed methods can still change page or profile state. See the raw CDP policy above.
- **cdp_batch** — send a batch; `batch_json` must be a JSON object with `cmd: "batch"` and a `commands` array of `cdp`, `tabs`, or `cookies` objects. The whole batch passes the raw CDP policy before its first member runs; nested/unknown commands are rejected.
- **debugger_targets** — *(no tab needed)* list every CDP-attachable target, including service workers and extension background pages that `list_tabs` never shows.
- **save_pdf** — bounded `Page.printToPDF`; validates PDF bytes and atomically writes `save_path`. `save_path` is **relative** and resolves under `~/Downloads/browsertap`; an absolute path or a `..` escape is rejected with `ValueError`. A timeout forcibly releases its debugger lease.
- **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.
- **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.
- **uninstall_extension** — *(no tab needed)* request removal of another extension. Confirmation defaults on; set it off only for an explicitly selected disposable/test extension. Chrome can refuse either setting because a user gesture is required; changing the flag does not supply that gesture. BTAP cannot uninstall itself t…
- **get_bookmarks** — *(no tab needed)* read the bookmark tree.
- **create_bookmark** — *(no tab needed)* create a bookmark or folder.
- **remove_bookmark** — *(no tab needed)* atomically save the target subtree under `bookmark-backups` in the local state directory, then remove the bookmark or folder. Returns `backup_path` and `backup_sha256`; backup failure prevents deletion. The managed backup subdirectory must be an ordinary directory, not a symlink o…
- **call_extension** — *(no tab needed)* send JSON to another enabled extension; the target must allow BTAP via `externally_connectable`.
- **network_capture_start** — start collecting bounded request/response records and optional bodies. Defaults: 500-entry ring and 256 KiB per body.
- **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 runn…
- **console_capture_start** — start collecting `console.*` and uncaught exceptions.
- **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.
- **console_capture_stop** — return the remaining console messages and release its debugger lease.
- **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, and it is **relative** — it resolves under `~/Downloads/brow…
- **inspect_native_file_dialog** — inspect the current foreground Windows standard Shell file dialog owned by a registered Chrome or Edge process. Requires `[desktop]`. Checks owner/process identity, native controls, visibility and Cancel hit targets, then installs a temporary lifetime marker and returns a 15-second ticket. This has…
- **cancel_native_file_dialog** — consume a fresh inspection ticket and send one bounded message to that dialog's Cancel button. Requires `[desktop]` and the current safe/lab physical-approval policy. Rechecks the cross-process lease, observed Windows quiet-input state, held keys/buttons, identity, foreground and hit targets. Retur…

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `uvx` (confidence: high):

```json
"mcpServers": {
  "browsertap-mcp": {
    "command": "uvx",
    "args": ["browsertap-mcp"]
  }
}
```

## Documentation

## What the BrowserTap MCP MCP server does

BrowserTap MCP MCP server exposes browser automation tools through MCP while reusing an open Chromium-based browser profile. It supports Chrome, Edge, and Opera, including existing tabs and logged-in sessions. The server can read page content, follow navigation, interact with controls, execute JavaScript, download files, and inspect or change browser state such as cookies and web storage.

The connection uses a browser extension and a local bridge that communicates with the browser through CDP. This design lets an agent work with a real profile instead of a disposable browser session. It also means the profile may contain authenticated accounts, stored data, extensions, and other user state.

## How it works

An MCP client calls tools against the local server. BrowserTap tracks browser profiles, tabs, session handles, and tab ownership so calls can target a specific tab when several agents or browser windows are active. `list_tabs` reports connected session tabs, while `list_all_tabs` also exposes extension pages that do not become sessions. Calls can select a full session identifier when a URL or browser filter is not unique.

Page operations normally run in the selected tab and can remain in the background. Tools cover CSS or structured-locator clicks, text entry, key presses, dragging, scrolling, JavaScript execution, conditional waits, and URL waits. `execute_js` and other delayed operations can return an operation identifier that `get_execute_js_result` later retrieves without replaying the action.

Browser-level tools handle tab creation and closure, downloads through the browser’s native download manager, cookies, storage, and temporary site permissions. Dialog tools inspect or answer browser dialogs, while `upload_files` handles file inputs that JavaScript cannot set directly. The `lab` and `safe` automation profiles control certain approval behavior; changing the profile applies only to the current MCP process.

## Setup and configuration

The project requires Python 3.10 or newer, Chrome, Edge, or Opera, a running browser user session, the BrowserTap Bridge extension, and an MCP client. Claude Code and Codex can use the documented plugin installation path. Cursor, Claude Desktop, and other MCP clients use the standard MCP installation described by the project.

After starting an agent session, call `get_setup_status` to obtain the extension path and connection details. In the browser’s extensions page, enable Developer mode and choose Load unpacked, then select that directory. Use the corresponding `edge://extensions` or `opera://extensions` page for Edge or Opera. The bridge listener can start automatically when spawning is enabled, but setup status may still require a bridge restart or extension action.

## Tools and capabilities

The BrowserTap MCP MCP server includes tools for:

- Listing, selecting, activating, opening, and closing tabs.
- Reading simplified HTML or text and waiting for selectors, text, URLs, or other page conditions.
- Navigating, scrolling, clicking, typing, pressing keys, dragging, and uploading files.
- Running JavaScript and retrieving delayed operation results.
- Downloading authenticated HTTP(S) files through Chrome’s download manager.
- Reading, setting, and deleting cookies, plus reading and writing local or session storage.
- Inspecting and responding to dialogs and setting temporary notification, location, camera, or microphone permissions.

## Limitations and notes

This automation controls a real browser profile, so shared profile state is not isolated between concurrent tasks. Use explicit tab targets and owner-aware cleanup when managing agent-created tabs. The extension must be installed manually the first time. Background operation does not generally move the desktop cursor, but the project’s lab-only leave-dialog recovery and Windows native file-dialog capabilities have additional desktop requirements. Browser visibility can also differ from tab connection state; `activate_tab` is the explicit operation for bringing a tab and its window to the foreground.

_Full upstream README: https://allmcps.com/mcp/browsertap-mcp/readme_