BrowserZap
Let the AI agent on your computer use your own Chrome — your tab, your logins — while you watch and stay in control.
Website and docs: https://browserzap.com/docs · Contact: [email protected] · Security: [email protected]
BrowserZap connects an MCP agent (Claude Code, Codex CLI, Cursor, …) to the Chrome you already use. There is no cloud browser, no copied cookies and no new login: the agent works in your real tab, and you can see every step.
- Exact, not approximate. Every click and fill is resolved to exactly one element by its role and name. If two elements match, nothing happens and the agent is told which ones.
- You approve what matters. Submits, payments, deletions, posts and file uploads wait for Approve once in the side panel.
- Your passwords stay yours. The agent never types a password, one-time code or card number. The page asks you to (Your turn → Done), and what you type is never logged.
- Stop at any time. A pill on the page and a switch in the side panel take the tab back at once.
- Comment mode. Click what is wrong on any page, write a note, and send every note to your coding agent at once — with the component, source file and a screenshot of each element.
- Debug with your agent. It reads the page's console errors and failed network requests itself.
- Record once, replay many. Save a task as a workflow and run it again with new values, step by step and checked.
Requirements
- Windows 10 or 11 (macOS and Linux are not supported yet)
- Google Chrome (Microsoft Edge works too)
- Node.js 22 or newer; 24 recommended (https://nodejs.org)
- An MCP client: Claude Code, Codex CLI, Cursor or another
Install
-
Add the extension from the Chrome Web Store: https://chromewebstore.google.com/detail/bbnmhaonicbmljhbahimpgfafbjoijpe. Chrome keeps it updated for you.
-
Install the companion program (the bridge and the MCP server; it needs Node.js 22 or newer):
npm install -g browserzap -
Run setup once:
browserzap setup
browserzap setup does two things, and is safe to run again:
- Registers a small helper with Chrome and Edge for your Windows user only (no administrator rights), so the extension connects by itself and can start the companion program. There is no token to copy.
- Finds Claude Code, Codex CLI and Cursor, shows the exact entry it would add for BrowserZap, and adds it only after
you answer
y.
The npm package ships the bridge, the native helper and the MCP server — not the extension. If the extension is
not installed yet, setup prints the store link.
Click the BrowserZap icon to open the side panel. It turns green when it is connected. Check everything with:
browserzap doctor
Using Claude Code inside WSL? BrowserZap stays on Windows; in WSL run
claude mcp add browserzap -- cmd.exe /c browserzap (details: https://browserzap.com/docs/platforms).
Developers
From a source checkout, npm run build still writes extension/, which you can load with Load unpacked in
chrome://extensions (turn on Developer mode). Run browserzap setup --dev so the helper accepts that build;
setup without --dev goes back to the store extension only. From a checkout without a global install, the same
command is node bridge-server/index.js setup --dev.
Use it
Restart your MCP client and ask for something in the browser, for example: "Open example.com and tell me what the main heading says." If Chrome is closed, the first browser request opens it.
While the agent works, a small cursor shows where it is acting, a pill at the top of the page says the agent is working, and its tabs sit in a labelled BrowserZap tab group that it cleans up when it is done. Press Stop on the pill, or switch control in the side panel, to take over.
Things to try:
- "Search Wikipedia for 'Model Context Protocol' and summarise the first paragraph."
- "In my GitHub notifications, list the unread ones from this week." (uses your existing login)
- "Fill in the contact form on this page with my details, but let me approve before sending."
- "Open my app on localhost:3000, click Save, and tell me why it fails — check the console and the network."
- In the side panel: Comments → Comment on this page, click a few elements, write notes, Send, then tell your agent "Apply my BrowserZap feedback".
Every tool and option: https://browserzap.com/docs/tools.
Troubleshooting
Start with browserzap doctor: every failed line says what to do.
| You see | Do this |
|---|---|
| The side panel stays grey or says Not paired yet | Run browserzap setup, then reload the extension in chrome://extensions |
| Doctor: a bridge with a different pairing secret holds 127.0.0.1:9334 | browserzap restart-bridge, then Reconnect in the side panel |
| Doctor: Launcher finds Node and the helper fails | Node moved (a version switch with fnm, Volta or nvm): run browserzap setup again |
| Doctor: Not blocked by Chrome policy fails | Your computer is managed; ask IT to allow the helper com.browserzap.bridge and the extension |
| Chrome says Disable developer mode extensions on start-up | Only with a developer's unpacked copy: choose Keep. The Chrome Web Store install never shows it |
| A bar says "BrowserZap" started debugging this browser | Expected while an agent can act; it goes away when the agent ends or after a minute idle |
| Your agent does not list BrowserZap's tools | Restart the agent app after browserzap setup. To add it by hand, browserzap --help prints the exact MCP configuration |
| A step stops with "needs you" | The page asked for a password, a code or an approval. Do it, press Done, and the agent continues |
| Anything else | Email [email protected] with the output of browserzap doctor (it contains no passwords or page content) |
More: https://browserzap.com/docs/troubleshooting.
Commands
| Command | What it does |
|---|---|
browserzap setup | One-time setup (above). Safe to run again |
browserzap doctor | Checks the helper registration, the launcher, Chrome policy, the extension id and the connection |
browserzap restart-bridge | Replaces a bridge that will not pair (another install's secret or an old version) |
browserzap run <workflow> --params rows.csv | Runs a saved workflow without an agent (one row on the free plan) |
browserzap uninstall | Removes the helper registration (and a developer's unpacked copy); keeps your data |
browserzap uninstall --purge | Also removes your BrowserZap data folder (cannot be undone) |
Environment variables (allowed sites, profile, upload folder, retention, …): https://browserzap.com/docs/configuration.
Update
npm install -g browserzap@latest
browserzap setup
Chrome updates the extension from the Chrome Web Store by itself. Your workflows, run reports and settings are kept.
If the extension is older than the companion program, the agent's status result says so: Chrome retries on its own, or
open chrome://extensions and press Update.
Free and Pro
Every live browser tool, Comment mode, console and network reading, and every safety control are free; today up to 10 saved workflows are free too. BrowserZap Pro — automation at scale: workflows over many rows, background runs, history and run reports — is coming, as a monthly, yearly or lifetime licence. Any change to plans is announced on https://browserzap.com first. Safety controls are never paid features.
Privacy
BrowserZap runs on your machine. It has no cloud service, no account, no telemetry and no analytics. The bridge
listens only on 127.0.0.1 and accepts only authenticated connections. Form values, passwords and cookies are never
logged; Comment mode screenshots cover password and card fields and stay on your computer. What the agent reads on a
page goes to the AI client you connected, under that client's terms. Full policy: https://browserzap.com/privacy.
Known limitations
- Windows only so far (Chrome or Edge). macOS and Linux are planned.
chrome://pages and the Chrome Web Store cannot be automated.- Canvas apps, some custom widgets and cross-origin frames may need you to do the step.
- In a background tab, clicks are made inside the page; a site that requires a real user click needs the tab in front.
- Risk detection is heuristic. Approvals are there for that reason.
Licence
BrowserZap is proprietary software, free to use on the free plan. See LICENSE. It includes code from
Open Browser Control (MIT); see LICENSE-UPSTREAM and THIRD_PARTY_NOTICES.md.