Chrome DevTools for Agents

The package also ships a chrome-devtools command that exposes the same tools to a shell, without MCP. It keeps a background server between commands, so a script can chain calls and the agent pays for one shell command rather than for many tool definitions in its context:

Source: chrome-devtools-mcp README, CLI

The chrome-devtools --help listing of the installed 1.12.0 package was read and shows the same tool names as commands (start, status and stop manage the background server); the example above is from the README and was not run.

For repeatable work, such as an agent that verifies a change, use --headless --isolated. Without --isolated the default profile is shared by every server instance and reused between runs, which is convenient for staying signed in and harmful for reproducing a bug that depends on a clean state. The configuration used for every run on this page was:

Source: Chrome DevTools MCP, Configuration

(The runs started the locally installed chrome-devtools-mcp binary of that version with the same four flags, rather than through npx.) The two --no- flags are explained under Privacy: usage statistics and field data.

By default the agent gets its own Chrome with its own profile. That is the wrong shape in three situations: when a page needs a login that a controlled browser may be refused, when you want to switch between testing by hand and testing by an agent in the same state, and when the agent runs in a sandbox but Chrome runs outside it. Two ways of connecting exist.

Automatic connection (--autoConnect, Chrome 144 or later) targets the Chrome you already have open. Open chrome://inspect/#remote-debugging once to enable remote debugging, then configure the server:

Source: Chrome DevTools MCP, Advanced usage

Chrome has to be running already (the flag never launches it). Each time the server asks for a debugging session Chrome shows a permission dialog and the session starts only when you click Allow; while it is active Chrome shows a banner that it is being controlled by automated test software. With several profiles the server uses the default one, and it can see all open windows of that profile. Before 144 reached the stable channel the Chrome team’s announcement also needed --channel=beta; with --channel the server looks for the browser of that channel.

Manual connection (--browserUrl) targets a Chrome you started with a remote debugging port. Chrome requires a non-default user data directory when that port is enabled:

Source: Chrome DevTools MCP, Advanced usage

and pass --browser-url=http://127.0.0.1:9222 to the server. The debugging port is open to every process on the machine, so any local application can control that browser; do not browse sensitive sites while it is enabled. Neither connection mode was run here: the automatic mode needs a person to click the Chrome permission dialog, and the manual mode needs a second Chrome instance on the host. Both are documented from the official guides.

When one server instance is shared by several agent sessions, --pageIdRouting (on by default) makes every page-scoped tool require a numeric pageId, so each session routes to its own tab. That is why every call in the examples below carries pageId. Pages are numbered from 1 in the order list_pages returns them, and new_page adds a page without closing the initial about:blank page, so the new tab has pageId 2; the first attempt to run the example in the next section on pageId 1 after new_page inspected the blank page and returned nothing, which is what an agent that does not re-read the list_pages result also experiences.

The most common use of the server is the first thing a developer does in DevTools: load the page and look at the Console and Network panels. This sequence ran on the Bookshelf URL of a book that does not exist:

Source: Chrome DevTools MCP, Tool reference

(The prompt is the one the sequence answers; the calls were issued by hand, as described in the introduction, and the output is trimmed with ....) Three points matter for how an agent should use these tools. The console list reports messages by msgid and the network list by reqid, and the detail tools take those ids, which keeps the first listing short; pageSize and pageIdx paginate large logs. The server keeps console messages and requests for the last three navigations of each page (--maxNavigationSaved, from 1 to 25), so an error logged before an earlier reload is reachable only with includePreservedMessages or includePreservedRequests. And headers can contain secrets: pass --redactNetworkHeaders when the transcript will be stored or shared.

The same server also answers the question that Playwright MCP covers with browser_console_messages and browser_network_requests; the difference is that here the stack traces are source-mapped (a minified bundle error points to the original file) and a request’s body and headers can be written to a file with requestFilePath and responseFilePath for tools that should not read them inline.

performance_start_trace records a DevTools performance trace. With reload: true it reloads the page first, and with autoStop: true it stops by itself after the page load, so a single call returns the analysis. Without autoStop the agent interacts with the page and calls performance_stop_trace. filePath saves the raw trace (a .json or .json.gz file you can open in the DevTools Performance panel later). On Bookshelf:

Source: Chrome DevTools, Performance insights

This run used port 3971 for Bookshelf (a different local port from the sequence above) and was trimmed. The numbers belong to a tiny local page with no throttling; they show how to read the output, not a performance budget. The reading is the useful part: of 188 ms of LCP, 184 ms is render delay, the time between the resource being loaded and the element being painted, not network time. An agent that is told "optimise LCP" would otherwise guess at images.

The summary has three kinds of data. Lab metrics (LCP, CLS and, with interaction, INP) come from the trace itself. Field metrics come from the Chrome User Experience Report (CrUX), real-user data collected by Chrome, which the tool fetches for the page URL or origin so lab and field numbers appear side by side; for a localhost page there is none, hence the n/a line. Insights are named analyses (LCP breakdown, render-blocking requests, network dependency tree, document latency, cache use and others) that the agent can drill into with performance_analyze_insight.

A trace gets very large, so the tool returns a summary and the agent asks for details. A file path outside the allowed directories is refused: a filePath outside the configured roots returns Access denied: path ... is not within any of the configured workspace roots. When the MCP client does not offer the MCP "roots" capability the server limits file-reading and file-writing tools to the operating system temporary directory; add --filesystemRoot <dir> (also written --workspace) for each directory the agent may use, or --allowUnrestrictedPaths to remove the restriction, which should be a deliberate decision.

Throttling matters because a fast development machine hides what users on phones see. Combine the trace with emulate (next section) before recording, and the summary header then reports "CPU throttling: 4x" and the network preset.

emulate replaces all emulation settings on a page in one call, except extra HTTP headers; pass every setting you want every time. Settings survive navigations in the same page, as the next run shows:

Source: Chrome DevTools MCP, Tool reference

Two real behaviours are visible. The viewport is a compact string, <width>x<height>x<deviceScaleFactor> followed by optional mobile, touch and landscape flags. And networkConditions has no value meaning "none": in 1.12.0 the enumeration is Offline, Slow 3G, Fast 3G, Slow 4G and Fast 4G, so the instruction "turn throttling off" fails validation; the CPU rate is set back with cpuThrottlingRate: 1. The Lighthouse run in the next example shows the other consequence: the throttling stayed active, so it ran on the emulated phone. Reset by omitting networkConditions or by opening a fresh page. resize_page changes only the window size. Geolocation, userAgent, forcedColors, prefersContrast and prefersReducedMotion are further emulate parameters, useful for accessibility checks that the accessibility chapter automates with axe.

lighthouse_audit runs Lighthouse against the selected page. mode is navigation (reloads the page) or snapshot (audits the current state, which suits a page in the middle of a flow), device is desktop or mobile, and outputDirPath saves the reports. It does not run the performance category, which is the job of the trace tools:

Source: Lighthouse overview

The audit found three real findings in Bookshelf: a heading level skipped (an h3 card title directly under the h1), no meta description, and a disabled "Previous" link that has no href. They are small, but each is specific enough that an agent can open the source and fix it. Note the fourth category, "Agentic Browsing": current Lighthouse versions include a category that checks how well a page can be used by browsing agents, and it scored 100 here. Whether the scoring of that category stays as it is will depend on later Lighthouse releases. Lighthouse’s own accessibility category is a subset of what axe-core finds, which is why the 98 above and a dedicated axe run in a test (see Accessibility Checks in E2E Tests) complement rather than replace each other.