Chrome DevTools MCP: Let Your AI Agent Debug Live Web Apps

AI coding agents are excellent at writing code, but they have always been blind to one thing: what the code actually does in a real browser. When your agent fixes a layout bug or chases a slow page, it is guessing — it cannot see the rendered DOM, the network waterfall, or the console errors.

Chrome DevTools MCP closes that loop. It is an official Model Context Protocol server from the Chrome team that gives your AI agent direct, programmatic control over a real Chrome instance: navigate pages, click elements, record performance traces, inspect network requests, read console messages, and take screenshots — all from inside Claude, Cursor, Gemini CLI, or any MCP-capable client.

In this tutorial you will set up Chrome DevTools MCP, connect it to your agent, and run real debugging workflows: diagnosing a slow page with a performance trace, reproducing a failing network call, and fixing a console error end to end.

Prerequisites

Before starting, make sure you have:

• Node.js (current LTS version) and npm installed
• A current stable Chrome browser (or newer)
• An MCP-capable AI client: Claude Code, Cursor, VS Code Copilot, or Gemini CLI
• Basic familiarity with JSON configuration files and the browser DevTools concepts (network, console, performance)

No global install is required — the server runs through npx.

What You'll Learn

By the end of this guide you will be able to:

• Install and configure Chrome DevTools MCP in your AI client
• Understand the full toolset: navigation, input automation, performance, network, and debugging
• Run a guided performance audit and read the insights your agent surfaces
• Reproduce and fix network and console errors in an automated loop
• Connect the server to an already-running Chrome instance for debugging your own dev session

How It Works

Chrome DevTools MCP exposes the Chrome DevTools Protocol (CDP) as a set of MCP tools. Under the hood it uses Puppeteer to drive a Chrome instance, then translates the agent's tool calls into CDP commands.

The flow is simple:

1. Your AI agent decides it needs to see something in the browser.
2. It calls an MCP tool such as navigate_page or performance_start_trace.
3. The server executes the action in Chrome and returns structured results — a DOM snapshot, a trace summary, a list of network requests.
4. The agent reads those results and decides what to do next.

Because the agent works against a live page, it can verify its own fixes instead of guessing.

Step 1: Add the MCP Server to Your Client

The server is published as chrome-devtools-mcp on npm. You never install it globally — the client launches it on demand with npx.

Claude Code

Add it with a single command:

claude mcp add chrome-devtools -- npx -y chrome-devtools-mcp@latest

Or edit your MCP config manually (~/.claude.json or the project .mcp.json):

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

Cursor / VS Code / Gemini CLI

All MCP clients use the same shape. Drop this into the client's MCP settings file (for Cursor that is ~/.cursor/mcp.json, for Gemini CLI it is ~/.gemini/settings.json):

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

Verify the connection

Restart your client, then ask the agent a simple prompt:

Open a new page, navigate to https://example.com, and tell me the page title.

If the server is wired up correctly, the agent will call new_page, then navigate_page, then read the title back to you. You will also see a Chrome window pop up.

Step 2: Understand the Toolset

Chrome DevTools MCP exposes a broad toolset (around 58 tools). You rarely call these by hand — the agent picks them — but knowing the categories helps you write better prompts.

Two tools deserve special attention:

• take_snapshot returns a structured, text-based representation of the page's accessibility tree. This is what the agent reads to understand layout and find elements — it is far cheaper than a screenshot and gives stable element references for clicking.
• evaluate_script runs arbitrary JavaScript in the page context and returns the result. This is the agent's escape hatch for reading any state the dedicated tools do not cover.

Step 3: Run a Performance Audit

This is where Chrome DevTools MCP shines. Instead of you opening DevTools, recording a trace, and squinting at the flame chart, your agent does it and explains the result.

Try this prompt against a page you want to profile:

Navigate to http://localhost:3000, record a performance trace while reloading
the page, then tell me the Largest Contentful Paint and the top opportunities
to make the page faster.

The agent will typically run this sequence:

1. navigate_page  → http://localhost:3000
2. performance_start_trace (reload: true)
3. performance_stop_trace
4. performance_analyze_insight  → "LCPBreakdown"

The performance_analyze_insight tool is the key. It does not dump raw trace data — it returns named insights (LCP breakdown, render-blocking requests, layout shifts, long main-thread tasks) with concrete numbers. Your agent reads these and produces a prioritized list, for example:

