Skip to content

Chrome DevTools MCP

Browser automation for agents — navigate, click, fill forms, screenshot, read console and network logs, run Lighthouse audits.

Usage

bash scripts/chrome-debug.sh start     # start the browser (the MCP does this itself if needed)
bash scripts/chrome-debug.sh status
bash scripts/chrome-debug.sh stop      # profile volume survives

.mcp.json launches the server as chrome-devtools via scripts/mcp-run.sh chrome, which starts the browser container on demand. No manual step is needed before using the tools.

Why it does not use Windows Chrome

The usual WSL recipe runs Chrome on Windows with --remote-debugging-port and reaches it over localhost. That depends on WSL mirrored networking, which requires Windows 11 22H2+. This workstation is Windows 10 (build 19045) on default NAT networking, so WSL cannot reach a port on Windows loopback at all.

The remaining Windows-side options were both worse:

Option Why not
--remote-debugging-address=0.0.0.0 Exposes the browser's debugging interface — full control of the profile and its logged-in sessions — to the network. Chrome also ignores the flag and binds 127.0.0.1 regardless.
netsh portproxy Needs an admin shell and a firewall rule, and does not survive reboots cleanly.
Chromium inside WSL No apt candidate on this distro, and installing it needs sudo.

So Chrome runs in a container and nothing is published. The MCP client joins the browser's network namespace (docker run --network container:...), where 127.0.0.1:9222 is the browser. No host port, no firewall rule, no exposure beyond the container pair, and no WSL restart to set it up.

┌─ container network namespace ─────────────┐
│  chromium :9222   ←──  chrome-devtools-mcp│ ──stdio──▶ Claude Code
└───────────────────────────────────────────┘

Notes

  • Headless (--headless=new). It renders and screenshots normally, but there is no window to click in, so interactive logins must be driven through the MCP tools rather than by hand.
  • The profile lives in the chrome-debug-profile Docker volume, so cookies and sessions persist across restarts. stop keeps it; delete the volume to reset.
  • Separate browser from your Windows Chrome — logins do not carry over.
  • Pinned to chrome-devtools-mcp@0.25.0; telemetry is off (--no-usage-statistics --no-performance-crux).
  • Chrome is a normal client of the public internet here. It has no credentials beyond what its own profile accumulates, and no access to local/.env.