Setup · Browser Agent Bridge

Prerequisites

Chrome with Developer mode available.
Node.js 18 or later.
An MCP client that supports local stdio servers.

1. Clone and install

git clone https://github.com/rxluz/browser-agent-bridge.git
cd browser-agent-bridge/server
npm ci

2. Generate a bridge token

export BRIDGE_TOKEN="$(node -e "console.log(require('crypto').randomBytes(32).toString('base64url'))")"
npm start

Do not use a memorable phrase. Keep this token private and do not commit it to a config file.

3. Load the extension

Visit chrome://extensions and enable Developer mode.
Select Load unpacked and choose the repository's extension/ folder.
Open the extension popup and provide host 127.0.0.1, port 8765, and the generated token.
Confirm the badge displays on.

4. Configure MCP

{
  "mcpServers": {
    "browser-agent-bridge": {
      "command": "node",
      "args": ["/absolute/path/to/browser-agent-bridge/mcp-server/index.js"],
      "env": {
        "BRIDGE_HOST": "127.0.0.1",
        "BRIDGE_PORT": "8765",
        "BRIDGE_TOKEN": "your-generated-token"
      }
    }
  }
}

Use the configuration file or UI documented by your MCP client. The server uses the standard stdio JSON-RPC transport.

Action reference

Action	Purpose
`snapshot`	Return interactive controls. Prefer `viewportOnly: true`.
`click`	Click by `agentId`, CSS selector, or coordinate.
`type`	Set a regular input, textarea, or contenteditable field.
`insert_text`	Insert trusted text into a focused rich-text editor.
`press`	Send a key or shortcut such as `Enter`, `CTRL+A`, or `META+A`.
`clear`	Select and delete an editable target.
`get_content`	Read title, URL, and visible text.
`wait_for`	Wait for a selector, page text, or JavaScript condition.
`eval`	Run page JavaScript only if the bridge started with `BRIDGE_ENABLE_EVAL=1`.

Troubleshooting

Badge is off: verify the bridge is running, host/port match, and the same token is configured on both sides.
Target not found: take a fresh snapshot; `agentId` values are intentionally scoped to the current page state.
Action fails in a rich editor: focus it with click or a target-aware action, then use insert_text.
eval is denied: this is expected unless you set BRIDGE_ENABLE_EVAL=1.