• LCP is 4.2s, dominated by a render-blocking stylesheet
• A 600ms long task is blocking the main thread during hydration
• Three images lack explicit dimensions, causing layout shift

Now you can follow up: "Fix the render-blocking stylesheet and re-run the trace to confirm LCP improved." The agent edits your code, reloads, re-traces, and verifies — a complete closed loop.

Step 4: Debug Network Requests

When an API call fails or returns the wrong data, your agent can inspect the actual requests instead of guessing.

Navigate to http://localhost:3000/dashboard, then list all failed network
requests and show me the response body of any that returned a 4xx or 5xx status.

The agent calls list_network_requests to get the full list, filters for failures, then calls get_network_request on each suspicious one to read headers, status, and the response body. A typical finding:

GET /api/user/profile → 401 Unauthorized
Request headers missing: Authorization
Response: { "error": "Missing bearer token" }

From here the agent can trace the bug back to your code — perhaps the auth token is not attached on the client — fix it, reload, and confirm the request now returns 200.

Step 5: Fix a Console Error End to End

Console errors are the most common signal an agent was previously blind to. Now it reads them directly.

Open http://localhost:3000, list any console errors, find the root cause in
the codebase, fix it, then reload and confirm the console is clean.

The loop the agent runs:

1. navigate_page → localhost:3000
2. list_console_messages → finds: "TypeError: Cannot read properties of
   undefined (reading 'map') at ProductList.tsx:24"
3. (reads ProductList.tsx, finds products may be undefined before fetch resolves)
4. (edits the file to guard with `products?.map(...)`)
5. navigate_page (reload)
6. list_console_messages → clean

This observe → fix → verify cycle is the entire point of giving an agent eyes in the browser. The agent never declares victory based on a guess; it confirms against the live page.

Step 6: Connect to Your Existing Chrome Session

By default the server launches its own isolated Chrome. Sometimes you want the agent to debug the exact session you are already logged into — your dev environment with cookies, local storage, and auth in place.

First, launch Chrome with remote debugging enabled:

# macOS
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
  --remote-debugging-port=9222
 
# Linux
google-chrome --remote-debugging-port=9222

Then point the server at it with the --browser-url flag:

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": [
        "-y",
        "chrome-devtools-mcp@latest",
        "--browser-url",
        "http://127.0.0.1:9222"
      ]
    }
  }
}

Now the agent operates on your real, authenticated browser. Use this carefully — the agent can interact with anything in those tabs.

Useful CLI Flags

Pass these in the args array to tune the server's behavior:

A practical CI-friendly configuration:

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

Testing Your Setup

Verify the whole pipeline with one end-to-end prompt:

Open https://web.dev, take a snapshot of the page, run a Lighthouse audit,
and summarize the performance and accessibility scores.

A correct setup produces: a Chrome window opening, a structured DOM snapshot, a lighthouse_audit call, and a readable summary with numeric scores. If nothing happens, jump to troubleshooting.

Troubleshooting

The agent says it has no browser tools. Confirm the MCP server is listed and connected. In Claude Code run claude mcp list; the entry should show as connected. Restart the client after editing config.

npx fails or hangs on first run. Run npx -y chrome-devtools-mcp@latest --help directly in your terminal to surface the real error. Often it is a Node version that is too old — use a current LTS release.

Chrome does not launch. Make sure Chrome is installed and on a current stable version. If you have multiple versions, pin one with --channel or --executable-path.

--browser-url connection refused. Chrome must be started with --remote-debugging-port=9222 before the agent connects, and you must use the same port in the flag.

Token usage is high. Snapshots and traces are large. Use --slim for simple automation, prefer take_snapshot over take_screenshot when you only need structure, and ask the agent to inspect specific requests rather than dumping the full network list.

Next Steps

• Pair this with a Model Context Protocol server you build yourself to expose your app's internal state alongside the browser tools.
• Add Playwright end-to-end tests so the fixes your agent verifies in the browser are locked in by CI.
• Explore browser automation agents with Stagehand for higher-level, intent-driven browser control.

Conclusion

Chrome DevTools MCP turns your AI agent from a code generator into a code generator that can see its own work. By exposing navigation, performance tracing, network inspection, and the console as MCP tools, it lets the agent close the observe → fix → verify loop without you ever opening DevTools manually.

Start small: wire it into your client, ask it to profile one slow page, and watch it surface concrete insights. Once your agent can read the browser, debugging stops being a guessing game.