BrowserBuddy

browserbuddy 0.2.1 — an MCP stdio server plus a cross-browser WebExtension. Requires Node.js 22 or newer.

What it is

BrowserBuddy turns your real browser — Chrome or Firefox — into a space you share with an AI assistant. The assistant is not driving a separate throwaway browser somewhere off to the side — it is in the same window you are, with your logins, your tabs, and your session. It can do things for you, but it can also watch what you do, learn a task by watching you do it once, and work alongside you one step at a time.

Five capabilities:

• Act for you. Navigate, click, fill forms, scroll, zoom, screenshot, download, read page content, evaluate JavaScript.

• Watch you. Your navigation, clicks, typing, scrolling, copy/paste, tab switches and downloads stream to the assistant as a queryable event log.

• Wait for you. browser_wait_for_user blocks until your next action, so the assistant can pause mid-task and let you take over.

• Work in lockstep. The assistant does a step, waits for you to do yours, then continues — a genuine turn-taking loop rather than a one-shot script.

• Learn from you. Record a demonstration, perform the task once yourself, and the assistant keeps a cleaned step list it can replay later against different values.

Related MCP server: Chrome MCP Server

How it compares

Most browser tooling for assistants (chrome-devtools-mcp, Playwright MCP, and anything else built on the Chrome DevTools Protocol) drives a browser through a debug port — usually a fresh profile, always with an automation surface a site can detect: navigator.webdriver, the CDP infobar, an open debugging port. BrowserBuddy is a plain browser extension running in the browser you already use, so it inherits your real sessions and logins, opens no debug port, and sets no automation flags. The larger difference is direction: CDP tools only let an assistant act. BrowserBuddy also lets it see — what you clicked, what you typed, where you went — which is what makes lockstep collaboration and learning from demonstration possible at all.

Setup

The browser starts the server. The extension asks the browser to spawn a native-messaging host — an ordinary local process — and that host is what serves MCP, over a loopback HTTP endpoint it publishes itself. Nothing runs as a daemon, nothing has to be started in the right order, and there is no port to agree on in advance: the host picks one and tells you.

That inverts the usual MCP setup, so read the four steps in order. Host installation is Linux only in this version and refuses other platforms outright rather than writing files where no browser looks.

1. Install the dependencies

npm install

Node.js 22 or newer is required.

2. Install the native-messaging host

browserbuddy install-host --browser chrome     # the whole Chromium family
browserbuddy install-host --browser firefox

This writes the host manifest where that browser looks for it — <user-data-dir>/NativeMessagingHosts/ for Chrome, ~/.mozilla/native-messaging-hosts/ for Firefox — plus the small launcher its path points at. It starts nothing: it only makes the host findable. Add --data-dir <path> to put event logs, demonstrations and the endpoint files somewhere other than server/data; if you do, pass the same --data-dir to client-config in step 4.

3. Load the extension

One extension/ directory serves both browsers; the manifest declares both a service worker (Chrome) and an event page (Firefox), and each browser picks its own.

Chrome:

1. Open chrome://extensions.

2. Turn on Developer mode (top right).

3. Click Load unpacked and select the extension/ directory of this repo.

Firefox (128 or newer):

1. Open about:debugging, choose This Firefox.

2. Click Load Temporary Add-on… and select extension/manifest.json.

3. Grant host permissions: open about:addons → BrowserBuddy → Permissions → enable Access your data for all websites. Firefox treats MV3 host permissions as opt-in, and without this grant the content script cannot run, so page reads, clicks, fills and observation will all fail.

A temporary add-on is removed when Firefox exits; reload it after a restart. Firefox older than 128 refuses to install the extension (strict_min_version — main-world script injection, which browser_eval needs, does not exist before 128).

Loading the extension is what spawns the host. The toolbar badge shows a green ● once the connection is up; a red badge with install instructions means the browser could not find the host, i.e. step 2 was skipped or installed for the wrong profile.

4. Attach Claude Code

browserbuddy client-config

The host published its url and bearer token in server/data/mcp-endpoint.json when the browser spawned it. client-config reads that descriptor and prints the exact registration, ready to paste:

