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
- 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
- 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
- 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
- Be explicit about privacy and cost.
- disable usage statistics or CrUX-backed performance enrichment when policy or sensitivity requires it
- 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>: opt-in debug artifact for an unresolved bug; keep it size-bounded outside model context and inspect only exact bounded excerpts
--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
- link screenshots and show only relevant Warning/Error console entries from the failing route (at most 80 lines / 8 KiB per diagnostic response); never dump console history
- 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
1---2name: chrome-devtools-mcp3description: "Use Chrome DevTools MCP from .NET agents and .NET-focused repos to inspect, debug, and automate Chrome through an MCP client. USE FOR: 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. DO NOT USE FOR: pure .NET code analysis, unit testing, or NuGet/package management; static HTML linting alone. INVOKES: inspect the repository context, edit targeted files, and run relevant build, test, lint, or validation commands when changes are made."4compatibility: "Requires an MCP-capable .NET agent/app or repo with a browser-debugging workflow; Chrome DevTools MCP runs as an external Node-based server and needs Chrome or Chrome for Testing."5metadata:6 source: https://skillmd.com/skills/managedcode/chrome-devtools-mcp7---89# Chrome DevTools MCP for .NET Repos1011## Trigger On1213- the repo needs browser-level debugging for ASP.NET Core, Blazor, WebAssembly, or any .NET app with a web UI14- the user wants an MCP server that can inspect console output, network traffic, screenshots, traces, and DOM state15- the repo needs agent-friendly browser control instead of manual DevTools work1617## Do Not Use For1819- pure .NET code analysis, unit testing, or NuGet/package management20- static HTML linting alone21- sensitive browser sessions that must not be exposed to an MCP client2223## Inputs2425- the nearest `AGENTS.md`26- the MCP client config for the current agent or app27- the target Chrome mode: launch new, connect to existing browser, or attach to a WebSocket endpoint28- the target app URL or local dev server2930## Workflow31321. Choose the browser mode first.33 - new ephemeral browser: default when you want a clean session34 - existing browser: use `--browserUrl` or `--wsEndpoint`35 - running browser with a user profile: use `--autoConnect` only when Chrome 144+ and remote debugging are already enabled362. Prefer repo-local config over ad hoc shell commands.37 - store the MCP server block in the repo or agent config so every run is repeatable383. Start from the smallest useful surface.39 - use `--slim` when you only need navigation, JavaScript execution, and screenshots40 - leave the full toolset enabled when you need network, performance, or emulation414. Be explicit about privacy and cost.42 - disable usage statistics or CrUX-backed performance enrichment when policy or sensitivity requires it435. Validate against the real app, not a mock page.44 - use the app's local dev server, preview URL, or a production-like environment that reflects the bug4546## Current Upstream Notes4748- 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.49- 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.50- 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.51- For sensitive or scoped browser automation, prefer `allowedUrlPattern` / `blockedUrlPattern` over relying only on prompt instructions.52- When enabling category extensions, prompt the user for the category instead of silently broadening the tool surface.5354## Install And Configure5556Use the same JSON MCP server block in whatever .NET agent/app host you use:5758```json59{60 "mcpServers": {61 "chrome-devtools": {62 "command": "npx",63 "args": ["-y", "chrome-devtools-mcp@latest"]64 }65 }66}67```6869Common variants:7071```json72{73 "mcpServers": {74 "chrome-devtools": {75 "command": "npx",76 "args": ["-y", "chrome-devtools-mcp@latest", "--slim", "--headless"]77 }78 }79}80```8182```json83{84 "mcpServers": {85 "chrome-devtools": {86 "command": "npx",87 "args": ["-y", "chrome-devtools-mcp@latest", "--browserUrl", "http://127.0.0.1:9222"]88 }89 }90}91```9293For Codex CLI, the upstream repo documents:9495```bash96codex mcp add chrome-devtools -- npx chrome-devtools-mcp@latest97```9899### Useful Flags100101- `--slim`: three-tool surface for navigation, JavaScript execution, and screenshots only102- `--headless`: run without UI103- `--browserUrl` or `--wsEndpoint`: attach to an existing debuggable browser104- `--wsHeaders`: add custom WebSocket headers when `--wsEndpoint` is used105- `--autoConnect`: connect to a locally running Chrome 144+ instance instead of launching a new one106- `--channel stable|beta|dev|canary`: pick a Chrome channel107- `--isolated`: create and clean up a temporary profile108- `--userDataDir`: reuse a specific Chrome profile directory109- `--no-usage-statistics`: opt out of usage collection110- `--no-performance-crux`: stop sending performance trace URLs to CrUX111- `--acceptInsecureCerts`: only when the target environment uses self-signed or expired certs112- `--allow-unrestricted-paths`: opt out of filesystem path restrictions only for a trusted local workflow that genuinely needs arbitrary path access113- `--logFile <path>`: opt-in debug artifact for an unresolved bug; keep it size-bounded outside model context and inspect only exact bounded excerpts114- `--experimentalScreencast`: only when ffmpeg is available and you need video capture115116## Practical Usage Patterns117118- Debug a local ASP.NET Core or Blazor app:119 - start the app120 - connect with `--browserUrl` if the browser is already running, or let the server launch Chrome121 - ask the agent to inspect console errors, network failures, and rendering behavior122- Investigate a flaky UI test:123 - use `--headless --isolated`124 - link screenshots and show only relevant Warning/Error console entries from the failing route (at most 80 lines / 8 KiB per diagnostic response); never dump console history125 - compare the result to a known-good run126- Diagnose performance regressions:127 - keep the full toolset enabled128 - use performance tools only when you need trace data129 - prefer `--slim` for quick smoke checks, not for performance work130- Work in a sandboxed or containerized environment:131 - attach to a running browser with `--browserUrl` or `--wsEndpoint`132 - avoid assuming the server can launch Chrome itself133- Reuse a signed-in session:134 - use `--userDataDir`135 - avoid `--isolated`136 - accept that this increases exposure to sensitive browser state137138```mermaid139flowchart LR140 A[".NET repo or app"] --> B["MCP-capable agent/app"]141 B --> C["chrome-devtools-mcp config"]142 C --> D["Chrome"]143 D --> E["Console / network / screenshots / traces"]144```145146## Risks And Tradeoffs147148- The server can see and act on browser content, so do not point it at sensitive accounts or data unless that exposure is intended.149- `--slim` lowers token and tool overhead, but it removes network, performance, and emulation workflows.150- `--isolated` is safer for disposable runs, but it discards existing browser state and logins.151- `--autoConnect` is convenient for local debugging, but it depends on Chrome 144+ and remote debugging being enabled.152- `--no-usage-statistics` and CrUX-backed performance traces may change what data leaves the machine; disable them when policy requires it.153- `--headless` is good for CI or scripted runs, but it can hide UI-specific failures.154- 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.155156## Handle Failures157158- If `npx` returns a permission denied error on macOS from `_npx`, clear `~/.npm/_npx` and rerun.159- If the server cannot find Chrome, check `--channel`, `--executablePath`, and whether Chrome is installed on the host.160- If connection to an existing browser fails, verify `http://127.0.0.1:9222/json/version` and the `webSocketDebuggerUrl` value.161- If performance traces are noisy or too expensive, keep the browser mode stable and compare runs against the same URL and browser channel.162163## Validate164165- `npx -y chrome-devtools-mcp@latest --help` prints the expected flags on the current host166- the MCP client can list the server and open a page in the target browser167- the agent can capture at least one screenshot or console/network observation from the real app168- the chosen mode matches the task: `--slim` for quick browser checks, full mode for debugging and performance169170## Deliver171172- a repeatable MCP server config for the repo or agent host173- a browser connection mode that fits the environment174- a safe default for privacy, performance, and reproducibility