Chrome DevTools MCP Setup: Debug With a Separate Browser Profile
Run Chrome DevTools MCP with a dedicated or isolated Chrome profile, verify page and console reads first, and fence URLs before enabling traces, heap inspection, evaluation, or an attached signed-in browser. This keeps browser state understandable while still supporting performance, network, console, and memory-debugging workflows.
Run Chrome DevTools MCP with a dedicated or isolated Chrome profile, verify page and console reads first, and fence URLs before enabling traces, heap inspection, evaluation, or an attached signed-in browser. This keeps browser state understandable while still supporting performance, network, console, and memory-debugging workflows.
Table of contents
- What Chrome DevTools MCP exposes
- Choose launched Chrome or an attached browser
- Install the local stdio server
- Verify pages, console, network, and performance reads
- Fence browser state, URLs, telemetry, and evaluation
- Fix Chrome discovery, login, port, and profile errors
- FAQ
What Chrome DevTools MCP exposes
Chrome DevTools MCP gives an agent browser inspection and debugging tools through a local Node process over stdio. Begin with a dedicated or isolated profile, confirm page and console reads, then add traces, heap inspection, evaluation, or an attached signed-in browser.
The server starts stable-channel Chrome only when the first browser-dependent tool is called, not when the MCP connection is created. Its persistent profile is stored under ~/.cache/chrome-devtools-mcp/; --isolated selects a throwaway profile. This affects cookies, local storage, extensions, and other retained state. See the Chrome DevTools MCP directory page for the practical setup summary.
Automation uses Puppeteer and waits for action results automatically, which produces fewer flaky interactions than raw CDP scripting. The MCP architecture is still client-server based: a client connects to a server, and the server exposes tools operating on the controlled browser. The MCP architecture guide explains that boundary.
The tool surface includes source-mapped console stack traces, request-level network inspection, and performance analysis. It can record a DevTools trace, retrieve insights such as LCP breakdown and render-blocking information, run Lighthouse audits, and optionally add real-user CrUX field data. An 11-tool heap-snapshot suite supports memory-leak investigation. Confirm advanced options in the official configuration documentation.
Choose launched Chrome or an attached browser
Use launched Chrome with a dedicated or isolated profile for routine debugging. Use an attached browser with --browser-url only when a normally started Chrome session is required, such as when a site blocks sign-in for a WebDriver-launched browser.
A launched profile is easier to separate from everyday browsing. Use a persistent dedicated profile when development state should remain between runs, or --isolated for a clean, temporary profile. An attached browser can preserve an existing session, but it also exposes that browser’s pages, logged-in sessions, and network traffic to the MCP client.
| Situation | Choice |
|---|---|
| Repeatable development debugging | Dedicated launched profile |
| Clean reproduction | --isolated |
| WebDriver sign-in is blocked | Attached Chrome with --browser-url |
| Concurrent subagents need separate tabs | --experimentalPageIdRouting |
| Sensitive account access | Do not use the automated profile |
Do not open personal email, banking, administrative, or similar sensitive accounts in the controlled browser. For broader browser-automation context, see the browser automation capability guide.
Install the local stdio server
Install the local server with npx -y chrome-devtools-mcp@latest, then connect your MCP client to that stdio process. You need Node.js LTS, current stable Google Chrome or Chrome for Testing, and npm or npx available on your PATH.
npx -y chrome-devtools-mcp@latest
The transport is stdio and authentication is not required for this local connection. A successful MCP connection does not prove that Chrome discovery or page access works, because the browser starts only when a browser-dependent tool is called.
For a throwaway profile, use:
npx -y chrome-devtools-mcp@latest --isolated
Add only the options required by the task. The configuration surface includes --headless, --viewport, --channel, proxy settings, URL allow and block patterns, screenshot format and size caps, and --experimentalPageIdRouting. Validate a more complex configuration with the MCPtrove config validator, and consult the MCP repository for current implementation details.
Verify pages, console, network, and performance reads
Verify a page read and a console read before using traces, heap snapshots, evaluation, or signed-in sessions. Then test network inspection and performance analysis separately so each failure points to a smaller set of causes.
Use this sequence:
- Start the stdio server with the default or isolated profile.
- Open a non-sensitive target page.
- Confirm the expected document can be read.
- Confirm console output and source-mapped stack information can be read.
- Inspect a request or response at the network level.
- Record a trace or run a Lighthouse audit.
- Only afterward consider heap inspection or evaluation.
This order separates browser discovery, page control, console access, network access, and performance tooling. If the page read fails, a trace will not clarify the cause. If page and console reads work but network inspection fails, focus on the target request and browser state before changing unrelated settings.
Trace-derived insights, Lighthouse results, and CrUX field data answer different questions. A trace describes the inspected run; CrUX adds collected real-user observations. The MCP debugging guide provides additional protocol-level troubleshooting context.
Fence browser state, URLs, telemetry, and evaluation
Fence the browser with a separate profile, URL restrictions, and an explicit telemetry decision before using advanced tools. Treat every page, logged-in session, and network request inside the controlled browser as exposed to the MCP client.
Use a dedicated profile or --isolated to control retained state. Persistent profiles can preserve cookies and local storage between runs, which may be useful for development but can also carry access into a later task. URL boundaries can be set with --allowedUrlPattern and --blockedUrlPattern; use them when navigation should remain within known domains or paths.
Usage statistics and CrUX lookups are enabled by default, and both can be turned off. Usage statistics can be disabled with --no-usage-statistics. Decide separately whether CrUX enrichment is needed, because field data and local trace analysis serve different purposes.
Treat evaluation and heap inspection as later-stage capabilities. Evaluation operates in page context, while heap snapshots may expose application data held in memory. Do not attach a signed-in browser unless its wider exposure is necessary and understood. The MCP security best practices and MCPtrove security guide provide useful boundary-setting guidance.
Fix Chrome discovery, login, port, and profile errors
Fix errors by isolating the layer involved: verify Chrome discovery, then profile selection, login behavior, and remote-debugging access. Change one option at a time so each result remains interpretable.
| Symptom | Focus | Action |
|---|---|---|
| Chrome does not start | Installation or channel | Confirm Chrome or Chrome for Testing; review --channel |
| No page opens after connection | Browser startup timing | Call a tool that needs the browser |
| Login is rejected | WebDriver sign-in block | Use a normally started browser with --browser-url |
| Unexpected cookies or state | Persistent profile | Retry with --isolated |
| Tabs interfere across workers | Page routing | Consider --experimentalPageIdRouting |
| Local control behaves unexpectedly | Debugging-port exposure | Check which local processes can reach it |
Chrome DevTools MCP officially supports Google Chrome and Chrome for Testing only. Also confirm Node.js LTS and npm or npx are available on PATH. If a profile contains unwanted state or appears locked, stop using it for the task and retry with --isolated.
A remote-debugging port is a control boundary: any local process that can reach it may control the browser. Do not expose it broadly or treat it as an authentication mechanism. Chrome’s remote-debugging security explanation describes why attaching to an existing browser can require a normally started instance and an explicit browser URL.
If the server connects but browser tools fail, review the MCP client’s tool configuration and logs using the protocol debugging guidance. Avoid adding unrelated browser flags until the failing layer is clear.