Chrome DevTools MCP: Browser Debugging for AI Agents

What Chrome DevTools MCP is

Chrome DevTools MCP, published on npm as chrome-devtools-mcp and branded in its README as "Chrome DevTools for agents", gives a coding agent a live Chrome browser to drive and inspect. The README names Antigravity, Claude, Cursor and Copilot as examples of agents that can use it. It ships in two forms from the same package: a Model Context Protocol (MCP) server that an agent connects to over stdio, and a chrome-devtools command-line tool that calls the same tools from a terminal without MCP. Both expose what the README calls "the full power of Chrome DevTools for reliable automation, in-depth debugging, and performance analysis."

The problem it addresses is familiar to anyone who has asked an agent to fix a front-end bug. A model that edits code but cannot see the running page has to guess at console errors, failed requests and layout problems. With this server attached, the agent can open the page, read the console with source-mapped stack traces, list network requests, record a performance trace, run a Lighthouse audit and click through a flow, then report what it found. The project is maintained under the ChromeDevTools organisation on GitHub, licensed Apache-2.0 and written in TypeScript, with documentation hosted on developer.chrome.com.

The audience is developers who already use an MCP-capable editor or agent and want that agent to verify its own front-end work, and teams building agent products who need a browser component. The README says directly that tool builders who want "an integrated browser subagent" are encouraged to build on it, and points to the Gemini CLI browser agent as a reference implementation.

How it works

Under the hood the server combines two Chrome projects. Automation goes through Puppeteer, which the README credits for automating actions in Chrome and automatically waiting for action results. Performance work uses the Chrome DevTools frontend code to record traces and extract insights, so the agent receives the same kind of analysis a human would see in the Performance panel rather than a raw trace file.

By default the server launches its own Chrome instance the first time a tool needs one; connecting an MCP client does not start the browser by itself. The launched browser uses a dedicated profile under $HOME/.cache/chrome-devtools-mcp/chrome-profile on Linux and macOS, which persists between runs. Alternatively the server can attach to a Chrome that is already running, either with --autoConnect (Chrome 144 and later, after enabling remote debugging at chrome://inspect/#remote-debugging) or through a remote debugging port with --browser-url or --wsEndpoint. The advanced usage guide lists the reasons to prefer attaching: keeping application state between manual and agent-driven testing, sites that block sign-in under WebDriver control, and agents that run inside a sandbox while Chrome runs outside it.

The design principles document explains the shape of the tool output. Tools are meant to be "Token-Optimized", returning semantic summaries (the example given is that "LCP was 3.2s" beats 50k lines of JSON), and heavy assets such as screenshots, traces and videos should come back as file paths or resource URIs rather than inline data. Tools are deliberately small and composable (click, screenshot) instead of "magic buttons", and errors are supposed to be actionable. That last point showed up in practice during the test run described below, where a missing argument produced a precise validation message.

The CLI is a thin client over the same server. According to the CLI guide, it talks to a background chrome-devtools-mcp daemon over Unix sockets on Linux and macOS or named pipes on Windows, starts that daemon and the browser automatically on first use, and reuses the instance so open pages and cookies survive between commands. In CLI mode headless and isolated profiles are on by default.

The tool surface

The generated tool reference groups tools into categories. Most are on by default, and several are opt-in behind flags. A summary based on the reference and the 1.13.0 help output:

• Input automation: click, drag, fill, fill_form, handle_dialog, hover, press_key, type_text and upload_file. Elements are addressed by a uid taken from a page snapshot. A coordinate-based click_at exists only with --experimentalVision, which the help text says usually requires a computer-use model.
• Navigation: list_pages, new_page, navigate_page, select_page, close_page and wait_for.
• Emulation: emulate and resize_page for device and viewport conditions.
• Performance: performance_start_trace, performance_stop_trace and performance_analyze_insight, which drill into individual insights from a recorded trace.
• Network: list_network_requests and get_network_request. Retention across navigations is controlled by --maxNavigationSaved (1 to 25).
• Debugging: evaluate_script, console listing and detail tools, get_css_styles, lighthouse_audit (accessibility, SEO, best practices and agentic browsing; performance is excluded and handled by the trace tools), screencast start and stop, set_logpoints (new in 1.13.0), take_screenshot and take_snapshot.
• Memory: take_heapsnapshot is in the default set; the reference lists 13 further heap-analysis tools (dominators, retainers, duplicate strings, snapshot comparison and so on) that are enabled with --memoryDebugging.
• Opt-in categories: network mocks (mock_network, remove_network_mock), extensions, Progressive Web Apps (pipe connection only), virtual WebAuthn authenticators for passkey testing, third-party developer tools exposed by the page, and WebMCP tools, which require Chrome 150+ with a feature flag.

For lightweight jobs, --slim collapses everything into three tools, navigate, evaluate and screenshot, which keeps the tool list small for clients that pay a context cost per tool definition. Categories can also be switched off individually, for example --no-category-emulation, and a JSON config file can set the same options. With --watchConfig the server reloads that file on change and notifies the client that the tool list changed.

The package also bundles agent skills: chrome-devtools, chrome-devtools-cli, a11y-debugging, cookie-debugging, debug-optimize-lcp, memory-leak-debugging and troubleshooting. The README warns that skills describe the tools of a specific version, so they should be updated each time the server is updated.

Getting started

The README lists three requirements: a Node.js LTS release, Chrome at the current stable version or newer, and npm. The package's engines field narrows the Node range to ^20.19.0 || ^22.12.0 || >=23. Officially supported browsers are Google Chrome and Chrome for Testing; other Chromium-based browsers may work but are not guaranteed. The standard MCP client configuration from the README is:

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": ["-y", "chrome-devtools-mcp@latest"]
    }
  }
}

