browsertap-mcp

English | 中文文档

Usage guide · Troubleshooting · Security · Contributing · Changelog

A Model Context Protocol (MCP) server that drives the real Chrome you are already using, through a Chrome extension and the Chrome DevTools Protocol. Your agent works inside your existing browser session, so logins, cookies, and open tabs are all already there — no separate sandbox browser to authenticate again.

Current release: unified Python package, bridge, and unpacked Chrome extension 0.4.12.

It also reaches past the page: five direct tools provide real mouse and keyboard input at the OS level when page-level input is not enough. resolve_leave_dialog is one additional, narrowly scoped path that can send Enter after two protocol attempts fail. safe asks before physical input, while the default lab profile runs without elicitation and still enforces the cross-process lock, quiet-input gate, target activation, and on-screen confirmation.

Start in 60 seconds

Three steps. Each one is spelled out in full under Getting started below, with the Windows PowerShell paths and the config for every supported client.

# 1. Install from source. There is no PyPI release yet.
git clone https://github.com/LinVireo/browsertap-mcp.git && cd browsertap-mcp
python -m venv .venv && ./.venv/bin/python -m pip install -e ".[desktop]"
./.venv/bin/browsertap extension-path   # prints the directory step 2 needs

# 3. Point your MCP client at that same executable (Claude Code shown).
claude mcp add browsertap -- "$PWD/.venv/bin/browsertap"

On Windows the same three commands use .\.venv\Scripts\python.exe and .\.venv\Scripts\browsertap.exe.

Step 2 is manual, and it is the slow one. There is no Chrome Web Store listing yet, so the extension is loaded by hand: open chrome://extensions, turn on Developer mode, click Load unpacked, and pick the directory extension-path printed. Then open an ordinary http:// or https:// page -- about:blank runs no content script, so no session is established.

Then ask your agent what tabs do I have open? If the list comes back empty, run browsertap doctor: it names one cause and the one matching advice.

Key features

• Real browser, real session — attaches to your running Chrome/Edge/Opera. Logged-in sites, cookies, and page context are preserved.
• Background by default — a selected tab is not a foreground tab. switch_tab retargets without raising anything, and page work runs in the tab you named while you keep using the screen.
• Page reading — scan any page into simplified HTML or text, sized for a model's context. Long links are shortened to #r1 refs and the real URLs come back alongside, so a results page stays both small and navigable.
• JavaScript execution — run arbitrary JS in the page.
• Background page input — page_click, page_type, page_press, and page_drag dispatch trusted CDP input events at viewport coordinates inside one named tab, without moving your cursor or changing which tab is visible.
• Waiting and scrolling — wait for a selector, text, URL, or JS condition; scroll and re-scan long pages. scan_page reports how much it left outside the viewport instead of dropping it silently.
• Explicit dialog policies — alert, confirm, prompt, and beforeunload each get a per-call dismiss/accept/manual policy and are reported truthfully; handle_dialog resolves one that is left open.
• Temporary site permissions — grant notifications, geolocation, camera, or microphone to one origin for 60–600 seconds; the prior setting is restored automatically.
• Native CDP access — single commands or batches. Addressable by tab, extension id, or target id.
• Authenticated native downloads — download attachments through Chrome's download manager with the active browser profile's cookies, wait for completion, and receive the verified local path.
• Tab-less operation — extension management, CDP target listing, and tab listing/closing go straight to the extension's service worker, so they work even with zero tabs open.
• Page screenshots — page capture via CDP is returned as MCP image content and can also be saved to disk; full desktop capture is available for physical-input checks. A model without image support must use scan_page, page APIs, or OCR to inspect content.
• Guarded real physical input — OS-level mouse move/click/drag, typing, and hotkeys are the last-resort path. lab can run without elicitation; safe prompts per call. Both profiles keep the lock, quiet-input gate, ownership checks, target activation, and on-screen confirmation.
• Multi-browser — Chrome, Edge, and Opera can all connect to one bridge at the same time without clobbering each other's sessions.

Requirements

• Python 3.10+
• Chrome, Edge, or Opera
• Linux, macOS, or Windows. OS-level input on Linux requires an X11 desktop.
• A desktop session, not a container. There is no Docker image on purpose: the server attaches to the Chrome you are signed into, through an extension a human loads once, so an isolated container has no browser to drive.
• Claude Code, or any other MCP client

Getting started

1. Install

Clone the repository, create a virtual environment, and install the recommended desktop feature set:

Windows PowerShell

git clone https://github.com/LinVireo/browsertap-mcp.git
Set-Location browsertap-mcp
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e ".[desktop]"
.\.venv\Scripts\browsertap.exe extension-path

Linux or macOS

git clone https://github.com/LinVireo/browsertap-mcp.git
cd browsertap-mcp
python -m venv .venv
./.venv/bin/python -m pip install -e ".[desktop]"
./.venv/bin/browsertap extension-path

The core install (pip install -e .) omits OS-level mouse/keyboard and desktop capture dependencies. Use it only when those tools are intentionally disabled. After the first PyPI release, pip install "browsertap-mcp[desktop]" will be the non-editable install path; until then, the source install above is the supported path.

2. Load the Chrome extension

This project ships an unpacked extension that has to be loaded once by hand.

browsertap extension-path

Open chrome://extensions, turn on Developer mode, click Load unpacked, and pick the directory that command printed. The loaded extension is listed as BrowserTap Bridge.

If you also use Edge or Opera, repeat the same steps at edge://extensions or opera://extensions with the same directory. The bridge tells the browsers apart automatically.

Then open a normal http:// or https:// page. A blank tab is not enough — content scripts cannot run on about:blank, so no session is established.

Connection status badge

The extension may show a small BTAP: checking, BTAP: connected, or BTAP: disconnected badge on pages. The badge is presentation-only: it reports the bridge connection state and does not display page content, cookies, tokens, or URLs. Open the extension popup and clear Show connection status on pages to hide it. Hiding the badge does not stop the bridge, keepalive, or automatic reconnect behavior.

3. Add the server to your client

Standard config works in most tools:

{
  "mcpServers": {
    "browsertap": {
      "type": "stdio",
      "command": "browsertap"
    }
  }
}

If you installed into a virtualenv, point command at the executable's absolute path instead — relying on PATH is the most common reason a client fails to start the server.

claude mcp add browsertap -- browsertap

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

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

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

Read the full README on GitHub →