DEV Community

Deduped
Deduped

Posted on Originally published at dedupedai.com

How to let Claude Code debug your web app in real Chrome with Chrome DevTools MCP

#debugging #ai #mcp #webdev

Most coding agents are blind to the one place front end bugs actually happen: the browser. Claude Code can read your React component, but it cannot see that the button is hidden behind a modal, that a fetch returns a 401, or that the console is full of hydration warnings. So you end up pasting screenshots and stack traces into the chat by hand.

Chrome DevTools MCP (chrome-devtools-mcp) fixes that. It is an official project from the Chrome DevTools team that lets a coding agent control and inspect a live Chrome browser, as an MCP server or as a CLI. Your agent gets the real DevTools: network requests, console messages with source-mapped stack traces, screenshots, performance traces and Lighthouse audits.

Here is how to set it up in Claude Code (plus VS Code and Cursor), the prompts that make it useful, and the flags worth knowing.

What you need

From the README:

  • Node.js LTS and npm
  • Chrome, current stable version or newer

The project officially supports Google Chrome and Chrome for Testing only. Other Chromium browsers may work, but that is not guaranteed.

Step 1: add it to Claude Code

The fastest path is one command:

claude mcp add chrome-devtools --scope user npx chrome-devtools-mcp@latest
Enter fullscreen mode Exit fullscreen mode

--scope user makes it available in every project, not only the current folder. Using @latest means the server updates itself each time it starts.

If you also want the bundled skills (they teach the agent how to use the tools well), install it as a plugin instead. Inside Claude Code:

/plugin marketplace add ChromeDevTools/chrome-devtools-mcp
/plugin install chrome-devtools-mcp@chrome-devtools-plugins
Enter fullscreen mode Exit fullscreen mode

Restart Claude Code, then check with /skills. The docs say to remove any earlier MCP-only install first so you do not end up with two copies.

The skills that ship with it include a11y-debugging, cookie-debugging, debug-optimize-lcp, memory-leak-debugging and troubleshooting, each scoped to one job.

Step 1b: VS Code or Cursor

The same server works anywhere that speaks MCP. The standard config is:

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

In VS Code you can add it from the terminal:

code --add-mcp '{"name":"io.github.ChromeDevTools/chrome-devtools-mcp","command":"npx","args":["-y","chrome-devtools-mcp"],"env":{}}'
Enter fullscreen mode Exit fullscreen mode

In Cursor, go to Cursor Settings, then MCP, then New MCP Server, and paste the standard config.

Step 2: run the first prompt

The README suggests this as a smoke test:

Check the performance of https://developers.chrome.com
Enter fullscreen mode Exit fullscreen mode

Chrome should open and the agent should record a performance trace. Note that the server only launches Chrome when a tool actually needs a browser. Connecting to the server alone does not start it, so do not panic if nothing opens until you ask for something.

Prompts that earn their keep

Once it works, point it at your own dev server. A few patterns that map directly to the tools it exposes (navigate_page, click, fill_form, list_console_messages, list_network_requests, take_screenshot, performance_start_trace, lighthouse_audit and more):

Open http://localhost:3000/login, sign in with the test account in .env.local,
and tell me every console error and failed network request you see.
Enter fullscreen mode Exit fullscreen mode 
The checkout button does nothing on mobile. Emulate a phone viewport,
click it, and find out why. Then fix the code and verify the fix in the browser.
Enter fullscreen mode Exit fullscreen mode 
Run a Lighthouse audit on http://localhost:3000 and fix the top three issues.
Enter fullscreen mode Exit fullscreen mode

The last step, "verify the fix in the browser", is the whole point. The agent edits code, reloads, and checks the result itself instead of asking you to look.

Debug inside your real, signed-in Chrome

By default the server starts its own Chrome with a dedicated profile. When the bug only shows up behind a login, you can connect it to a Chrome you already have open.

On Chrome M144 or newer, open chrome://inspect/#remote-debugging, enable remote debugging, and allow the connection. Then start the server with --autoConnect:

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": ["chrome-devtools-mcp@latest", "--autoConnect"]
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Chrome shows a permission dialog, and the agent gets access to the open windows of your default profile.

The older route is a debugging port. Close Chrome, then on a Mac start it with:

/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-profile-stable
Enter fullscreen mode Exit fullscreen mode

and pass --browser-url=http://127.0.0.1:9222 to the server. Chrome requires a non-default user data directory for this. The docs warn that any app on your machine can control the browser while that port is open, so do not browse sensitive sites in that window.

Flags worth knowing

  • --headless: no visible window, handy on a server or in CI.
  • --isolated: a temporary profile that is deleted when the browser closes.
  • --slim: a reduced tool set for basic browsing, which keeps more of the context window free.
  • --viewport 1280x720: set the starting window size.
  • --no-usage-statistics: Google collects usage statistics by default; this turns it off. Setting the CI environment variable also disables it.
  • --no-performance-crux: stops performance tools from sending trace URLs to the CrUX API for real-user data.

One privacy note straight from the README: the server exposes everything in that browser to your MCP client. Do not use it in a profile holding data you would not paste into the chat.

Prefer the terminal?

The package also ships a chrome-devtools CLI, no MCP required:

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
Enter fullscreen mode Exit fullscreen mode

That makes it scriptable in shell checks, or usable by agents that run commands but do not load MCP servers.

Where it fits

Chrome DevTools MCP is the right pick when you want to debug: real network data, console errors, traces and audits. If your goal is to automate web tasks rather than debug pages, other repos may fit better. We keep a ranked list of the best AI repos for browser automation, including Vercel's agent-browser, which lets your agent browse with short CLI commands.

The step-by-step version of this setup, with the prompt to paste, is on the Deduped page for letting your agent debug a page in real Chrome. For more servers like this one, see the best MCP servers list.

Get one email every Monday with the week's hottest AI repos and exactly how to use them: subscribe free at dedupedai.com

Top comments (0)