Apr 24, 2026

Chrome DevTools MCP: Giving Your AI Agent Eyes in the Browser

A professional walkthrough — from install to real-world use — of Chrome DevTools MCP across VS Code, Cursor, GitHub Copilot, Claude Code and Gemini CLI with npx chrome-devtools-mcp@latest and --autoConnect. JSON configs, the Chrome M144+ connection flow, Lighthouse and CORS debugging prompts, and a verification checklist.

Engineering

Tags (9)

# mcp # chrome-devtools # cursor # claude-code # github-copilot # gemini # productivity # debugging # lighthouse

Last week I asked an agent to fix a CORS bug on an admin page. It produced three versions that were all “theoretically correct” — add a header, flip credentials, patch middleware — and none of them worked. Because it couldn’t see the actual request in DevTools. It was guessing.

Chrome DevTools MCP closes that blind spot. The agent opens a real Chrome, reads a real Network waterfall, runs a real Lighthouse pass, and only then writes the fix. Here’s how I wire it up across VS Code, Cursor, GitHub Copilot, Claude Code and Gemini CLI, along with the workflows that have actually cut my debug cycles from half an hour to minutes.

Primary sources (read these first)

Baseline requirements: Node.js ≥ 20.19 LTS, Chrome stable (or Chrome for Testing), npm. --autoConnect requires Chrome M144+ — if stable hasn’t caught up, pass --channel=beta or --channel=canary.

The shared base config

Nearly every client accepts the same root config. Pin it — every variant just adds flags:

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": ["-y", "chrome-devtools-mcp@latest"]
    }
  }
}

-y skips the first-run npx confirmation. @latest pulls the newest package at startup — trade stability for freshness by pinning ([email protected]) if you run this in CI.

The flags I reach for most:

Per-client install

All six clients share the base config above — only where you put it and which command registers it differ. Expand the one you need:

code --add-mcp '{"name":"chrome-devtools","command":"npx","args":["-y","chrome-devtools-mcp@latest"]}'

{
  "servers": {
    "chrome-devtools": {
      "command": "npx",
      "args": ["-y", "chrome-devtools-mcp@latest"]
    }
  }
}

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": ["-y", "chrome-devtools-mcp@latest", "--autoConnect", "--viewport=1440x900"]
    }
  }
}

claude mcp add chrome-devtools --scope user npx chrome-devtools-mcp@latest

/plugin marketplace add ChromeDevTools/chrome-devtools-mcp
/plugin install chrome-devtools-mcp

# Project-wide — MCP only
gemini mcp add chrome-devtools npx chrome-devtools-mcp@latest

# Machine-wide
gemini mcp add -s user chrome-devtools npx chrome-devtools-mcp@latest

# Or install as an extension (MCP + Skills + auto-update)
gemini extensions install --auto-update \
  https://github.com/ChromeDevTools/chrome-devtools-mcp

copilot
/mcp add

codex mcp add chrome-devtools -- npx chrome-devtools-mcp@latest

[mcp_servers.chrome-devtools]
command = "cmd"
args = ["/c", "npx", "-y", "chrome-devtools-mcp@latest"]
env = { SystemRoot = "C:\\Windows", PROGRAMFILES = "C:\\Program Files" }
startup_timeout_ms = 20_000

--autoConnect: attach to your signed-in Chrome

This is the mode I recommend for daily work — the agent uses the exact session you have open: cookies, SSO, extensions, the tab you were already debugging. No restart, no re-login.

Three-step summary: (1) enable chrome://inspect/#remote-debugging in Chrome M144+, (2) add --autoConnect to your MCP client’s args, (3) run a smoke-test prompt and click Allow when Chrome asks.

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": ["chrome-devtools-mcp@latest", "--autoConnect"]
    }
  }
}

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": ["chrome-devtools-mcp@latest", "--autoConnect", "--channel=beta"]
    }
  }
}

Check the performance of https://developers.chrome.com

/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
  --remote-debugging-port=9222 \
  --user-data-dir=/tmp/chrome-profile-stable

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": [
        "chrome-devtools-mcp@latest",
        "--browser-url=http://127.0.0.1:9222"
      ]
    }
  }
}

