One Chrome

One signed-in Chrome for every model you have open.

Cursor, Claude, and OpenCode can drive the same browser at the same time. Each client gets its own tabs and its own tab group. Clicks, typing, and navigation take a lease on the tab, so two models never type into the same field at once. Reads overlap. Tabs stay in the background, so one model does not steal the window from another.

The host speaks two tool dialects:

• chrome_*, a full browser toolset: snapshots with stable refs, trusted mouse and keyboard input, console, network, dialogs, emulation, and Core Web Vitals.

• Claude's browser toolset, all 31 members of browser_toolset_20260801, with the same names, ref_N targets, error texts, and tab context. A Messages API executor turns a turn of tool_use blocks into tool_result blocks.

 Cursor / Claude / OpenCode              your own Messages API app
        │  stdio (starts the host)                │  POST /claude/execute
        ▼                                         ▼
 ┌────────────────────────── One Chrome host ───────────────────────────────┐
 │  /mcp   chrome_* tools     /mcp/claude   Claude members    /mcp/all both │
 │  sessions · tab leases · per-tab queues · popup and download tracking    │
 └───────────────────────────────────┬──────────────────────────────────────┘
                                     │  ws://127.0.0.1:12307/bridge
                                     ▼
                    Chrome extension, running in your profile
             debugger · scripting · tab groups · downloads

Install

Requires Node 20+ and Chrome (or Chromium) 120+.

git clone https://github.com/AbinMadathil07/one-chrome.git
cd one-chrome
npm install
npm run build

Load the extension:

1. Open chrome://extensions and turn on Developer mode.

2. Click Load unpacked and select the extension folder inside the clone. The repo root has no manifest, and Chrome will say the manifest is missing if you select it.

3. Open the extension popup and click Connect. It reconnects on its own after Chrome restarts.

Related MCP server: Umbra MCP Server

Add it to an MCP client

Give the client a command, not a URL. The first client starts the host. Every later client attaches to that same host, so they share one browser. You only need npm start when you want the host up before any client connects.

Replace /path/to/one-chrome with the clone path.

Cursor and Claude Code (~/.cursor/mcp.json, ~/.claude.json):

{
  "mcpServers": {
    "one-chrome": {
      "command": "node",
      "args": ["/path/to/one-chrome/dist/cli.js", "stdio"]
    },
    "one-chrome-claude": {
      "command": "node",
      "args": ["/path/to/one-chrome/dist/cli.js", "stdio", "--claude"]
    }
  }
}

OpenCode (~/.config/opencode/opencode.jsonc), version 1.x:

{
  "mcp": {
    "one-chrome": {
      "type": "local",
      "command": ["node", "/path/to/one-chrome/dist/cli.js", "stdio"],
      "enabled": true
    }
  }
}

Host logs are written to ~/.chrome-mcp/host-12306.log. Check that the extension is connected with node dist/cli.js status, then try: "Open example.com and tell me the heading."

How sharing works

A session is created for each MCP connection, so sessionId is optional. Call session_ensure with a distinct clientId when one connection drives several agents. To share a tab on purpose, attach it with session_attach_tab: reads overlap, writes wait their turn.

Claude browser toolset

stdio --claude exposes the members Claude's browser use tool defines.

Targets are {"type":"ref","ref":"ref_3"} or {"type":"coordinate","x":120,"y":340}. Refs come from read_page and find and stay valid until the page navigates. A stale ref returns Error: ref_3 is stale or not found on the current page. Re-read the page to get fresh references. Screenshots are CSS pixels, so a coordinate read off the image is the coordinate to click. Viewports wider than 1568px are scaled down, and incoming coordinates are scaled back up. Results include the tab-context footer, opened tabs, and download lines in the form Claude's API renders.

If you call the Messages API yourself, post each turn's browser tool_use blocks to the host:

curl -s http://127.0.0.1:12306/claude/execute \
  -H 'content-type: application/json' \
  -d '{
    "session": "my-agent",
    "tool_uses": [
      { "id": "toolu_1", "name": "navigate", "input": { "url": "example.com" } },
      { "id": "toolu_2", "name": "read_page", "input": { "filter": "interactive" } }
    ]
  }'

The response is { "tool_results": [...] }, one block per call, with toolset_name: "browser" and a browser_state block. Calls run in order. After a failure, the rest of the turn gets Not executed: an earlier action in this turn failed. DELETE /claude/sessions/my-agent closes that session and its tabs.

examples/claude-browser-agent.mjs is a full agent loop:

ANTHROPIC_API_KEY=sk-ant-... node examples/claude-browser-agent.mjs "Open example.com and summarize it"

chrome_* toolset

Pass includeSnapshot: true on a mutating tool to get the page's interactive elements back with the result. If an action opens a JavaScript dialog, the call returns { modal } instead of hanging, and other commands wait until chrome_handle_dialog.

Configuration

Every variable is optional. Defaults are safe for a machine you control.

See .env.example.

Security

The browser is your real profile, with its cookies and accounts, and any page can contain text written to steer a model.

• Leave the host on 127.0.0.1. Set CHROME_MCP_TOKEN if other local processes can reach the ports.

• For untrusted sites, use a separate Chrome profile with no accounts, set CHROME_MCP_ALLOWED_HOSTS, set CHROME_MCP_BLOCK_PRIVATE_NETWORKS=true, and point CHROME_MCP_UPLOAD_DIR at a folder that holds only files meant for upload.

• javascript_exec, chrome_evaluate, chrome_fetch, and uploads run with the page's privileges. Hide the ones you do not need with CHROME_MCP_DISABLED_TOOLS.

• Console and network output is redacted for tokens, keys, JWTs, and credential query parameters. Treat the rest as untrusted.

• Chrome shows a debugging banner while DevTools is attached. chrome_devtools_detach removes it for that tab.

Development

npm run dev        # rebuild and serve on change
npm test           # leases, sessions, Claude formatting, uploads
npm run typecheck
npm run build
npm run smoke      # round trip against the running host and your Chrome
CHROME_BIN="/path/to/Google Chrome for Testing" npm run e2e

npm run e2e serves a fixture page, starts its own host on ports 22306 and 22307, and launches Chrome for Testing with a copy of the extension. It does not touch a host or browser you already have open. It drives two concurrent sessions through the chrome_* tools and the full Claude toolset, both over MCP and through /claude/execute. Branded Chrome ignores --load-extension, so use Chrome for Testing or Chromium. HEADLESS=0 shows the window.

src/
  cli.ts            serve, stdio, status
  config.ts         environment variables, defaults, validation
  concurrency/      sessions, tab leases, per-tab queues
  bridge/           WebSocket protocol
  browser/          runtime, uploads, downloads, snapshot search
  claude/           Claude toolset executor
  mcp/              HTTP server, both toolsets, stdio launcher
extension/          MV3 extension. Load this folder.
examples/           Messages API agent loop
scripts/            smoke and end-to-end tests
test/               unit tests and the browser fixture

Credits

The idea of driving a real Chrome profile from MCP comes from hangwin/mcp-chrome (MIT). One Chrome is an independent rewrite built around sharing that browser across models.

License

MIT