The client configurations guide covers more than two dozen clients. For Claude Code, the CLI route is:

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

The same guide gives one-liners for Codex CLI and Gemini CLI:

codex mcp add chrome-devtools -- npx chrome-devtools-mcp@latest
gemini mcp add chrome-devtools npx chrome-devtools-mcp@latest

Claude Code can also install the server plus its skills as a plugin:

/plugin marketplace add ChromeDevTools/chrome-devtools-mcp
/plugin install chrome-devtools-mcp@chrome-devtools-plugins

A quick smoke test from the README is to ask the agent to "Check the performance of https://developers.chrome.com"; the client should open the browser and record a trace. To use the terminal interface instead of MCP, install globally and address pages by ID:

npm i chrome-devtools-mcp@latest -g
chrome-devtools navigate_page 1 --url "https://developers.chrome.com"
chrome-devtools take_screenshot 1 --filePath screenshot.png
chrome-devtools stop

Flags go in the args array. The configuration guide's example combines a channel with headless and isolated mode:

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": [
        "chrome-devtools-mcp@latest",
        "--channel=canary",
        "--headless=true",
        "--isolated=true"
      ]
    }
  }
}

To attach to a Chrome started by hand on Linux, the advanced usage guide starts Chrome with a remote debugging port and a non-default profile, then points the server at it with --browser-url=http://127.0.0.1:9222:

/usr/bin/google-chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-profile-stable

When something fails, the troubleshooting guide's first suggestion is to run the server's --help through npx to confirm it starts at all, and to make sure the MCP client uses the same Node and npm versions as the terminal.

Hands-on: driving 1.13.0 over raw MCP

In a test run on 14 November 2026, version 1.13.0 was exercised on a Linux x86_64 cloud VM with Node v22.23.4 and Google Chrome installed at /usr/bin/google-chrome. Instead of going through an editor, a small Python client spoke MCP JSON-RPC directly over stdio, which exposes exactly what the server sends and expects. The server was started with --headless, --isolated, --no-usage-statistics and --chrome-arg=--no-sandbox. The last flag was needed only because that VM runs everything as root; the troubleshooting guide notes that Chrome does not start as root and recommends running the server as a non-root user instead, so this is not a setting to copy into a normal workstation setup.

The initialize handshake returned server name chrome_devtools, title Chrome DevTools MCP server and version 1.13.0. A tools/list call returned 33 tools with the default categories: click, close_page, drag, emulate, evaluate_script, fill, fill_form, get_console_message, get_css_styles, get_network_request, handle_dialog, hover, lighthouse_audit, list_console_messages, list_network_requests, list_pages, navigate_page, new_page, performance_analyze_insight, performance_start_trace, performance_stop_trace, press_key, resize_page, screencast_start, screencast_stop, select_page, set_logpoints, take_heapsnapshot, take_screenshot, take_snapshot, type_text, upload_file, wait_for.

The pageId gotcha

The first navigate_page call, sent without a page ID, failed with Input validation error: Invalid arguments for tool navigate_page: pageId: Invalid input: expected number, received undefined. The cause is --pageIdRouting, which defaults to true and makes pageId required on every page-scoped tool; the changelog records this default arriving in 1.8.0 (August 2026), and the advanced usage guide explains it as a way for concurrent sessions sharing one server to route calls to their own tab. Calling list_pages first returned 1: about:blank [selected], and passing pageId: 1 fixed every subsequent call. Mainstream MCP clients read the tool schema and handle this, but anyone writing a custom client, a test harness or an agent framework integration should call list_pages before anything else, or start the server with --no-page-id-routing to restore selected-page routing.

