OpenBrowser

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

A Chrome extension with a side-panel UI, 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 · Tools · Token cost · Difficult sites · Security · Docs

Why this exists

Most browser automation hands your agent a fresh headless browser: 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.

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.

Related MCP server: Chrome MCP Server

Install

1. Load the extension

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

2. 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"]
    }
  }
}

3. Check it

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

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

How it fits together

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

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 in the same session without fighting over it.

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

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.

What a page looks like

browser_snapshot renders this:

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

{
  "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.

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.

• 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):

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          # 75 tests: WebSocket framing, MCP protocol, round trip, formatting
npm run preview   # UI preview + 68 browser 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. TODO.md has the open work with reproduction details.

License

MIT — see LICENSE.

openbrowser.pulse-core.com