claude mcp add --transport http browserbuddy http://127.0.0.1:PORT/mcp --header "Authorization: Bearer TOKEN"

It also prints the equivalent mcpServers block for MCP clients configured by hand. Pass --apply to run the claude mcp add for you instead of printing it — off by default, because asking where the endpoint is should not rewrite your config. Add --scope user to register it for every project rather than the current one. Restart Claude Code (or run /mcp in a live session) afterwards.

If no host is running, client-config fails with the ordered procedure above rather than printing something that cannot work; the host only exists while the browser is running it.

Register once. The browser tears its background context down routinely, which kills the host and respawns it — but the host persists its identity and comes back on the same port with the same token, so the registration you made keeps working. See Endpoint stability in docs/PROTOCOL.md §1.1.

The CLI's commands:

The WebSocket carrier

Before the native-messaging host, the server was a long-lived process started by the MCP client (claude mcp add browserbuddy -- node …/server/src/index.js serve), with the extension dialling it over a WebSocket on a fixed port. That carrier still works and browserbuddy serve still runs it, but it must now be selected explicitly by setting const TRANSPORT = 'websocket'; in extension/background.js and reloading the extension; WS_URL in the same file is the hardcoded hub address, and serve --port must match it. docs/PROTOCOL.md §1 specifies both carriers.

Tool catalog

25 MCP tools: 18 acting, 3 observing, 4 learning.

Acting

Every tool that takes an optional tabId defaults to the active tab of the last-focused window.

Observing

Learning

Demonstration replay is deliberately agent-mediated: there is no demo_replay tool. The assistant reads the steps with demo_get and re-performs them with the acting tools, substituting new values and adapting to whatever the page actually looks like now.

Ways of working

Do it for me

You describe the outcome; the assistant works alone. "Open my orders page, find the order from last Tuesday, and tell me its tracking number." The assistant uses browser_open_tab, browser_read, browser_click, and reports back. You never touch the keyboard.

Watch and narrate

You drive; the assistant observes. Ask it to follow along, and it polls browser_observe (or blocks on browser_wait_for_user) while you work — noticing which fields you filled, which link you followed, what you copied. Useful for "am I doing this right?", for having it write down what you just did, or for debugging a flow you can reproduce but not describe.

Lockstep

Turn-taking on one task. The assistant fills the parts of a form it knows, then calls browser_wait_for_user and stops. You solve the CAPTCHA, pick the option only you can pick, or approve the payment. Your action wakes the assistant, it reads the new page state, and it continues from there. Anything requiring your judgement or your second factor fits this shape.

Teach by demonstration

1. Ask the assistant to run demo_record_start with a name, e.g. file-expense-report.

2. Perform the task yourself, once, at normal speed.

3. Ask it to run demo_record_stop. Your clicks, typing, key presses, submits, navigations, page loads, tab changes and downloads are reduced to a clean step list — repeated typing in one field collapses to its final value, and a page load that merely echoes a navigation is dropped. Scrolling, copying and pasting are never recorded. Anything redacted is flagged rather than stored.

4. Later: "file an expense report for the 48 EUR taxi on the 3rd." The assistant calls demo_get file-expense-report, reads how you did it, and performs the same steps with the new values — re-finding elements live rather than blindly replaying coordinates.

Privacy and data

A field's value is replaced with [REDACTED] when any of the following hold:

• the input's type is password;

• its autocomplete attribute starts with cc- (credit card fields);

• its name, id or aria-label matches /pass(word)?|card|cvv|cvc|ssn|secret|token|otp|pin\b/i.

This applies uniformly to observed input events, page reads (browser_read in forms mode) and recorded demonstration steps. Redacted values are never transmitted to the hub, never written to disk, and never visible to the assistant — it sees only that a redacted field exists and was filled. A forms-mode read of a redacted field carries an explicit redacted: true flag alongside the [REDACTED] value; unredacted fields carry no flag.

Redaction also covers the ways a sensitive value could leak through a different event:

• Clicks. A click event describes the element by its visible text; when the element has none, the fallback would be its value. For a sensitive element the text is [REDACTED] instead.

