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

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
• --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