@facets-cloud/bx
v0.7.0
Published
Let coding agents drive your running Chromium browser, in the profile you name. An MCP server for Claude, Codex and Cursor.
Readme
@facets-cloud/bx
An MCP server that lets Claude, Codex, Cursor and other MCP clients drive the Chromium browser you already have open, in the profile you name, with your logins. No telemetry.
Platforms: macOS only for now, on Apple Silicon and Intel. Linux and Windows aren't supported yet. bx's lookup of browsers, profiles and processes is Mac-specific, and npm refuses to install the package elsewhere.
Install
Claude Code and Codex:
claude mcp add -s user bx -- npx -y @facets-cloud/bx mcp
codex mcp add bx -- npx -y @facets-cloud/bx mcpClaude Desktop, Cursor and other apps, in their MCP config:
{ "mcpServers": { "bx": { "command": "npx", "args": ["-y", "@facets-cloud/bx", "mcp"] } } }Or run npx -y @facets-cloud/bx mcp install, which adds that entry to
Claude Desktop and Cursor if they are installed.
Use the full name @facets-cloud/bx. The npm package called plain bx is
an unrelated WebdriverIO tool.
First run
Turn on remote debugging in your browser. It is off by default, and bx can't connect until it's on. Open this page in your browser and switch it on:
| Browser | Page | | --- | --- | | Brave |
brave://inspect/#remote-debugging| | Chrome, Chromium, Arc |chrome://inspect/#remote-debugging| | Edge |edge://inspect/#remote-debugging| | Vivaldi |vivaldi://inspect/#remote-debugging|If the page has no remote-debugging switch, update the browser. Older versions don't have it.
On macOS 27 and later, give the app that runs the MCP server Full Disk Access: System Settings > Privacy & Security > Full Disk Access. That's your terminal for Claude Code and Codex, or Claude Desktop or Cursor itself. See Full Disk Access for why.
Restart your MCP app and ask it to run the
doctortool to check.On the first browser action, the browser asks you to Allow the connection. Click it once. It holds until the browser quits.
Rather not do step 1 by hand? Quit the browser and ask the agent to run
the setup tool. It switches the setting on for you (off: true switches
it back off).
Full Disk Access
The browser writes its debugging port to a file in its own data folder, and keeps your profile names there too. bx has to read both. macOS 27 and later block other apps from browser data folders unless you've given them Full Disk Access. Without it, every tool fails with "macOS blocked reading". macOS 26 and earlier don't have this block.
bx only reads two files there: DevToolsActivePort and Local State
(plus writing Local State if you use setup). Full Disk Access is wider
than that, so grant it only if you're comfortable with that app having it.
If you'd rather not, use the launch browser instead: bx owns its folder,
so it needs neither Full Disk Access nor the Allow click. It has its own
logins, separate from your everyday profiles.
If someone clicks "Turn off in settings" on the browser's "being controlled by automated test software" bar, remote debugging goes off and bx can't connect until it's switched on again.
Tools
| Group | Tools |
| --- | --- |
| Setup | doctor, list_browsers, setup, launch |
| Read | list_profiles, list_tabs, snapshot, read, screenshot, eval, wait |
| Act | open, goto, click, hover, drag, fill, type, key, upload, download, pdf, mouse, dialog, close_tab |
| Debug | console, network, storage, change_storage, mock, performance, emulate, cdp |
A typical run: list_profiles, then open a URL in a profile, then
snapshot the tab. The snapshot gives every element a ref like e12,
which click, fill and the other actions take. Each action reports
whether the page navigated, opened a tab or showed a dialog.
The debug tools are DevTools for the agent:
consolelists console messages, uncaught exceptions and failed loads, with the file and line.networklists requests with status and timing. Pass a request id for its headers and request and response bodies.storageshows the page's cookies, localStorage and sessionStorage.performancereports Core Web Vitals (LCP, CLS, FCP, TTFB) with ratings, the long tasks and the scripts behind them, the slowest resources, and heap and DOM size.emulatesets a phone viewport, slow 3G or offline, a slower CPU, a location, or dark mode.cdpsends any other DevTools Protocol command.
So "log in to staging, add an item, check out, and tell me why it fails" ends with the agent reading the failing request's response body and the exception's file and line.
How the one Allow works
Chromium asks you to Allow every new DevTools connection. So the first
tool call starts a small background process that holds one connection,
and every MCP session, from every app, goes through it over a Unix socket
in ~/Library/Application Support/bx/. It stops when the browser quits.
Browsers
Brave and Chrome are tested. Chromium, Edge, Arc and Vivaldi use the same
layout and should work. The server picks the first browser with remote
debugging on. To pin one, pass browser in a tool call, or set it for the
whole server:
"env": { "BX_BROWSER": "chrome" }By default the agent works in background tabs at full speed while you
keep using the browser. Say "show me" and it brings each tab it works in
to the front; say "at human pace" and it slows down. To change the
defaults, run bx config set mode watch or bx config set pace human;
the CLI and every MCP app read the same settings.
To skip the Allow dialog entirely, the launch tool starts a separate
copy of the browser just for agents, with its own profile and logins.
Drive it with browser: "brave-agent" (or chrome-agent, and so on).
Any program on your Mac can connect to that copy, so sign in there only to
what agents need.
Security
The server gives the agent your logged-in browser: it can read any page
and act as you on any site you're signed in to. The server instructions
tell the agent to ask before submitting forms, sending messages, buying or
deleting, but that is the agent's judgment, not a hard limit. Use a
separate profile, or the launch browser, for anything you don't want an
agent to touch.
License
MIT. See LICENSE and THIRD_PARTY_NOTICES.
