Chrome DevTools MCP: Letting an Agent Debug in the Browser

Chrome DevTools MCP is Google’s Model Context Protocol server that lets a coding agent control and inspect a live Chrome browser through DevTools. Once it is added to a client such as Claude Code, Cursor, Gemini CLI or VS Code, the agent can open a page, click and type, read console messages with source-mapped stack traces, list network requests, record a performance trace, run a Lighthouse audit and take screenshots. The point is that the agent stops guessing: it can see what the code it just wrote actually does in the browser. The package is chrome-devtools-mcp, it runs locally with npx, and it starts its own Chrome with a dedicated profile unless you tell it otherwise. That profile, and what the browser can reach, is what to set up with care.

What it is, and what it is called now

Google announced the server as a public preview in the Chrome for Developers post Chrome DevTools (MCP) for your AI agent↗ (opens in a new tab) on September 23, 2025. It has since moved to 1.x releases and a new umbrella name: the project now calls itself Chrome DevTools for agents, which also includes a command-line tool for use without MCP. The npm package, the chrome-devtools server name in the examples and the GitHub repository did not change, so older guides still work. It is licensed Apache 2.0.

Under the hood it uses Puppeteer to drive Chrome and waits for the result of each action, and it uses DevTools itself to record and analyze traces. It officially supports Google Chrome and Chrome for Testing; other Chromium browsers may work but are not guaranteed.

What the tools do

The tool reference in the chrome-devtools-mcp repository↗ (opens in a new tab) groups the tools by job. The ones you will use most:

• Input: click, fill, fill_form, type_text, press_key, hover, drag, upload_file and handle_dialog. Elements are addressed by a uid from take_snapshot, a text outline of the page built from the accessibility tree.
• Navigation: new_page, navigate_page, list_pages, select_page, close_page and wait_for.
• Console: list_console_messages and get_console_message, with stack traces on request.
• Network: list_network_requests and get_network_request, which returns request and response headers, including cookies, and the bodies.
• Performance: performance_start_trace, performance_stop_trace and performance_analyze_insight, for Core Web Vitals such as LCP, INP and CLS and the insights DevTools draws from a trace.
• Inspection: take_screenshot, evaluate_script to run a JavaScript function in the page, get_css_styles for the rules that apply to an element, and lighthouse_audit for accessibility, SEO and best practices.
• Emulation: emulate and resize_page, for a phone-sized viewport, a slow network or a different location.

More groups exist but are off by default: extensions, Progressive Web Apps, memory heap snapshots, experimental screencasts and coordinate clicks. If you only need to load a page, run a script and take a screenshot, --slim cuts the list to three tools, which saves context. Why a long tool list costs so much is covered in MCP token usage.

Setup in each client

Every client takes the same entry: a server named chrome-devtools that runs npx -y chrome-devtools-mcp@latest. You need a current Node.js LTS release and Chrome stable or newer. The repository’s client configuration guide↗ (opens in a new tab) has the command for each client:

# Claude Code, available in every project
claude mcp add chrome-devtools --scope user npx chrome-devtools-mcp@latest

# Gemini CLI (add -s user to install it globally)
gemini mcp add chrome-devtools npx chrome-devtools-mcp@latest

# VS Code (macOS and Linux shells)
code --add-mcp '{"name":"io.github.ChromeDevTools/chrome-devtools-mcp","command":"npx","args":["-y","chrome-devtools-mcp"],"env":{}}'

• Cursor: Cursor Settings, then MCP, then New MCP Server, and paste the standard entry. There is also a one-click install link in the guide.
• Claude Code as a plugin: /plugin marketplace add ChromeDevTools/chrome-devtools-mcp, then /plugin install chrome-devtools-mcp@chrome-devtools-plugins. The plugin adds skills alongside the server. Remove any earlier manual entry first so you do not run two.
• Gemini CLI as an extension: gemini extensions install --auto-update https://github.com/ChromeDevTools/chrome-devtools-mcp, which also brings the skills.
• VS Code as a plugin: run Chat: Install Plugin From Source from the Command Palette and paste ChromeDevTools/chrome-devtools-mcp. Where VS Code keeps the entry is covered in the VS Code mcp.json guide.

Check it with a prompt such as “Check the performance of https://developers.chrome.com”. The browser starts only when the agent first calls a tool that needs it, not when the client connects. To pass flags in Claude Code, put them after a double dash, for example claude mcp add chrome-devtools --scope user -- npx chrome-devtools-mcp@latest --isolated. If the server will not start, how to debug MCP tools walks through the checks.