Snapshot, console and network on a test page

The target was a six-line local page titled "Checkout demo" served at http://127.0.0.1:8765/: a heading, an email input, a "Pay now" button whose click handler logs console.error('payment API returned 500'), and a fetch('/missing.json') on load. Results:

Tool call	What came back
navigate_page	Successfully navigated to http://127.0.0.1:8765/.
take_snapshot	Accessibility-tree text: uid=1_0 RootWebArea "Checkout demo", uid=1_1 heading "Checkout" level=1, uid=1_2 "Email ", uid=1_3 textbox "Email ", uid=1_4 button "Pay now"
list_console_messages	msgid=1 [log] app booted; msgid=2 [error] Failed to load resource: the server responded with a status of 404 (File not found) [2 times]
click with uid 1_4	Successfully clicked on the element; the console then also held msgid=4 [error] payment API returned 500
list_network_requests	reqid=1 GET http://127.0.0.1:8765/ [200]; reqid=2 GET /missing.json [404]; reqid=3 GET /favicon.ico [404]

This sequence is the core loop an agent uses. The snapshot is compact text, roughly one line per meaningful element, and each line carries a uid. Those uids are the handles that click, fill, hover and drag take as input, so the agent never has to invent a CSS selector or estimate pixel coordinates from a screenshot. The tool reference tells agents to "Always use the latest snapshot" and to prefer snapshots over screenshots, which matters because uids are only meaningful against the snapshot they came from. The console and network listings then close the loop: after the click, the new error appeared with its own message ID, which an agent can expand with get_console_message for the source-mapped stack trace. The two 404s in the console line up with the two failed requests in the network list, which is exactly the cross-check a developer would do by hand in DevTools.

Behaviour behind a proxy

• Navigating to https://example.com from the VM failed with net::ERR_TUNNEL_CONNECTION_FAILED, because the VM sits behind an egress proxy that Chrome was not configured to use.
• The server did not crash; the next snapshot simply contained Chrome's error page, so an agent sees a readable failure rather than a dead connection.
• The --proxyServer flag, passed to Chrome as --proxy-server, exists for this situation in corporate networks and CI runners.

Use cases

• Agent self-verification of UI changes. After editing a component, the agent opens the page, takes a snapshot, exercises the flow with uid-based clicks and fills, and checks the console and network lists for new errors before reporting the task as done.
• Performance investigations. Recording a trace and drilling into insights with performance_analyze_insight turns a vague "the page feels slow" into specific findings. The bundled debug-optimize-lcp skill targets Largest Contentful Paint work.
• Accessibility and SEO checks. lighthouse_audit returns scores, failing audits and the DOM nodes they flag, and the a11y-debugging skill guides an agent through fixing them.
• Memory leak hunting. With --memoryDebugging, heap snapshots can be compared and queried for retainers and dominators; the 1.12.0 changelog adds analysis of heap snapshots without a browser connection.
• API failure simulation. The opt-in network mocks category, which gained page-scoped mocks and upstream mock responses in 1.13.0, lets an agent test error states without touching the backend.
• Shell scripting and CI-style checks. The chrome-devtools CLI runs the same tools from scripts, and the CLI guide pitches it for cases where an agent generates scripts that automate browser actions.
• Passkey and PWA testing. Opt-in WebAuthn and PWA categories cover virtual authenticators and app install, launch and uninstall flows.

In a multi-server setup, Chrome DevTools MCP usually sits beside other MCP servers in the same client, for example GitHub MCP Server for repository and pull request context, so one agent session can read an issue, reproduce it in the browser and propose a fix.

How it compares

The README does not name competitors, so the comparison below sticks to category-level differences with tools that cover similar ground. Check each project's own documentation for current feature details.

Project	What it is	Where it fits relative to Chrome DevTools MCP
Chrome DevTools MCP	MCP server and CLI from the ChromeDevTools organisation, built on Puppeteer and DevTools frontend code	Debugging and performance focus: traces with insights, Lighthouse audits, source-mapped console, heap snapshots; officially supports Chrome and Chrome for Testing only
Playwright	A test framework and browser automation library, which per its own docs also offers MCP and agent tooling	A broader fit when the goal is a maintained end-to-end test suite or automation beyond Chrome; Chrome DevTools MCP is narrower and closer to the DevTools panels
agent-browser	A browser automation CLI aimed at AI agents	Overlaps with the chrome-devtools CLI for agent-driven browsing; Chrome DevTools MCP adds DevTools-specific inspection and profiling
Mobile MCP	An MCP server for mobile automation	Relevant for native mobile apps; Chrome DevTools MCP covers web pages, with Android Chrome debugging documented separately

