How to Connect Chrome DevTools to AI Coding Agents Using MCP: A Step-by-Step Guide

A practical step-by-step tutorial on setting up the Chrome DevTools MCP server and connecting it to AI coding agents like Claude Code, Cursor, and Codex for browser debugging, screenshots, JavaScript evaluation, and DOM interaction.

Why Chrome DevTools MCP Matters

If you have been building with AI coding agents like Claude Code, Cursor, or Codex, you already know how powerful they are. But there is one gap that until recently was impossible to close: giving your AI agent direct access to the browser.

The Chrome DevTools MCP Server (now with over 41,000 stars on GitHub) bridges exactly that gap. It lets AI coding agents inspect pages, take screenshots, evaluate JavaScript, read console logs, and interact with the DOM — all through the Model Context Protocol (MCP).

In this tutorial, you will set up the Chrome DevTools MCP server from scratch and connect it to an AI coding agent to debug a live web page.

Prerequisites

Node.js 18+ installed on your machine
Google Chrome or Chromium installed
An AI coding agent that supports MCP (Claude Code, Cursor, Codex, or similar)
Basic familiarity with the terminal

Step 1: Install the Chrome DevTools MCP Server

The server is distributed as an npm package. Open your terminal and install it globally:

npm install -g @chrome-devtools/mcp

Verify the installation:

mcp-chrome-devtools --version

You should see the version number printed. If you get an error about permissions, try running with sudo or use npm install without -g in your project directory instead.

Step 2: Launch Chrome with Remote Debugging

The MCP server communicates with Chrome via the DevTools Protocol over WebSocket. You need to launch Chrome with the remote debugging port enabled:

# macOS
"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" \
  --remote-debugging-port=9222 \
  --user-data-dir=/tmp/chrome-mcp-profile

# Linux
google-chrome --remote-debugging-port=9222 \
  --user-data-dir=/tmp/chrome-mcp-profile

# Windows
"C:\Program Files\Google\Chrome\Application\chrome.exe" ^
  --remote-debugging-port=9222 ^
  --user-data-dir=C:\temp\chrome-mcp-profile

The --user-data-dir flag ensures you do not interfere with your main Chrome profile. A fresh temporary profile is created each time.

Step 3: Start the MCP Server

With Chrome running, start the MCP server in another terminal:

mcp-chrome-devtools --port 9222

The server will connect to Chrome and expose tools over stdio (MCP protocol). You should see output confirming the connection:

Connected to Chrome DevTools on port 9222
MCP server ready. Exposing tools: navigate, screenshot, evaluate, getConsoleLogs, getElement, click, type, ...

Step 4: Configure Your AI Agent

How you configure the MCP server depends on your agent. Here are the most common setups:

Claude Code

Add the server to your .mcp.json file in the project root:

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "mcp-chrome-devtools",
      "args": ["--port", "9222"]
    }
  }
}

Cursor

Go to Settings → Features → MCP and add a new server with:

Field	Value
Name	chrome-devtools
Type	Command
Command	mcp-chrome-devtools
Arguments	--port 9222

Codex / Generic MCP Client

Use the same .mcp.json format as Claude Code above. Any MCP-compatible client can connect.

Step 5: Use It — Real Examples

Once connected, you can ask your AI agent to interact with the browser. Here are practical examples:

Navigate and Screenshot

Ask your agent: "Navigate to https://example.com and take a screenshot."

Behind the scenes, the agent calls the navigate tool followed by screenshot, returning a visual of the page.

Debug Console Errors

# The agent can read console logs:
Tool: getConsoleLogs
Result: [
  { level: "error", text: "Uncaught TypeError: x is undefined", url: "app.js", line: 42 },
  { level: "warning", text: "Deprecated API usage", url: "vendor.js", line: 15 }
]

This lets your AI agent identify and explain runtime errors without you manually opening DevTools.

Evaluate JavaScript

Ask: "What is the value of window.__INITIAL_STATE__ on the current page?"

# Agent uses the evaluate tool:
Tool: evaluate
Expression: "JSON.stringify(window.__INITIAL_STATE__)"
Result: "{\"user\":{\"name\":\"Alice\"},\"theme\":\"dark\"}"

Interact with Page Elements

Ask: "Click the login button and type 'test@example.com' into the email field."

# Agent sequences multiple tools:
1. getElement(selector: "#login-btn") → click
2. getElement(selector: "#email-input") → type("test@example.com")

Step 6: Common Patterns for Development

Automated Visual Regression

Take screenshots before and after a code change to compare visually:

Ask agent to navigate to your local dev server
Take a "before" screenshot
Make your code changes
Reload and take an "after" screenshot

Performance Profiling

The MCP server exposes performance metrics. Ask your agent: "What is the LCP and FCP for this page?" — and it will run the evaluation and report back.

Accessibility Auditing

Chain the evaluate tool with axe-core to check accessibility:

Tool: evaluate
Expression: `
  const axe = await import("https://unpkg.com/axe-core/axe.min.js");
  return axe.run();
`
Result: { violations: [...], passes: [...] }

Security Considerations

Only run on trusted pages. The MCP server gives your AI agent full control over Chrome. Never connect it while browsing untrusted sites.
Use a separate profile. The --user-data-dir flag is not optional for security. It isolates cookies, saved passwords, and extensions.
Close the debugging port when done. Anyone with access to port 9222 can control your browser. Kill Chrome or close the port after your session.

Troubleshooting

Problem	Solution
"Connection refused" on port 9222	Make sure Chrome is launched with `--remote-debugging-port=9222`
MCP server crashes on start	Check Node.js version (need 18+) and reinstall the package
Agent cannot find tools	Verify your `.mcp.json` syntax and that the server process is running
Screenshot is blank	Wait a few seconds after navigation for the page to fully load

What Comes Next

The Chrome DevTools MCP server is evolving fast. The project roadmap includes support for network inspection, service worker debugging, and multi-tab management. As AI coding agents become more capable, having direct browser access transforms them from code-only assistants into full-stack development partners.

Start with the basics — navigate, screenshot, evaluate — and gradually explore more advanced patterns. The more you use it, the more you will discover ways to make your AI agent an extension of your debugging workflow.