Profiles: dedicated, isolated or your own

Which browser profile the agent uses decides what it can reach. There are four ways to run it:

• The default: a dedicated profile under .cache/chrome-devtools-mcp/chrome-profile in your home folder. It is not your everyday profile, but it is not cleared between runs either, so anything the agent signs in to stays signed in next time.
• --isolated: a temporary profile that is deleted when the browser closes. Use this by default, and always when several sessions run at once.
• --autoConnect: connect to the Chrome you already have open, with its tabs and signed-in sessions. It needs Chrome 144 or newer, remote debugging switched on at chrome://inspect/#remote-debugging, and your approval in a dialog each time the server asks to connect.
• --browser-url: connect to a Chrome started with a remote debugging port, for example when the agent runs in a sandbox. Anything on your machine can use that port while it is open.

Google’s post on debugging your browser session↗ (opens in a new tab) explains why the last two exist: some sign-ins refuse a browser that is controlled by automation, and it is useful to select a failing request or an element in DevTools yourself and hand it to the agent. The cost is that the agent then sees whatever that profile is signed in to. For your own app, a test account in an isolated profile is almost always enough.

The security warning, in plain words

The README carries a short disclaimer: the server exposes the content of the browser to the MCP client, which can inspect, debug and change any data in the browser or in DevTools, so do not share sensitive or personal information you would not want the client to see. In practice that means:

• Network tools return headers, including cookies and session tokens. --redact-network-headers removes some sensitive headers from what the model sees.
• evaluate_script runs arbitrary JavaScript in the page. Keep your client’s approval prompt on for it, or turn it off with --no-javascript-evaluation when you only need to read.
• Pages are input. A page the agent reads can carry instructions aimed at it, which is indirect prompt injection. Point it at your own app and sites you trust.
• --allowed-url-pattern and --blocked-url-pattern limit where the browser may go. The allowlist needs Chrome 149 or newer.
• Leave --accept-insecure-certs off unless you are testing a local certificate you control.

Two data flows are on by default and worth knowing. Performance tools may send trace URLs to Google’s Chrome UX Report API to fetch real-user field data; --no-performance-crux stops that, and you should use it for internal or staging URLs. Google also collects usage statistics about the tool; --no-usage-statistics opts out, and collection is off when the CI environment variable is set. The wider checklist for local servers is in MCP security best practices.

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": [
        "-y", "chrome-devtools-mcp@latest",
        "--isolated",
        "--no-performance-crux",
        "--no-usage-statistics",
        "--redact-network-headers"
      ]
    }
  }
}

Chrome DevTools MCP vs Playwright MCP

Both drive a real browser and both read the page as an accessibility snapshot, so for clicking through a flow either will do. The difference is emphasis. Chrome DevTools MCP is built around DevTools: source-mapped console errors, full network request detail, performance traces with DevTools insights, CSS rule inspection and Lighthouse, in Chrome only. Playwright MCP is built around automation and testing across browsers, with its own options, test agents and a CLI, all covered in that post. A fair rule: reach for Chrome DevTools MCP when the question is why something is broken or slow in Chrome, and for Playwright MCP when the goal is a repeatable test. Many teams keep both configured and turn on only the one the task needs.

If what you want is Claude working inside your own everyday browser with site-by-site permissions, that is a different product; see Claude in Chrome.

Filing what the agent finds as a bug

A debugging session turns up more than the bug you asked about: a second console error, a slow image, a button with no accessible name. Those are lost when the chat ends unless they are written down. With fenbs connected as a second MCP server at https://fenbs.ai/api/mcp, you can end the session with a prompt like this one:

For each problem you found on localhost:3000/checkout, search the fenbs
board first. If it is not there, file it as a bug with the URL, the steps,
the console error or failing request, and what you expected. Anything that
is a polish item, not a fault, goes in as an enhancement. Do not fix anything yet.

Each report lands in To Do with a BUG- or ENH- reference, a note that states the problem, and room for a plan, a test status and a priority from 1 to 10, where 1 is the most urgent. History records each task as filed by the assistant on your behalf, so you can tell its reports from yours. What a good report contains is in the bug report template. fenbs does not run the browser or reproduce anything itself; that stays with Chrome DevTools MCP.