OpenBrowser

Browser automation for AI agents — in your real Chrome, with your real logins.

A Chrome extension plus a zero-dependency MCP server, so any MCP client can drive an actual browser instead of a headless copy of one.

🌐 openbrowser.pulse-core.com

Install · Quickstart · Tools · Token cost · Difficult sites · Security · Contributing

What it is

OpenBrowser lets an AI agent drive your Chrome — the one already signed in to your accounts, running your extensions — over the Model Context Protocol. It has two halves: a Manifest V3 Chrome extension with a side-panel UI, and a small MCP stdio server that any MCP client (Claude Code, opencode, Cursor, Windsurf, Zed, or your own) can launch.

Most browser automation hands the agent a fresh headless browser instead: signed out of everything, fingerprinted as a bot, and reading pages as either raw DOM or screenshots. OpenBrowser takes the opposite position on all three — real session, trusted input, and a compact accessibility tree that keeps token cost low.

Related MCP server: Chrome MCP Server

Highlights

• 🔓 Real browser, real session. Runs in your actual Chrome, with your logins, cookies, and extensions. Nothing extra to keep signed in.

• ⌨️ Trusted input events. Clicks and keystrokes go through the Chrome debugger, so they are indistinguishable from a real user's. Payment forms, login pages, and drag-and-drop all work where synthetic clicks are rejected.

• 🪶 Built for token cost. Pages are read as a compact accessibility tree, not screenshots or raw DOM. A full login page costs ~350 characters.

• ⚡ Parallel by default. Every tool takes a tabId. Read twenty tabs at once.

• 🧩 Fourteen composable tools. Grouped by action enums rather than split into forty single-purpose ones — models pick an enum value far more reliably.

• 🖥️ Side-panel UI. Run any tool by hand and see exactly what an agent would get back — the fastest way to debug a flow.

• 🌐 Multi-browser and multi-machine. Several agents share one browser; one hub can federate to hubs on other machines and drive their browsers too.

• 📦 Zero dependencies. No npm install. Node 18+ and Chrome 116+ is the whole requirement.

• 🏠 Entirely local. Loopback only by default. No telemetry, no analytics, no outbound calls.

Zero dependencies is a feature, not a boast. npm install failing is the most common reason a local MCP server doesn't work, and it fails silently from the user's point of view. The WebSocket and MCP protocol implementations are hand-written for exactly this reason.

Install

1. Get the code

git clone https://github.com/dylansantwani/openbrowser.git

There is nothing to build and nothing to install — no npm install step.

2. Load the extension

Open chrome://extensions, turn on Developer mode, click Load unpacked, and select the extension/ folder.

3. Point your MCP client at the server

claude mcp add openbrowser -- node /absolute/path/to/openbrowser/mcp-server/src/index.js

{
  "mcp": {
    "openbrowser": {
      "type": "local",
      "enabled": true,
      "command": ["node", "/absolute/path/to/openbrowser/mcp-server/src/index.js"]
    }
  }
}

Standard MCP stdio server:

{
  "mcpServers": {
    "openbrowser": {
      "command": "node",
      "args": ["/absolute/path/to/openbrowser/mcp-server/src/index.js"]
    }
  }
}

Quickstart

First, confirm Chrome is connected. The server prints its status and exits:

node mcp-server/src/index.js --health

The toolbar badge clears when Chrome is connected. If it doesn't, see Troubleshooting.

Now hand your agent a task. Everything an agent does reduces to two moves — read the page, then act on it. A read looks like this:

browser_navigate url:"example.com"
browser_snapshot

and browser_snapshot renders the page as a compact accessibility tree with [ref=eN] handles you can act on directly:

app.example.com/login · "Sign in · Example" · tab 481 · 1280x800
banner
  link "Example" [e1] /
main
  heading "Sign in" h1
  form
    textbox "Email" [e2] required
    password "Password" [e3] required
    checkbox "Remember me" [e4] unchecked
    button "Sign in" [e5]
  link "Forgot your password?" [e6] /reset

356 characters — roughly 90 tokens. The same page is ~4,000 tokens as raw accessibility JSON and ~1,500 as a screenshot.

A whole login in one call

Once you know a flow, browser_batch collapses it into a single round-trip:

{
  "tool": "browser_batch",
  "args": {
    "steps": [
      { "tool": "browser_navigate", "args": { "url": "app.example.com/login" } },
      { "tool": "browser_input", "args": {
          "fields": [
            { "ref": "e2", "value": "ada@example.com" },
            { "ref": "e3", "value": "correct horse battery staple" }
          ]}},
      { "tool": "browser_act", "args": { "action": "click", "ref": "e5" } },
      { "tool": "browser_wait", "args": { "for": "text", "value": "Dashboard" } }
    ]
  }
}

One round-trip instead of eight.

The tools

Fourteen tools, grouped by action enums rather than split into forty single-purpose ones — models pick an enum value far more reliably.

Full parameter reference: docs/TOOLS.md.

Keeping token cost down

The design assumes tokens are the scarce resource:

1. Snapshots, not screenshots. ~20x cheaper, and refs are directly actionable. Screenshot only to verify something visual.

2. mode: "diff" in loops. After the first snapshot, ask only what changed.

