Chrome Devtools MCP

Chrome DevTools MCP for .NET Repos

Trigger On

• the repo needs browser-level debugging for ASP.NET Core, Blazor, WebAssembly, or any .NET app with a web UI
• the user wants an MCP server that can inspect console output, network traffic, screenshots, traces, and DOM state
• the repo needs agent-friendly browser control instead of manual DevTools work

Do Not Use For

• pure .NET code analysis, unit testing, or NuGet/package management
• static HTML linting alone
• sensitive browser sessions that must not be exposed to an MCP client

Inputs

• the nearest AGENTS.md
• the MCP client config for the current agent or app
• the target Chrome mode: launch new, connect to existing browser, or attach to a WebSocket endpoint
• the target app URL or local dev server

Workflow

1. Choose the browser mode first.
   • new ephemeral browser: default when you want a clean session
   • existing browser: use --browserUrl or --wsEndpoint
   • running browser with a user profile: use --autoConnect only when Chrome 144+ and remote debugging are already enabled
2. Prefer repo-local config over ad hoc shell commands.
   • store the MCP server block in the repo or agent config so every run is repeatable
3. Start from the smallest useful surface.
   • use --slim when you only need navigation, JavaScript execution, and screenshots
   • leave the full toolset enabled when you need network, performance, or emulation
4. Be explicit about privacy and cost.
   • disable usage statistics or CrUX-backed performance enrichment when policy or sensitivity requires it
5. Validate against the real app, not a mock page.
   • use the app's local dev server, preview URL, or a production-like environment that reflects the bug

Current Upstream Notes

• Chrome DevTools MCP v1.8.0 adds PWA automation, query_heapsnapshot, richer heap-edge and native-context inspection, console stack traces, multi-file upload, and a stable-DOM bypass for evaluate_script. Enable memory-debugging tools explicitly and keep heap output bounded to the investigation.
• Page-scoped tools now require pageId by default. Update callers to select and pass the intended page instead of relying on ambient tab state. The release also fixes CLI default handling, remote-path validation, HiDPI screenshot bounds, slow-client root listing, and lifecycle regressions; reproduce the real browser path before adding client-side workarounds.
• Use the memory tools only when heap snapshots are the actual debugging need; close snapshots when finished so the browser session does not keep unnecessary memory pressure.
• For sensitive or scoped browser automation, prefer allowedUrlPattern / blockedUrlPattern over relying only on prompt instructions.
• When enabling category extensions, prompt the user for the category instead of silently broadening the tool surface.

Install And Configure

Use the same JSON MCP server block in whatever .NET agent/app host you use:

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

Common variants:

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

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

For Codex CLI, the upstream repo documents:

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

Useful Flags

• --slim: three-tool surface for navigation, JavaScript execution, and screenshots only
• --headless: run without UI
• --browserUrl or --wsEndpoint: attach to an existing debuggable browser
• --wsHeaders: add custom WebSocket headers when --wsEndpoint is used
• --autoConnect: connect to a locally running Chrome 144+ instance instead of launching a new one
• --channel stable|beta|dev|canary: pick a Chrome channel
• --isolated: create and clean up a temporary profile
• --userDataDir: reuse a specific Chrome profile directory
• --no-usage-statistics: opt out of usage collection
• --no-performance-crux: stop sending performance trace URLs to CrUX
• --acceptInsecureCerts: only when the target environment uses self-signed or expired certs
• --allow-unrestricted-paths: opt out of filesystem path restrictions only for a trusted local workflow that genuinely needs arbitrary path access
• --logFile <path>: capture debug logs for bug reports
• --experimentalScreencast: only when ffmpeg is available and you need video capture

Practical Usage Patterns

• Debug a local ASP.NET Core or Blazor app:
  • start the app
  • connect with --browserUrl if the browser is already running, or let the server launch Chrome
  • ask the agent to inspect console errors, network failures, and rendering behavior
• Investigate a flaky UI test:
  • use --headless --isolated
  • capture screenshots and console logs from the failing route
  • compare the result to a known-good run
• Diagnose performance regressions:
  • keep the full toolset enabled
  • use performance tools only when you need trace data
  • prefer --slim for quick smoke checks, not for performance work
• Work in a sandboxed or containerized environment:
  • attach to a running browser with --browserUrl or --wsEndpoint
  • avoid assuming the server can launch Chrome itself
• Reuse a signed-in session:
  • use --userDataDir
  • avoid --isolated
  • accept that this increases exposure to sensitive browser state

flowchart LR
  A[".NET repo or app"] --> B["MCP-capable agent/app"]
  B --> C["chrome-devtools-mcp config"]
  C --> D["Chrome"]
  D --> E["Console / network / screenshots / traces"]

Risks And Tradeoffs

• The server can see and act on browser content, so do not point it at sensitive accounts or data unless that exposure is intended.
• --slim lowers token and tool overhead, but it removes network, performance, and emulation workflows.
• --isolated is safer for disposable runs, but it discards existing browser state and logins.
• --autoConnect is convenient for local debugging, but it depends on Chrome 144+ and remote debugging being enabled.
• --no-usage-statistics and CrUX-backed performance traces may change what data leaves the machine; disable them when policy requires it.
• --headless is good for CI or scripted runs, but it can hide UI-specific failures.
• Passing --chromeArg='--no-sandbox' or similar launch flags can be necessary in some container or root environments, but only use it when the environment really requires it.

Handle Failures

• If npx returns a permission denied error on macOS from _npx, clear ~/.npm/_npx and rerun.
• If the server cannot find Chrome, check --channel, --executablePath, and whether Chrome is installed on the host.
• If connection to an existing browser fails, verify http://127.0.0.1:9222/json/version and the webSocketDebuggerUrl value.
• If performance traces are noisy or too expensive, keep the browser mode stable and compare runs against the same URL and browser channel.

Validate

• npx -y chrome-devtools-mcp@latest --help prints the expected flags on the current host
• the MCP client can list the server and open a page in the target browser
• the agent can capture at least one screenshot or console/network observation from the real app
• the chosen mode matches the task: --slim for quick browser checks, full mode for debugging and performance

Deliver

• a repeatable MCP server config for the repo or agent host
• a browser connection mode that fits the environment
• a safe default for privacy, performance, and reproducibility