The 29 tools, grouped

Knowing what’s available makes your prompts tighter and the agent’s tool choice better.

Need to save context? Use --slim — just navigate_page, evaluate_script, take_screenshot.

Prompts I’ve actually used

Guided Lighthouse audit

Don’t just say “run Lighthouse.” Give thresholds and demand a plan:

Visit http://localhost:3000/pricing. Emulate 4G throttling + Moto G4.
Run lighthouse_audit for performance, accessibility, seo.
If LCP > 2.5s or CLS > 0.1, performance_start_trace, reload, stop, then
performance_analyze_insight and return the top 3 causes. Propose fixes
with repo-local file/line — DO NOT edit code.

This forces the agent to plan first and not edit code in the first pass — you review insights before any changes.

CORS debugging (the classic)

Open https://app.local/dashboard. Wait for network idle.
list_network_requests filter status >= 400 or failed, domain api.local.
For the first failing request, get_network_request for full request +
response headers. Check Access-Control-Allow-Origin vs Origin, confirm
OPTIONS preflight returns 204, and look for missing Allow-Credentials
when the client sends credentials: 'include'. Summarize root cause in
3 bullets and propose a server-middleware patch — DO NOT edit code.

Three things the agent usually misses without prompting: (1) preflight missing Access-Control-Allow-Methods, (2) Allow-Origin: * is incompatible with credentials: 'include', (3) a proxy (Nginx/Cloudflare) stripping the header at a different layer.

Form + console repro

navigate_page to /checkout. fill_form {email:"[email protected]", card:"4242..."},
click "Place order". wait_for text "Order confirmed" or 10s timeout.
On timeout: list_console_messages (error, warning),
list_network_requests (status >= 400), take_screenshot viewport.
Return bundle: console log + failing request + screenshot + hypothesis.

Performance diff across commits

Emulate Slow 4G. Trace twice: before and after checkout of commit abc123.
Compare LCP, TBT, JS bundle size from network. Report deltas; flag if
TBT grows > 100ms.

Verification checklist

After pasting JSON, run this in order:

• npx chrome-devtools-mcp@<pinned-version> --help works (Node ≥ 20.19; use a specific reviewed version, not @latest, on work machines)
• Restart client — chrome-devtools appears in the tool picker
• Smoke prompt: “Check the performance of https://developers.chrome.com” → Chrome opens on its own
• chrome://inspect dialog appears when using --autoConnect — click Allow
• Agent returns Lighthouse scores, not “I can’t access a browser”
• list_network_requests returns > 0 entries on a public page
• take_screenshot yields a PNG (check chat attachments)
• On ECONNREFUSED with --browser-url: is Chrome on the right port? curl http://127.0.0.1:9222/json/version must return JSON
• --autoConnect not attaching? Chrome version ≥ 144 (chrome://version) and Allow toggled in chrome://inspect
• Debug logs: add --logFile=/tmp/cdp-mcp.log and DEBUG=* when filing issues

Security: don’t skip this

Chrome DevTools MCP exposes the entire browser to the MCP client. The agent reads DOM, cookies, localStorage, network payloads. Practical consequences:

• Don’t sign in with personal accounts on the profile you use with the agent. Use a dedicated work profile, or --isolated.
• Redact sensitive headers: --redactNetworkHeaders masks Authorization, Cookie, Set-Cookie before they reach the client.
• --remote-debugging-port is a public local port: any process on your machine can attach. Don’t enable it while browsing your bank.
• Disable telemetry if required: --no-usage-statistics or env CHROME_DEVTOOLS_MCP_NO_USAGE_STATISTICS=1. CI auto-disables when CI is set.
• Pin versions in CI: [email protected] instead of @latest to sidestep supply-chain surprises. See OWASP MCP Top 10 on tool description poisoning.

Enterprise guardrails

If your org has run a security review for Chrome DevTools MCP, it almost always lands on a set of mandatory conditions. Below is the most common version — it overlaps with the section above but is stricter and specific.

Required configuration (telemetry off, pinned version)

When running on a company machine, replace the @latest examples earlier in this post with this:

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": [
        "chrome-devtools-mcp@<pinned-version>",
        "--no-usage-statistics",
        "--no-performance-crux"
      ]
    }
  }
}

