The requirements: an LTS version of Node.js, a current stable Chrome or newer, and npm.

Popular clients have ready-made commands:

Claude Code has a second route - install it as a plugin, together with the skills that teach the agent how to use these tools:

After installing, restart the client and check with /skills that the skills loaded. If plugin installation fails on cloning the repository - a familiar story behind a corporate firewall - the troubleshooting guide suggests falling back to the CLI installation, while warning that you then get the server alone, without the bundled skills.

To confirm everything works, the authors offer a single prompt:

And they immediately note the thing that otherwise looks broken: the browser does not start when the server connects. It starts on the first call to a tool that actually needs it.

How the Agent Works With a Page

The order of operations is strict, and the project's skill spells it out: navigate, wait for what you need, take a snapshot, act on the snapshot.

The snapshot is take_snapshot. It returns the page structure, where every element carries a uid. All subsequent actions address that identifier: click with a uid, fill with a uid. If an element is not found, the skill says take a fresh snapshot: the page may have changed.

The second address is pageId. Page-scoped tools require it explicitly so that several agents or subagents sharing one server do not confuse tabs. list_pages returns the open pages, and a new page returns its identifier when created. The behaviour is on by default; --no-page-id-routing turns it off and the tools then act on the currently selected page.

The third thing worth remembering is wait_for. It removes the guesswork about whether the page has finished rendering, provided you know what you are waiting for.

The Tools

There are many, and holding the categories in your head beats memorising the list.

At the time of checking the reference lists fifty-seven tools, but that number moves: categories keep arriving, and memory has grown noticeably over recent releases. Trust the reference in the repository rather than a figure in an article.

Some categories are off by default and switch on with flags: extensions with --categoryExtensions, memory work with --memoryDebugging, progressive web apps with --categoryPwa. The first and the third carry a limitation: they only work over a direct connection to the browser and are incompatible with attaching to an already running Chrome.

When There Are Too Many Tools

Fifty-seven tool descriptions are a noticeable slice of context in every request. If you need the browser for simple things, the project has an economy mode:

It leaves three tools: navigation, script evaluation and screenshots. For "open the page and show me how it looks" that is enough, and the context stays small.

The second way to save is the screenshot format. The README notes that JPEG and WebP are roughly three to five times smaller than PNG and offers this as a way to reduce context size:

How exact that figure is remains open: the image set, the resolution and the encoder settings are not given in the README. The direction is right; the actual multiplier depends on your pages.

The third way is the most direct: screenshots, snapshots and traces can be written to a file by passing filePath rather than dumped into the conversation. The project's skill recommends exactly that.

The Browser Profile and Its State

By default the server launches Chrome with a profile of its own that persists between runs:

For non-stable channels the channel name is appended - chrome-profile-canary and the like. The profile is not cleared between runs and gets reused, and only one browser can hold it at a time.

If you want a clean slate each run, --isolated provides it: a temporary directory that is removed after the browser closes. It also resolves the clash where several independent client sessions try to claim the same profile.

Attaching to a Running Chrome

A dedicated profile does not suit every case, and the README lists three where you want your own browser: when you want the same state across manual and agent-driven testing; when a site refuses a sign-in in a browser driven by WebDriver; and when the model runs inside a sandbox while Chrome lives outside it.

There are two ways. The automatic one is available from Chrome 144: enable remote debugging in the browser through chrome://inspect/#remote-debugging and pass the server a flag:

The second way is to start Chrome yourself with a remote debugging port and give the server the address through --browser-url. And here the README does not soften the wording: any application on your machine can connect to that port and drive the browser. An open debugging port is an open door, not a configuration detail.

If attaching to a running browser hangs on timeouts, the troubleshooting guide gives a short list: Chrome 144 or newer already running, remote debugging enabled, the connection prompt accepted, and no second tool competing for the same port. The same page carries a warning that explains part of the mysterious hangs: the server forces all tabs to load, so using it with a browser holding hundreds of tabs is explicitly not recommended.

The Command Line Without MCP

The package ships a second, experimental half - the same tools available from the terminal. Useful when the agent should write an automation script rather than call tools one at a time.

It works as a client to a background daemon: Unix sockets on Linux and macOS, named pipes on Windows. The first tool call starts both the daemon and the browser; after that the state - open tabs, cookies - survives between commands.

Required arguments are positional, optional ones are flags, and page-scoped tools take the page identifier first. By default the daemon runs headless and isolated unless a user data directory is supplied.

The limitation is documented plainly: the CLI only supports tools that need no extra server arguments. Extension tools are not available through it.

What Leaves Your Machine

Three things worth knowing in advance.

The browser's contents are visible to the client. The very first disclaimer in the README says the server exposes the browser's content to MCP clients and lets them inspect, debug and modify any data in the browser or DevTools. The advice on the same line: do not keep anything in that browser you are not prepared to share with the client.

Performance tools call a Google API. Traces may send page URLs to CrUX so that field data from real users can sit next to your lab measurements. It is switched off with --no-performance-crux.

Usage statistics are collected by default. Google gathers data on tool invocations, latency and environment. The README stresses that this is not the same as Chrome's own metrics: opting out of one does not opt you out of the other. It is disabled in three ways - the --no-usage-statistics flag, the CHROME_DEVTOOLS_MCP_NO_USAGE_STATISTICS variable, or simply having CI set.

Separately but in the same vein: the server periodically checks the npm registry for updates. That is turned off with CHROME_DEVTOOLS_MCP_NO_UPDATE_CHECKS.

When Something Does Not Work

The general advice in the guide is short and practical: run npx chrome-devtools-mcp@latest --help and confirm the server starts at all; check that your client uses the same Node and npm as your terminal; add --yes to npx so you are not waiting on an install prompt; find the specific error in the server's output - in editor clients it usually lands in the output pane.

For a verbose log, both switches go on together:

Among the specific cases the documentation covers running under WSL, debugging between a virtual machine and its host, operating system sandboxes, a Windows 10 problem with the connection closing, and a Chrome crash on macOS when a Web Bluetooth prompt appears.

Mistakes of the First Encounter

Expecting the browser to open on connection. It starts on the first call to a tool that needs it. An empty screen is not a fault.

Leaving every category enabled. Fifty-seven tool descriptions ride along in every request. If you need navigation and a screenshot, --slim offers three.

Forgetting that extensions and PWAs do not work over every connection. Both categories require a direct connection and are incompatible with attaching to a running Chrome.

Opening a remote debugging port and forgetting about it. Any application on the machine can connect to it.

Working in a browser with hundreds of tabs. The server forces them all to load, and the connection runs into a timeout.

Dumping screenshots into the conversation. That is what filePath is for, and WebP or JPEG instead of PNG for the size.

Assuming any Chromium will do. Chrome and Chrome for Testing are officially supported; the rest is at your own risk.

Not noticing that statistics are on. Collection is enabled by default and has to be switched off explicitly.

To put it in one sentence: Chrome DevTools MCP closes the feedback loop - the agent can finally look at what it made - and the whole setup comes down to giving it exactly as many tools and exactly as much access as the task needs.

Sources

This article was checked against the ChromeDevTools/chrome-devtools-mcp repository (branch main) and the official documentation on 25 August 2026: the README, package.json, the tool reference, the CLI guide, the troubleshooting guide and the chrome-devtools skill. The tool set and the flag defaults change from release to release - the reference in the repository is more reliable than any article.

• GitHub: ChromeDevTools/chrome-devtools-mcp
• Tool reference
• Slim mode tool reference
• The command line
• Troubleshooting guide
• Design principles
• The chrome-devtools skill
• Changelog
• Chrome for Testing
• Chrome User Experience Report