Local Browser Control MCP

Control Chrome, Helium and Firefox from an MCP client using your existing browser session. The server runs locally. No remote relay, account or debugging port is required.

• Reuse existing windows and keep automation tabs in named groups.

• Read page state, scroll containers and frames; fill forms and verify actions.

• Show a smooth virtual cursor with click pulses. Human input hides it and cancels pending work.

• Mask sensitive screenshot regions locally, by default and without a switch.

• Close unused automation tabs after four hours. Preserve pinned and marked tabs.

• Use an authenticated local WebSocket, or an optional native messaging pipe.

This is an independent project. It does not use or reproduce OpenAI's private extension protocol.

Install

Requires Node.js 22+, Chrome/Helium 120+ or Firefox 139+.

Release package

Download the server .tgz from Releases, then install it:

npm install -g ./browser-control-mcp-0.1.0.tgz
browser-control-mcp --setup

The setup command creates locally paired extension folders, starts the bridge and prints your MCP configuration. Add that configuration to your client, then reconnect it.

Load the extension folder printed by setup:

• Chrome / Helium: open chrome://extensions, enable Developer mode, select Load unpacked, then select the chrome folder.

• Firefox: open about:debugging#/runtime/this-firefox, select Load Temporary Add-on, then select firefox/manifest.json.

The popup shows Connected when the bridge is available. It contains only the connection toggle and idle cleanup timeout.

Firefox releases are unsigned. Temporary installation ends when Firefox closes. Permanent installation in standard Firefox requires Mozilla signing. The Chrome ZIP is for unpacked installation, not a signed Web Store release.

Registry publication is pending. Use the release package above until an npm package name is confirmed.

Using a downloaded extension ZIP

Setup already creates extension folders. If you prefer the separate release ZIP, extract it to a permanent folder and pair it before loading:

browser-control-mcp --pair-extension /path/to/extracted-extension

Public ZIPs contain no pairing secret. After pairing, the local folder contains your secret: do not upload or share that folder.

Build from source

git clone https://github.com/kierandrewett/browser-control-mcp.git
cd browser-control-mcp
yarn install
yarn build
yarn setup

Use the extension paths and MCP configuration printed by setup. Development builds are also available in build/chrome and build/firefox.

After an update, repeat the build and setup commands, reload the extension and reconnect the MCP client.

Related MCP server: chromium-sidecar

Start using it

Ask your client to call browser_list, then browser_tabs. If multiple profiles are connected, use the returned browser ID.

browser_list {}
browser_tabs {"browser":"chrome"}
browser_snapshot {"browser":"chrome","tabId":3}

The server also provides a persistent JavaScript API:

let tab = await cua.createBrowserTab("chrome", "https://example.com", {
    sessionName: "Research",
});
await tab.getAXStateAndScreenshot();

Read browser behaviour and tools, JavaScript API compatibility, and privacy and recovery limits.

Behaviour and safety

There are no per-site approvals, task controls or manual resume buttons. When enabled, the connection can control your browser tabs. Browser-enforced permissions still apply.

Real mouse, keyboard, touch or wheel input cancels pending work and hides the virtual cursor. The agent must read a fresh snapshot before further actions. Disable the connection for private activity such as password-manager login.

Screenshots are always masked locally. Masking is not a guarantee that all sensitive page content is detected. Page text can still contain private information. Screenshots briefly select their target tab, then restore the previous selection.

New tabs normally open in an existing window without changing its selected tab. Named sessions use tab groups. Closing the last task tab removes the group and ends that named session.

Only recorded automation tabs are eligible for four-hour idle cleanup. Pinned tabs and marked handoffs or deliverables are protected. Ordinary tabs are not adopted for cleanup. Unmarked idle forms can close, so mark work you need to keep.

Chrome supports trusted text insertion when its target is active in the focused window. Pointer and key actions use DOM events in both browsers. Sites that require trusted pointer or key events may reject them. Chrome can show a debugger attachment banner.

Actions are not automatically replayed after failure. A lost reply can mean an action already happened. Read current page state and use browser_action_status before retrying a write.

The JavaScript runtime has your local OS permissions. It is not a security sandbox.

Local connection

The bridge listens on 127.0.0.1:18925. It uses a random pairing token, rejects web-page origins, reconnects after connection loss and expires journal metadata after 24 hours. The journal stores no page content, screenshots, action arguments or results.

npm installations store configuration, journal data and generated extensions in ~/.local/share/browser-control-mcp. Source checkouts keep their existing .local directory. Set BROWSER_CONTROL_HOME to use another directory; use the same value for setup and the MCP server.

To diagnose startup, run browser-control-mcp --bridge in a terminal. For a custom port, stop the existing bridge, change port in the data directory's config.json, repeat setup, then reload both the extension and MCP client.

Keep the bridge on loopback. The server and browser must run on the same computer. A remote agent must start the stdio server on that computer, for example through SSH.

Optional native messaging on Linux

From a source checkout, install the native host with your browser's extension ID:

node scripts/install-native.mjs helium YOUR_EXTENSION_ID

Use chrome or chromium for those browsers. For Firefox, use node scripts/install-native.mjs firefox. Chromium-based browsers accept a custom user-data directory as the third argument.

Reload the extension. The popup reports native messaging or local WebSocket transport. The native host uses OS pipes to the browser and still connects to the authenticated local bridge.

Development

yarn check
yarn build
yarn test

Browser tests use temporary profiles and isolated bridge ports. They do not control your normal browsing session. Install Chromium with yarn playwright install chromium. To test Firefox:

GECKODRIVER=/path/to/geckodriver yarn test

Firefox tests expect /usr/bin/firefox. The suite covers forms, shadow roots, frames, screenshots, cursor behaviour, human takeover, idle cleanup and connection recovery.

Create release files

yarn release:extensions
npm pack

The extension command requires zip. It creates fresh, unpaired Chrome and Firefox ZIPs plus SHA256SUMS in releases/v<VERSION>. It refuses to overwrite existing release files. Never ZIP the paired build folders for distribution.

The npm package uses an explicit file allowlist. Local configuration, build folders, browser profiles and test captures are excluded.

After installing a tarball in a temporary directory, test the installed package with:

node scripts/test-installed.mjs /path/to/node_modules/browser-control-mcp

This checks setup, generated extensions, MCP requests and the script runtime using isolated configuration and a temporary bridge port.