3. Actions return their own delta. After a click you usually already know what changed, so no follow-up snapshot is needed.

4. selector to scope. On a dense page, read the one region you care about.

5. browser_batch for known flows. Collapses N round-trips into one.

6. browser_macro for repeated flows. Derive the flow once, replay for the cost of a single call.

Difficult sites

The cases that usually break browser automation, and what handles them here:

Every row above is a bug that was found by driving the extension against a real site, not a hypothetical. The write-ups are in docs/SESSION-2026-08-02.md and docs/SESSION-2026-08-03.md.

Side panel

Click the toolbar icon or press Ctrl+Shift+U (⌘+Shift+U on macOS).

• Control — tabs, quick actions, element search

• Tools — run any tool by hand and see exactly what an agent would get

• Macros — inspect, run, and delete saved sequences

• Activity — every call with timing and errors

The panel calls the same dispatcher the MCP server does, so it is the fastest way to debug a flow: try it by hand, then hand it to the model.

Configuration

Extension options (chrome://extensions → Details → Extension options):

Server flags (node mcp-server/src/index.js …, or the matching env var):

How it works

  Claude Code ─┐
               ├─ stdio ─> mcp-server ─ ws://127.0.0.1:8848 ─> Chrome extension ─> your tabs
  opencode ────┘

The MCP server speaks stdio to your client and WebSocket to the extension. The first server to start binds the hub port; later ones join it. So several agents can share one browser — an editor agent and a CLI agent can work side by side without fighting over it, because each session gets a name of its own (harbor), owns only the tabs in its own tab group, and works in a shared background agent window that nothing it does can bring in front of you.

Everything is local. Nothing leaves your machine except the pages you ask it to visit.

Browsers on other machines

A hub can attach to hubs elsewhere, so one agent with one MCP config drives browsers on any number of boxes:

  your agent ──> hub (laptop) ──┬──> Chrome, here
                                ├──ws──> hub (10.0.0.5) ──> Chrome, there
                                └──ws──> hub (10.0.0.6) ──> Chrome, there

On each remote machine, let the hub listen off-loopback:

node mcp-server/src/index.js --hub --host 0.0.0.0

Then, from an agent:

browser_window action:"connect" hub:"10.0.0.5"

Its browsers appear as 10.0.0.5/<name> and are used exactly like local ones. action:"remotes" lists what is attached; action:"disconnect" detaches. --connect 10.0.0.5,10.0.0.6 attaches them at startup instead.

⚠️ The hub has no authentication. Anything that can reach it can run JavaScript in a logged-in browser. --host defaults to 127.0.0.1 for that reason — keep federated hubs on a private network or a VPN mesh, never on a public IP.

For why the pieces are split the way they are, see docs/ARCHITECTURE.md.

Security

• Binds loopback only (127.0.0.1). Nothing is exposed to your network.

• No telemetry, no analytics, no outbound calls of any kind.

• The blocklist ships with identity providers on it, because an automation mistake against an SSO flow is expensive and hard to undo.

• CAPTCHAs are reported, never solved or bypassed.

• The debugger permission is what makes trusted input possible. It is broad — read docs/ARCHITECTURE.md for exactly what it is used for, and turn it off in options if you would rather not grant it.

⚠️ Treat an agent with browser access as having your logged-in privileges. Use the allowlist when running unattended.

Troubleshooting

node mcp-server/src/index.js --health

The hub only exists while an MCP client has the server running. To test standalone: npm run hub.

Chrome blocks extensions on chrome:// pages, the Web Store, and other extensions' pages. Navigate somewhere else.

DevTools and the extension cannot both own the debugger. Close DevTools, or use another tab.

The page re-renders aggressively. Use browser_find immediately before acting, or browser_batch so the whole sequence runs before the page can change under you.

Expected under MV3. It respawns and reconnects on its own; the first call afterwards may take a moment.

Chrome caches extension files. Anything under extension/ needs chrome://extensions → reload before it takes effect. Anything under mcp-server/ is picked up when the MCP client next starts the server.

Development

npm test          # 232 tests: WebSocket framing, MCP protocol, round trip, formatting
npm run preview   # UI preview + in-browser accessibility-tree tests at :8850
npm run hub       # hub only, verbose
npm run icons     # regenerate icon PNGs

npm run preview serves two things that need a DOM: the side-panel UI at /, and the accessibility-tree assertions at /test/a11y-browser.html.

Layout:

extension/
  background/   service worker: bridge, router, CDP, recorder, frames, formatting
  content/      injected: accessibility tree, actions, frame offsets
  sidepanel/    the UI
  options/      settings
mcp-server/src/ ws.js (hand-rolled RFC 6455), hub.js, mcp.js, tools.js
docs/           capabilities, tools reference, architecture, test checklist
site/           the source of openbrowser.pulse-core.com (static, no build step)

CLAUDE.md carries the hard rules and the platform behaviours that each cost a real bug to discover. AGENTS.md is the short version for AI coding agents. TODO.md has the open work with reproduction details.

Contributing

Contributions are welcome. The short version: no dependencies, ever; npm test stays green; commits follow Conventional Commits. The full guide — dev setup, testing, commit convention, and PR process — is in CONTRIBUTING.md.

License

MIT — see LICENSE.

openbrowser.pulse-core.com