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>/.omp/mcp.json (project scope).

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

CLI reference

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

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 being 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.

License

MIT