ChromeMCP

A small, opinionated stack that lets agents in WSL2 drive your real, signed-in Chrome on Windows through the Model Context Protocol (MCP). You launch Chrome once with CDP enabled against a dedicated user-wide profile, expose that debug port to WSL through a scoped portproxy + firewall rule, and run Playwright MCP as a long-running HTTP/SSE service that any MCP client (Codex, Claude Code, Cursor, Continue, etc.) can attach to. Every client shares the same browser session — same tabs, same cookies, same logins. Multi-client by design: repositories point to the same service instead of installing their own ChromeMCP runtime.

Architecture

┌─────────────── Windows host ───────────────┐    ┌──────── WSL2 ────────┐
│                                            │    │                      │
│  Chrome.exe                                │    │  Playwright MCP      │
│  ├─ profile: %LOCALAPPDATA%\ChromeMCP      │    │  (HTTP/SSE server)   │
│  └─ --remote-debugging-port=9222           │    │  localhost:8931/mcp  │
│         │                                  │    │       │              │
│         │ 127.0.0.1:9222 (CDP)             │    │       │              │
│         ▼                                  │    │       ▼              │
│  netsh portproxy ◄───── firewall ──────────┼────┤  CDP client          │
│  (vEthernet WSL IP)    (WSL subnet only)   │    │                      │
│                                            │    │  ▲ ▲ ▲               │
└────────────────────────────────────────────┘    │  │ │ │  MCP clients  │
                                                  │  Claude Code, Cursor,│
                                                  │  Continue, ...       │
                                                  └──────────────────────┘

The Chrome profile lives in %LOCALAPPDATA%\ChromeMCP\Profile, not in this repo (browser data belongs on Windows-native storage, not on a 9p share). The portproxy binds only to the WSL vEthernet adapter IP, and the firewall rule restricts source to the WSL subnet — your LAN cannot see port 9222.

Requirements

• Windows 10/11 with WSL2 and Google Chrome 140+ (pinning guide)
• A WSL2 distro (tested on Ubuntu) with Node.js ≥ 18.18
• PowerShell 5.1+ on Windows (ships by default)
• Administrator rights on Windows for the one-time bridge setup

Install

# One-liner (installs to ~/ChromeMCP):
curl -fsSL https://raw.githubusercontent.com/rizonetech/ChromeMCP/main/scripts/install.sh | bash

# Via npm / npx (no clone required):
npx @rizonetech/chromemcp install

# From source:
git clone https://github.com/rizonetech/ChromeMCP.git ~/ChromeMCP
cd ~/ChromeMCP && bash scripts/install.sh --from-source

Quick start

chromemcp setup-bridge   # one-time Windows bridge setup (UAC required)
chromemcp chrome         # launch Chrome with CDP
chromemcp up             # start the MCP server
chromemcp token          # print bearer token for client config
chromemcp test           # smoke test

Sign in to any sites you need in the new Chrome window. The profile persists across restarts — sign in once.

Optional lanes for isolation or concurrency

The shared instance on 8931 is the default and recommended path, including when more than one MCP client is connected. Do not allocate a lane merely because another client or repository uses ChromeMCP.

Use a lane only when simultaneous browser actions would interfere, or when a workflow explicitly needs separate cookies, storage, login state, or browser policy. For an isolated Codex run:

eval "$(chromemcp codex-lane acquire --format shell --owner "overnight-$$")"
chromemcp codex-bridge "$CODEX_CHROMEMCP_LANE"
chromemcp codex-chrome "$CODEX_CHROMEMCP_LANE"
chromemcp codex-up "$CODEX_CHROMEMCP_LANE"
chromemcp codex-status "$CODEX_CHROMEMCP_LANE"

The default instance remains unchanged on MCP 8931, upstream 8932, CDP 9222, token ~/.config/chromemcp/token, and Windows profile %LOCALAPPDATA%\ChromeMCP\Profile. The Codex instance uses MCP 8941, upstream 8942, CDP 9232, token ~/.config/chromemcp-codex/token, and profile %LOCALAPPDATA%\ChromeMCP-Codex\Profile.

Point Codex at mcp/client-config-codex.json or set:

eval "$(chromemcp codex-lane env "$CODEX_CHROMEMCP_LANE")"

Release the lock when the run is finished:

chromemcp codex-lane release "$CODEX_CHROMEMCP_LANE"

Lane 1 keeps the compatibility defaults above. Lane 2 uses MCP 8951, upstream 8952, CDP 9242, token ~/.config/chromemcp-codex-2/token, and profile %LOCALAPPDATA%\ChromeMCP-Codex-2\Profile; higher lanes follow the same +10 port pattern.

Lanes for any client

codex-lane is an alias for the client-generalized lane command. Each client gets its own port band, so concurrent Codex and Claude overnight runs can never collide with each other or with the default stack:

eval "$(chromemcp lane acquire --client claude --format shell --owner "overnight-$$")"
chromemcp lane up --client claude "$CHROMEMCP_LANE"     # starts MCP, Chrome, bridge
chromemcp lane config --client claude "$CHROMEMCP_LANE" # client config JSON
chromemcp lane release --client claude "$CHROMEMCP_LANE"

Claude lanes start at MCP 8741 / upstream 8742 / CDP 9432 (lane 1) and step +10 per lane, with profile %LOCALAPPDATA%\ChromeMCP-Claude[-N]\Profile and token ~/.config/chromemcp-claude[-N]/token. Crashed runs are reclaimed automatically: the next acquire reuses a lane whose owner process is gone.

Connect your MCP client

The server listens at http://localhost:8931/mcp. Get the token:

chromemcp token --header   # prints: Authorization: Bearer <token>

Merge into your client's MCP config:

{
  "mcpServers": {
    "chromemcp-playwright": {
      "type": "http",
      "url": "http://localhost:8931/mcp",
      "headers": { "Authorization": "Bearer <TOKEN>" }
    }
  }
}

Older clients can target /sse instead of /mcp. Full per-client instructions: docs/CLIENTS.md.

CLI reference

| Command | What it does | |---|---| | chromemcp up | Start the MCP server (auto-launches Chrome and bridge if needed) | | chromemcp down | Stop the MCP server | | chromemcp status | Health report | | chromemcp test | Smoke test (initialize + browser_tabs + browser_snapshot) | | chromemcp chrome | Launch Chrome with CDP on Windows | | chromemcp setup-bridge | Install/refresh the WSL↔Windows portproxy | | chromemcp bridge-check | Diagnose bridge health (--fix to auto-repair) | | chromemcp token | Print bearer token (--header, --rotate, --path) | | chromemcp logs | Tail server logs (auto-detects systemd vs file mode) | | chromemcp enable | Install systemd user unit (crash auto-restart) | | chromemcp disable | Uninstall systemd unit; revert to ad-hoc mode | | chromemcp update | Pull latest release and reinstall |

Links

• docs/CLIENTS.md — per-client config (Claude Code, Cursor, Codex, Python)
• docs/CONFIGURATION.md — all environment variables
• docs/TROUBLESHOOTING.md — common errors, reconnection, bridge self-healing
• SECURITY.md — threat model, auth proxy, network scoping
• CHANGELOG.md — version history
• claude-plugins marketplace — Claude Code plugin
• codex-plugins — Codex plugin

License

MIT © 2026 Rizonetech (Pty) Ltd.