How to Install Chrome DevTools MCP: Debug Web Network, Console, and Performance with Codex and Claude Code

Sun, 12 Jul 2026 12:13:00 +0800

Chrome DevTools MCP is not a tool for letting an agent casually “click around a website.” It exposes Chrome DevTools capabilities—network requests, console messages, screenshots, performance traces, and page automation—to coding agents through MCP. It is better suited to verifiable questions such as “Why is the page blank?”, “Why does the API return 401?”, “Why does nothing happen after a click?”, or “Why did performance suddenly slow down?”

Use it together with How to troubleshoot failed MCP tool calls: first make sure the MCP process and permissions work, then inspect evidence from the browser. The official repository describes support for live Chrome inspection, automation, debugging, and performance analysis, and explicitly warns that an MCP client can access browser data. Official repository

Confirm the use case first

It is a good fit when:

An agent needs console errors, network requests, screenshots, or a performance trace.
You need to reproduce a frontend problem already visible in Chrome.
You need to turn page behavior into actionable requests, selectors, or stack traces.
Your test site and account are isolated from production.

Do not treat it as an unattended production operator. A browser can contain sessions, customer data, payment pages, or internal systems. Start with a separate Chrome profile and a low-privilege test account.

Minimal setup for Codex and Claude Code

Add the MCP server in Codex CLI:

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

For Claude Code, use:

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

Restart the relevant client after installation, then ask the agent to perform a low-risk check, such as: “Open the test page and list console errors and failed network requests.” Do not begin with tasks like “log in to the admin panel and modify data.”

If Windows cannot find Chrome after npx starts, or MCP initialization is slow, explicitly use cmd and increase the timeout in .codex/config.toml:

[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

Debug from evidence instead of asking the agent to guess

Use this fixed order:

Page and screenshot: confirm the target environment, account, and route are open.
Console: capture the full text and source-mapped stack of the first error, not merely the number of red entries.
Network: filter for 4xx, 5xx, CORS, and long-pending requests; inspect the URL, request body, and response summary.
Reproduce one interaction: have the agent perform only one click or input, then inspect network and console again.
Performance: record a trace only after the issue reproduces reliably, so transient network jitter is not mistaken for rendering trouble.

You can give the agent a tightly scoped request:

Reproduce “the page is blank after submission” only at http://localhost:3000.
Take a screenshot first, then list console errors and failed network requests.
Do not modify the page, submit the form, or visit other domains.
Organize the output as: symptom, evidence, most likely cause, and next manual check.

Common failures and responses

Symptom	Check first
MCP was added but its tools are unavailable	Restart the client; confirm `npx`, Node.js, and the MCP configuration are active in the current scope.
Cannot connect to an existing Chrome instance	Confirm the debug port matches `--browser-url`; do not assume the tool automatically takes over an already-open browser.
The agent saw data it should not see	Close that profile immediately, switch to an isolated test profile, and narrow the agent task.
Performance reports fluctuate	Fix the page, network conditions, and reproduction steps; compare multiple samples.

By default, the official tool collects usage data such as tool-call success rate, latency, and environment information. If your environment requires it, pass --no-usage-statistics. Performance analysis can also read CrUX data; use --no-performance-crux when appropriate. These are not debugging failures, but privacy and network boundaries to decide before rollout.

Summary