chrome-control-mcp

What's new

Every release, with the day it shipped and what it changed, is in CHANGELOG.md; each release page has its downloads. To hear about new ones, use Watch → Custom → Releases on this repository, or subscribe to the releases feed. An agent can check for you with browser_update_check, and install one with browser_update_apply.

Related MCP server: Chrome MCP Server

Highlights

Many agents, one browser

Each of these is a direct browser_screenshot from the same run as the window above, with include_control_overlay turned on; screenshots an agent takes for itself leave the overlay out.

How it keeps agents apart, in the order they meet it:

1. Its own tab. An agent opens one with browser_new_tab -- optionally naming itself with agent: "research" -- and passes the returned tab_id to every call. Element refs from a snapshot are bound to the tab they came from, so one agent's snapshot never retargets another's click.

2. Its own group. Each agent's tabs share a tab group titled for it (or for its MCP client), in a colour no other live group has. A tab its own click opens joins the same group.

3. Nobody else's tab. A tab another session holds is refused by name, and browser_tabs marks it controlled_by_other_session rather than hiding it.

4. Its own clipboard. Copy, cut and paste keys, browser_clipboard, and a page's copy and paste buttons in its tabs use the agent's own clipboard; your clipboard is never read or written.

5. Letting go. browser_release (with tab_id to release only that agent's tabs, popups included) closes what the agent opened and hands back what it borrowed; keep_open: true leaves a page open for you. The tab you are looking at and the browser's last tab are never closed.

Two agents behind one server are isolated but take turns: one server carries one command at a time. Separate servers -- separate editor windows or clients -- run in parallel. The design record is docs/MULTI_SESSION.md.

Chrome profiles. Load the extension in each profile agents may use -- work, personal, each person's -- and one server serves them all. An agent opens its tab in a profile by name (browser_new_tab with profile: "work"), or in the one whose window you used last, and every call with that tab_id goes there. browser_tabs names each tab's profile. A profile is called by its account email, or a name you give it on the extension's options page (chrome://extensions → Chrome Control MCP → Details → Extension options). A profile without the extension stays out of reach.

Stopping every agent at once: click the extension's toolbar button while it is connected. Tabs the agents opened are left open for you, tabs they borrowed are handed back, and the groups and highlights come off. The button then reads "off", and nothing reconnects -- even after a browser restart -- until you click it again.

File pickers are caught only while an agent's own command runs (and for 2 s after), so your own clicks on an upload button still open the normal dialog. Folder pickers are not supported yet.

Install

Two parts: the MCP server, which your client runs, and the Chrome extension the server drives.

The server, for any MCP client

Download the latest release for Windows x64, Linux x64, Apple silicon macOS or Intel macOS -- the release page's Downloads table says which file is yours -- verify its SHA-256 against SHA256SUMS.txt, unpack it, and run:

# Windows
.\chrome_control_mcp.exe --install

# Linux / macOS
./chrome_control_mcp --install

That installs the server where it can update itself and prints the command path to give your client, plus the folder to load into Chrome. Both stay the same through every later update. The archives are deliberately unsigned; the release guide covers verification and platform warnings. Then connect your client.

Or, in VS Code, from the Marketplace

code --install-extension RandyNorthrup.chrome-control-mcp

The same server, packaged for VS Code: on first activation the extension installs it as above and registers it with VS Code's own MCP support, so there is no mcp.json to edit. Marketplace updates and the server's own updater land in the same install, and from 1.8.0 on an older copy never rolls a newer one back.

Add the extension to Chrome (once)

From the Chrome Web Store: install Chrome Control MCP in one click, and the store keeps it up to date. It needs the server at 1.13.0 or later. Google reviews every version before the store offers it, so the store can trail a release by a few days -- and the listing opens once its first review passes.

Or load the folder unpacked: open chrome://extensions, turn on Developer mode, choose Load unpacked, and pick the extension folder -- the path --install printed, or run Chrome Control MCP: Show the Chrome extension folder to load in VS Code, which copies it for you. This is manual by Chrome's design: branded Chrome ignores --load-extension. Updates reuse the same folder, so it is a one-time step, and from 1.9.0 on the extension reloads itself after an update once no agent is using it. Coming from an older version, press reload on it once (or restart Chrome).

Use one or the other in a Chrome profile, not both: they are two extensions with two IDs, and the server answers to each. To let agents into another profile, add the extension there too.

Connect any MCP client

The server speaks MCP over stdio and opens no network listener. Point your client at the stable command path that --install prints:

Claude Code

claude mcp add --scope user chrome-control -- "<command path>"

Codex CLI

codex mcp add chrome-control -- "<command path>"

Cursor, Windsurf, Claude Desktop, and other JSON-configured clients

{
  "mcpServers": {
    "chrome-control": { "command": "<command path>" }
  }
}

VS Code (GitHub Copilot and other chat extensions): the Marketplace extension registers the server for you; or add the command path to mcp.json like any other client.

After an update, restart the server in your client (in Claude Code: /mcp, then reconnect) so it runs the new build.

Tools at a glance

All 55 tools have strict JSON Schemas; the tool reference documents each one.

Staying up to date

Every release page is titled with what the release does, says the day it shipped, and ends with a Downloads table saying which file is yours; What's new has the latest three and CHANGELOG.md the rest. From any client:

browser_update_status   where this build is installed, and which versions are present
browser_update_check    what the newest release is
browser_update_apply    download, verify and install it

Each version is installed into <root>/versions/<version>, and a current link -- a directory junction on Windows, a symbolic link elsewhere -- is repointed at it, so a running server is never overwritten. The client's command path, Chrome's extension folder and the native-messaging registration all point through current and never change. Downloads are checked against the SHA-256 published with the release.

Neither Chrome nor your editor reloads code under a running process. The MCP server in your client picks up a new build when the client restarts it. The extension, from 1.9.0 on, reloads itself for a newer installed copy as soon as no agent holds a tab and none has used it for 10 s, so it never interrupts an agent's work.

Until both have, you are told. Whenever the server, the installed copy and the extension Chrome is running disagree, your agent's next browser reply carries a note saying which is behind and the one thing that fixes it -- reload the extension, restart the server, or install -- in any MCP client, and browser_extension_status shows all three versions.

Set CHROME_CONTROL_MCP_INSTALL_ROOT to install somewhere else.

How it works

flowchart LR
    subgraph Clients["MCP clients"]
        A1["Claude Code<br/>agents: research, writer"]
        A2["Codex"]
    end
    A1 -->|MCP over stdio| B1[chrome_control_mcp]
    A2 -->|MCP over stdio| B2[chrome_control_mcp]
    B1 -->|named pipe / Unix socket| C1[Native-host relay]
    B2 -->|named pipe / Unix socket| C2[Native-host relay]
    C1 -->|native messaging| D[Chrome extension]
    C2 -->|native messaging| D
    D -->|DevTools protocol| G1["AI · research tabs"]
    D -->|DevTools protocol| G2["AI · writer tabs"]
    D -->|DevTools protocol| G3["AI · codex tabs"]

One executable is both the MCP server and the native-messaging relay Chrome launches. Each server publishes its own rendezvous record and gets its own relay; the one extension holds a session per relay and a set of tabs per session, each with its own debugger attachment and page state. A relay that is attached tells the extension within about a second when another server starts, without starting a process to ask. More in docs/ARCHITECTURE.md.

Security model

Full browser control is powerful, so the boundaries are explicit:

• The extension origin is pinned, the relay authenticates as the same user and the same executable, and every IPC message is size-limited and validated. Windows uses a current-user ACL-protected named pipe; Linux and macOS use a mode-0600 Unix socket in a private directory with peer credentials.

• Stale element refs and screenshot coordinates are refused rather than retargeted, and payloads are bounded throughout.

• File uploads are read by the server, never by the page, up to 2 GiB a file unless CHROME_CONTROL_MCP_UPLOAD_MAX_MB says otherwise, and can be confined with CHROME_CONTROL_MCP_UPLOAD_ROOTS.

For inspection-only use:

CHROME_CONTROL_MCP_SECURITY_PROFILE=read_only
CHROME_CONTROL_MCP_REDACT_SENSITIVE_OUTPUT=true

The read-only profile exposes 15 tools -- 12 that look at the browser plus extension status and the two update checks -- and independently refuses any hidden mutating call. The extension's permissions, and why each is needed, are in docs/SECURITY.md.

Verification

Measured for 1.9.0 on 2026-10-31, except the two rows marked 1.8.0, whose code later releases leave alone:

npm run smoke
node tests/e2e/isolated_run.mjs --chrome=<Chrome for Testing> tests/e2e/multi_agent_e2e.mjs

Exact evidence and its limits are in docs/VERIFICATION.md.

Build from source

Requirements: Windows 10/11 x64, Linux x64 or macOS; Google Chrome 116+; CMake 3.25+; Qt 6.5+ (Core, Network, Test); a C++20 compiler (Visual Studio 2022, GCC or Clang); Node.js 20.19+.

npm ci
npm run build             # or ./scripts/build.ps1 -Configuration Release
npm run extension -- install

The build uses warnings as errors and runs every native and extension unit suite. Output lands in build/Release/ on Windows and build/ elsewhere, with the extension staged beside the executable. Prefer the path --install prints over a build-directory path: only it survives an update.

Project identity

To retire it, run npm run extension -- uninstall (or browser_extension_uninstall), then remove the extension at chrome://extensions.

Thanks

Inflectra's UI Test Automation Playground (source) and Elemental Selenium's The Internet provide focused, practical browser scenarios. Both have been invaluable for testing this project end to end.

License

Released under the MIT License. Copyright © 2026 Randy Northrup.

If this project saves you time, you can buy me a coffee via PayPal. Thank you!