The two flags disable two separate telemetry channels: usage statistics, and the CrUX API calls that send performance-trace URLs to Google. Without them, both usage metadata and internal URLs can leak.

Conditions of use

1. Local developer machines only. No shared hosts, bastions, remote dev workspaces, or CI/CD. That means dropping the “CI performance budget” idea in the next section — keep it interactive on your laptop.
2. Non-production environments only. Local dev and testing; don’t point the agent at production URLs, production APIs, or real customer accounts.
3. Telemetry must be disabled: always --no-usage-statistics and --no-performance-crux.
4. Isolated Chrome profile. The server defaults to ~/.cache/chrome-devtools-mcp/chrome-profile — separate from your personal Chrome. For stronger isolation, add --isolated (ephemeral profile, wiped after each session). Avoid --autoConnect with profiles holding production credentials.
5. Pin the version, run npm audit. Do not use @latest. Pin to a reviewed version and npm audit before adopting a new one.
6. Keep Claude Code’s permission prompts. Mutating actions (click, fill, navigate_page, evaluate_script, …) must prompt for approval. Read-only actions (list_pages, get_console_message, list_network_requests) may auto-approve. Do not disable the prompts.

Productivity wins — from my workflow

A few ways Chrome DevTools MCP has compressed my cycle after a few weeks of daily use:

1. Visual-first PR review. Instead of pulling a branch locally, I have the agent open the preview URL (Vercel/Netlify), run Lighthouse on three key pages, and diff against a main baseline. Regression reports often catch a 40KB bundle bloat before a human notices.

2. Debugging flaky E2E. Playwright test flapping? The agent opens staging, replays that exact flow, captures console + network, cross-references the CI log. Finds race conditions, third-party timeouts, cross-domain cookie issues at a much higher hit rate than eyeballing trace files.

3. Migration audits. Webpack → Vite, framework majors. Snapshot performance across 10 critical URLs pre-migration, re-run post, diff. The agent writes the comparison table itself.

4. Hands-free bug repro. Vague customer report? Drop the URL + steps in chat, the agent reproduces, captures screenshot + console, files a fully-contextualized issue. My “open DevTools and fumble” tax dropped from 20 minutes to ~3.

5. Accessibility sweep. Run lighthouse_audit with accessibility + a DOM take_snapshot, ask the agent to list WCAG A/AA violations with CSS selectors. Feed straight into the a11y sprint backlog.

6. Performance budgets in CI. Combine --headless --isolated in pipelines; fail the build when LCP exceeds budget. Cheaper than a Lighthouse CI SaaS, and the same agent reviews the PR.

Last week’s actual numbers: one LCP regression (+400ms) caught pre-merge; two CORS fixes at ~5 minutes each instead of ~25; one flaky test turned deterministic after the agent pinpointed a race on navigator.serviceWorker.ready. Not magic — the agent finally sees what it’s fixing.

Seven canonical real-world applications

The six workflows above are mine. Chrome for Developers has published a set of canonical patterns teams have deployed successfully — worth keeping on your backlog when you’re looking for new places to introduce MCP:

Two patterns I find underrated: persistent styling — the agent picks up the hex values, spacing, and radii you tweaked in DevTools and commits them straight into the right @theme or token file — and reverse engineering to write client SDKs, especially useful when integrating with SaaS that only exposes a portal UI without public API docs.

Sources: Chrome for Developers — Chrome DevTools MCP for your AI agent and Let your Coding Agent debug your browser session.

Wrap: give the agent eyes, keep your hands on the wheel

Chrome DevTools MCP doesn’t replace your debugging instincts. It closes the gap between “agent guesses” and “agent verifies.” Install once, set --autoConnect plus --viewport, write prompts that force plan-before-fix — and you reclaim the dozens of minutes a day that used to drain into F12 + reload + squinting at the Network panel.

Tool reference, prompt templates, checklist — all above. The remaining hard part: break the habit of “fix CORS” prompts and replace them with contextually rich ones. The better the agent can see, the less you have to babysit.