• Copy. The preview is [REDACTED] when either the copy target or the focused element is a sensitive field, since the selection lives in the focused field.

• Paste. The preview is [REDACTED] when the field being pasted into is sensitive.

What is stored, and where:

Everything is plain text on your local disk. Nothing is sent anywhere: both carriers bind to 127.0.0.1 only — and the native host's MCP endpoint additionally requires the bearer token from mcp-endpoint.json (mode 0600) and emits no CORS headers, so a web page cannot reach it even if it learned the port. The only data that leaves your machine is whatever the assistant itself reads into your Claude Code conversation — which is exactly the data you asked it to look at. Events flow only while the browser is running the host; with the browser closed, nothing is recorded.

Copy and paste events from ordinary page content keep only a preview of at most 200 characters, not the full clipboard contents.

Limitations

Accepted trade-offs in version 0.2.1:

• Synthetic clicks are isTrusted: false. Extension-generated events are distinguishable from human ones. Most sites do not care; a few hardened ones (some payment and anti-fraud flows) ignore them. Those steps need you — which is what lockstep is for.

• browser_eval is subject to page CSP. A strict Content-Security-Policy can block main-world evaluation. This is reported as a hard error, not silently worked around.

• Screenshots capture the visible tab only. The browser can only capture what is on screen, so browser_screenshot activates the target tab first. Expect your foreground tab to change.

• No browser-internal pages. Content scripts cannot run on chrome:// or about: pages, the Chrome Web Store, addons.mozilla.org, or other extensions' pages, so nothing there can be observed or acted on.

• On the WebSocket carrier, Firefox suspends the background at idle. Firefox does not count WebSocket traffic as background activity, so at idle it suspends the extension's event page and the 30-second alarm revives it — roughly one reconnect per minute, during which acting tools fail with the not-connected error (retry succeeds within ~30 s) and observed events are buffered, not lost. Chrome keeps the socket's service worker alive continuously. This does not reproduce on the default native-messaging carrier: measured on Firefox 148, three minutes of idle left the same host process serving, uninterrupted.

• One browser profile at a time. A single extension connection is accepted; a new hello closes the previous one. This also means Chrome and Firefox cannot be connected simultaneously.

• Host installation is Linux only. browserbuddy install-host refuses macOS and Windows rather than writing the manifest where no browser looks; the layouts are not implemented yet.

• On the WebSocket carrier, port 8590 must be free. browserbuddy serve exits rather than falling back to another port. The native-messaging host has no such constraint: it advertises whatever port it bound, and only a live listener on its remembered port makes it move.

Layout

• extension/ — cross-browser MV3 extension (Chrome and Firefox, one codebase)

  • manifest.json — MV3 manifest: permissions, both background entry points (service worker + event page), Firefox settings

  • background.js — background script (service worker on Chrome, event page on Firefox): transport selection, tab-level observation, RPC dispatch, badge state

  • transport-native.js — the connectNative transport: the browser spawns the native-messaging host and hands the extension a port to it

  • content.js — injected into pages: DOM observation, selector construction, redaction, DOM-level RPC execution

• package.json — the npm package root (browserbuddy); npm install and npm test run from here

• server/ — Node.js process, MCP stdio server and WebSocket hub in one

  • src/index.js — browserbuddy bin entry point

  • src/cli.js — strictcli command definitions (serve, install-host, client-config) and server startup

  • src/client-config.js — the client-config command: turns the host's published endpoint into an MCP client registration

  • src/native-host-bin.js — the executable the browser spawns for the native-messaging carrier

  • data/ — runtime state (gitignored)

    • events/ — JSONL event logs

    • demos/ — recorded demonstrations

    • mcp-endpoint.json — live url + bearer token published by the native-messaging host

    • endpoint-state.json — the token and port the next host respawn reuses, so a configured MCP endpoint keeps working

• docs/

  • ARCHITECTURE.md — components, data flow, and the reasoning behind the design

  • PROTOCOL.md — the complete extension/hub wire protocol

License

Apache-2.0