chrome-devtools-mcp-wrapper

Share one Chrome across all your AI coding sessions.

A thin proxy wrapper around Google's chrome-devtools-mcp that adds what the upstream server assumes away: multiple MCP clients are going to run at the same time, and they shouldn't each own a browser.

 omp ─┐
claude ├─ stdio ──▶ chrome-devtools-mcp-wrapper ── npx ──▶ chrome-devtools-mcp ──CDP──▶ Chrome (shared)
cursor ┘             lifecycle · filtering ·             (official, unmodified)
                     anti-detect · logging

The problem

chrome-devtools-mcp is a single-client server: every MCP client that spawns it launches its own Chrome instance. Run three AI assistants (or three sessions of one) and you get three browsers competing for memory — each with a separate profile, separate login state, and no coordination on shutdown.

Related MCP server: js-reverse-mcp

What this adds

The upstream server itself runs unmodified — the wrapper spawns it via npx chrome-devtools-mcp@latest, wires its Chrome connection, and filters what passes through.

Requirements

• Node ≥ 18

• Google Chrome (any recent stable; the wrapper locates it, including Playwright-managed installs)

• npx (bundled with npm) — the upstream server is fetched on first run

Quickstart

git clone https://github.com/CornWorld/chrome-devtools-mcp-wrapper.git
cd chrome-devtools-mcp-wrapper
npm install

# smoke test: launches Chrome (or reuses a running one) and starts the proxy
npm start -- --profile=default

Register it with your MCP client instead of the plain server. For Claude-style mcp.json:

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "node",
      "args": [
        "/absolute/path/to/chrome-devtools-mcp-wrapper/index.mjs",
        "--profile=default"
      ]
    }
  }
}

For OMP, put the same block in ~/.omp/agent/mcp.json (user scope — applies to every project) or <project>/.mcp.json (project scope). Project scope is picked up at session start (with a trust approval); a mid-session /mcp reload only refreshes user-scope servers.

See .mcp.json.example for a config with tool filtering and debug logging enabled.

CLI reference

node index.mjs [options] [-- upstream-args...]

Environment: CHROME_PATH=<binary> overrides Chrome discovery — use it to pin Chrome-for-Testing or a specific Playwright Chromium build (e.g. to load extensions via --chrome-arg=--load-extension=..., which requires an unbranded binary and a real profile).

Profiles

A profile is a Chrome user-data directory plus a lock file. Clients that agree on a profile name share its browser; different profiles mean different browsers (useful to isolate work projects from personal ones, or headed from headless).

• --profile=work and --profile=personal → two independent Chrome instances

• no flag → shared-lite, one instance for everything

• profile state (lock files, user-data dirs) lives under ~/.cache/cdp-wrapper/

Upstream version policy

The wrapper launches the upstream server with npx chrome-devtools-mcp@latest and currently passes --experimentalPageIdRouting / --experimentalStructuredContent. This means:

• upstream fixes and features arrive automatically; no version pin to maintain

• but an upstream breaking change to those experimental flags can break the wrapper on a fresh npx fetch. If you need stability, change upstreamArgs in index.mjs to a pinned version (chrome-devtools-mcp@1.8.0).

Logging

Each session writes ~/.cache/cdp-wrapper/logs/wrapper-YYYYMMDD-HHMMSS-<pid>.log (path also printed to stderr at startup). Tunables via environment:

Notes & disclaimers

• The anti-detect layer exists to keep automation from needlessly flagged while testing your own sites and apps. Using it against services you don't have permission to automate may violate their terms of service — that's on you.

• The wrapper is a transparent pass-through for MCP traffic; it does not inspect or alter tool results beyond dropping filtered tools.

TODO

• Surface wrapper capabilities as MCP server instructions so MCP clients (and their models) see them without reading this README: profile sharing/isolation semantics (--profile, shared-lite), --chrome-arg passthrough (extensions, GPU flags, …), tool filtering (--block-tools/--allow-only), custom tools (--init-script), and CHROME_PATH pinning.

• Consider a --list-flags flag that prints the effective CLI reference, and a startup log line echoing the resolved profile + Chrome binary + extra args (including extension load errors from stderr).

Loading unpacked extensions (--chrome-arg=--load-extension)

Verified on unbranded Chrome-for-Testing 150, headed and --headless=new: a valid MV3 unpacked extension loads via --chrome-arg=--load-extension=/path/to/dist, its service worker appears in CDP targets and content scripts inject normally. Branded Google Chrome 137+ ignores --load-extension (upstream change) — use CfT/Chromium via CHROME_PATH.

The trap that costs hours: an unpacked extension with an invalid manifest field loads with no visible error (e.g. content_scripts[].matches must be an array; a string fails schema validation). Symptom: the extension looks half-alive — a service worker may show up in targets — but content scripts silently never inject. An unvalidated canary extension will happily report false negatives, sending you chasing keychain/headless ghosts. Diagnose instead with:

# extension load errors land on stderr
chrome --enable-logging=stderr --v=1 --load-extension=/path/to/ext about:blank

or check the error card on chrome://extensions in a headed session.

License

MIT