A practical way to choose: if the agent needs to understand why a page is slow, leaking memory or throwing errors, the DevTools-derived tools here are the distinguishing factor. If the main need is a durable regression suite, a test framework remains the natural home, and the two can coexist in one project.

Limits, privacy and security

The defaults favour convenience, and several of them deserve a deliberate decision before rolling the server out to a team.

• Usage statistics are on by default. The README says Google collects data such as tool invocation success rates, latency and environment information. Opt out with --no-usage-statistics; collection is also disabled when the CHROME_DEVTOOLS_MCP_NO_USAGE_STATISTICS or CI environment variables are set. This is independent of Chrome's own browser metrics, so opting out of one does not opt out of the other.
• CrUX lookups send URLs. Performance tools may send trace URLs to the Chrome User Experience Report API to fetch field data; --performanceCrux defaults to true. Use --no-performance-crux for internal or pre-release URLs.
• Update checks. The server periodically checks the npm registry for new versions unless CHROME_DEVTOOLS_MCP_NO_UPDATE_CHECKS is set.
• Browser content is exposed to the client. The README's disclaimer is explicit: the server lets MCP clients "inspect, debug, and modify any data in the browser or DevTools". The security policy adds that web content is returned as-is and recommends trusted content or client-side precautions against prompt injection.
• JavaScript evaluation is not a sandbox. --no-javascript-evaluation disables evaluate_script, set_logpoints, the slim evaluate tool, the initScript parameter and navigation to javascript:, data: or vbscript: URLs. The help text states plainly that "This is not a JavaScript sandbox": page scripts still run, clicks can still trigger code, and --experimentalDevtools reopens a path through the DevTools Console.
• Profile persistence. Without --isolated, the dedicated profile directory is not cleared between runs, so cookies and logins carry over, and only one browser can use it at a time. --isolated uses a temporary directory that is deleted when the browser closes. --autoConnect gives the server access to all open windows of the selected profile.
• Files and paths. --fileNavigations can be set to false to block file: URLs, though the help text says it is not a filesystem sandbox. File-reading and writing tools default to the OS temp directory when the client does not negotiate MCP roots; --workspace (alias --filesystemRoot) adds allowed directories. The CLI is different: its guide says it enables unrestricted filesystem access by default.
• URL allow and block lists. --blockedUrlPattern and --allowedUrlPattern use URL Pattern syntax; the allow list requires Chrome 149+. The security policy calls them guardrails, not a complete network sandbox, because they apply only to targets while the server is attached.
• Header redaction is off. --redactNetworkHeaders defaults to false, so request and response headers, including authentication headers, reach the client unless it is enabled.
• Trusted host model. The security policy treats the working directory, environment variables, npm configuration, Node and the Chrome binary as trusted, and advises against starting the server in an untrusted workspace; for untrusted repositories it recommends an OS-level sandbox or a dedicated VM. The configuration guide also warns that the config file and its directory must not be writable by the agent, since it can set options such as executablePath and chromeArg.
• Remote debugging ports. The advanced usage guide warns that any application on the machine can connect to an open debugging port and control the browser, so avoid sensitive browsing while one is open.
• Sandboxed clients and root. Clients that sandbox MCP servers with macOS Seatbelt or Linux containers can prevent Chrome from starting; the workaround is disabling that sandbox for this server or connecting with --browser-url. Chrome also refuses to run as root, which is common in containers.

Project activity and verified facts

Checked 14 November 2026: npm latest 1.13.0 (released 11 November 2026, per the GitHub releases and the npm package page), Apache-2.0, about 56,100 stars.

The repository was created on 11 September 2025 and was last pushed on 13 November 2026. The release cadence is brisk: the changelog shows 1.0.0 on 18 May 2026, then minor releases roughly every two to three weeks, including 1.11.0 on 15 October and 1.12.0 on 22 October. Version 1.13.0 added logpoints built on the DevTools BreakpointManager, page-scoped network mocks and upstream mock responses, along with fixes such as accepting config files with a UTF-8 BOM and disabling set_logpoints when JavaScript evaluation is turned off. Security reports go through Google's Open Source Software Vulnerability Reward Program, according to SECURITY.md.

Because the server is usually run as chrome-devtools-mcp@latest, each new release reaches users on the next client restart. Teams that want reproducible agent behaviour can pin a version in the args array and update deliberately, re-copying bundled skills at the same time as the README advises. Source, issues and the full changelog are in the GitHub repository, and the official documentation lives at developer.chrome.com/docs/devtools/agents.

[![Featured on TechLogHub](https://techloghub.com/badge-neutral.svg)](https://techloghub.com/open-source/chrome-devtools-mcp?utm_source=techloghub_badge&utm_medium=referral&utm_campaign=readme)