Field Browser Bridge

Field Browser Bridge lets your own AI agent work in your real Chrome browser through a self-hosted MCP broker. You choose read and control permissions, and final actions require your approval. Page reads filter sensitive browser data before it leaves the browser; cookies, storage, passwords, hidden fields, and existing form values are excluded. Screenshots are different: they can include anything visible, so enable them deliberately.

10-minute local quickstart

You need Node.js 22.12+ and Chrome 116+. Docker Compose is optional. Local setup uses 127.0.0.1 and needs no domain or HTTPS.

npm ci
cd deploy/selfhost
docker compose up -d --build
docker compose exec broker npm run pair-code

No Docker? Run the broker directly with Node. Keep this terminal open; run the other commands in a second terminal with the same three variables exported:

npm ci
export FBB_DATA_DIR="$PWD/.fbb-data" PUBLIC_BASE_URL=http://127.0.0.1:8767 FBB_LISTEN_HOST=127.0.0.1
npm start
# second terminal, same exports:
npm run pair-code
npm run agent-token -- create --id claude-code --cap browser.read,browser.control

Open chrome://extensions, turn on Developer mode, choose Load unpacked, and select this repository's extension/ folder. Open the extension side panel, choose Bridge, and enter http://127.0.0.1:8767/work-edge/ingest as the server address. Paste the single-use pairing code from the last command and click Pair browser. The standard extension build accepts this loopback HTTP URL; no special build flag is needed. Grant site read permission when Chrome asks, and turn on Browser control only if you want the agent to act.

Create a separate scoped key for Claude Code. The command prints the key once; copy it privately:

docker compose exec broker npm run agent-token -- create --id claude-code --cap browser.read,browser.control

In a terminal with Claude Code installed, substitute the printed key for <agent-token>:

claude mcp add --transport http field-browser-bridge http://127.0.0.1:8767/mcp --header 'Authorization: Bearer <agent-token>'
claude mcp list

Ask Claude Code to list available Field Browser Bridge tools or read the current tab. Codex and other HTTP MCP clients can use the same /mcp endpoint with a bearer authorization header; mint a separate key for each agent. Keep agent keys out of shell history and shared configuration when possible. To stop the local service, run docker compose down from deploy/selfhost/ (the state volume remains).

Related MCP server: huashu-chrome

Remote HTTPS for web apps

Claude.ai and ChatGPT require a publicly reachable HTTPS broker URL. Run the same Compose service behind your own HTTPS reverse proxy, set PUBLIC_BASE_URL=https://bridge.example.com in deploy/selfhost/.env, and restart with docker compose up -d. Enter https://bridge.example.com/work-edge/ingest in the extension. The MCP URL is https://bridge.example.com/mcp. Web clients use the broker's OAuth sign-in flow and start with read access; the owner can grant more capabilities. See self-hosting for a Caddy example. Keep the local port private to the host when exposing the proxy.

Safety model

Browser pairing and agent authentication use separate credentials. Each agent key has explicit capabilities and can be revoked. Read access requires Chrome site permission; control requires the browser toggle. The broker blocks ordinary final send, submit, save, delete, purchase, and signing actions. Verified actions bind proposed values and page state to an approval and record a receipt. Page text is filtered before transfer; screenshots may expose visible sensitive content and require the broker policy to allow them. Unauthenticated MCP requests are rejected.

Architecture

Your AI agent --HTTP MCP + scoped token--> Broker on your machine
                                           ^
                                           | authenticated WebSocket
                                           |
Your Chrome <--site permissions + approval-- Extension side panel

The extension connects outward to the broker. The broker routes authorized commands to a paired browser and returns filtered results to the agent. No vendor-hosted broker is configured in this repository.

Testing

npm ci
npm test

The test command validates the extension package and runs the Node test suite. GitHub Actions runs the same commands on Node 22. The source is Apache-2.0 licensed; see LICENSE and NOTICE.