chrome-devtools-mcp + Claude Code Browser Automation Setup: 5 Real Pitfalls and Complete Configuration Guide

AI Coding ToolsClaude CodeBrowser AutomationMCP

Why You Need chrome-devtools-mcp

If you've used Claude Code to write frontend code, you've hit this wall: Claude Code can generate React components and debug APIs, but it can't see what's actually happening in the browser. Refreshing pages, taking screenshots, clicking buttons to verify — all manual.

chrome-devtools-mcp is Google Chrome team's official MCP server (GitHub ⭐ 45,086) that exposes Chrome DevTools Protocol directly to Claude Code. Once configured, you can control a live browser with natural language: screenshot and analyze UI, debug network errors, inject JavaScript, capture performance traces.

This post documents 5 real pitfalls I hit during setup — each with actual error messages, root cause, and copy-paste fix.

🛠️ Prerequisites

**OS**: macOS 14+ / Ubuntu 22.04+ / Windows 11
**Chrome**: Chrome 122+ (latest stable recommended)
**Node.js**: 18+ (`node --version`)
**Claude Code**: 0.6.0+ (`claude --version`)
**Verify MCP package**: `npx chrome-devtools-mcp --version` (auto-downloads on first run)

🚀 Setup Steps

Step 1: Launch Chrome with Remote Debugging

This is where most people get stuck. Chrome doesn't open debugging ports by default.

macOS:

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

Ubuntu/Linux:

google-chrome \
  --remote-debugging-port=9222 \
  --user-data-dir=/tmp/chrome-debug

Windows:

"C:\Program Files\Google\Chrome\Application\chrome.exe" ^
  --remote-debugging-port=9222 ^
  --user-data-dir="C:\tmp\chrome-debug"

Verify the debugging port is open:

curl -s http://localhost:9222/json/version | grep "webSocketDebuggerUrl"
# Returns: "webSocketDebuggerUrl": "ws://127.0.0.1:9222/devtools/browser/xxx"

> ⚠️ **Note**: Launching Chrome with --remote-debugging-port opens a second Chrome window (with debugging). This is separate from your main browser — cookies are not shared.

Step 2: Configure Claude Code MCP Server

Add to ~/.config/claude/claude_desktop_config.json (macOS/Linux) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

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

> --no-usage-statistics: Prevents Chrome DevTools MCP from sending usage data to Google (enable if privacy-sensitive).

Restart Claude Code: exit current session and re-enter with claude.

Step 3: Verify MCP Connection

In Claude Code:

/mcp list

You should see chrome-devtools in the list with connected status.

Or test directly:

Open https://example.com using chrome-devtools and send me a screenshot

Claude Code will use the MCP tool to open the page in real Chrome.

💣 Pitfall Fixes

Pitfall 1: Chrome Debug Port Already in Use (EADDRINUSE)

Error:

Error: listen EADDRINUSE 0.0.0.0:9222

Cause: Port 9222 is occupied. Common conflicts: another Chrome instance, Jenkins, or other DevTools tools.

Fix:

Find the conflicting process:

# macOS
lsof -i :9222 | grep LISTEN

# Ubuntu
sudo lsof -i :9222 | grep LISTEN

# Windows
netstat -ano | findstr :9222

Once you have the PID:

Another Chrome → close it, or use a different port
Other service → stop it or change the port

Alternative port (recommended):

google-chrome --remote-debugging-port=9333 --user-data-dir=/tmp/chrome-debug

Update Claude Code MCP config:

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": ["chrome-devtools-mcp@latest", "--port=9333", "--no-usage-statistics"]
    }
  }
}

Pitfall 2: MCP Connected but Tool Calls Fail with 400 Bad Request

Error:

Error: 400 Bad Request: Target closed

**Cause**: Debug port is accessible, but --user-data-dir has permission issues or stale lock files.

Fix:

Kill all Chrome instances and rebuild the user data directory:

# Close all Chrome
pkill -f "Google Chrome"  # macOS/Linux
taskkill /F /IM chrome.exe  # Windows

# Remove stale directory
rm -rf /tmp/chrome-debug

# Restart Chrome
google-chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-debug

# Verify
curl -s http://localhost:9222/json | head -5

> **Tip**: Use a fixed --user-data-dir path and manually clean it before each session to avoid stale lock files.

Pitfall 3: MCP Server Version Out of Sync with Chrome Protocol

Error:

Error: Protocol version mismatch. Expected CDP version 1.45, got 1.43

**Cause**: chrome-devtools-mcp version doesn't match Chrome's embedded DevTools Protocol version. Chrome updates monthly; npx cache may have an outdated MCP.

Fix:

Force latest version (pulls fresh on every run):

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

If still failing, clear npx cache manually:

npx cache clean --force
npx chrome-devtools-mcp --version

> **Tip**: Use @latest tag instead of pinning a version (e.g., @1.2.3) — this ensures compatibility with each new Chrome release.

Pitfall 4: macOS Gatekeeper Blocks npx Execution

**Symptom**: Chrome doesn't open, Claude Code shows no error, but MCP stays in connecting state forever.

**Cause**: macOS Gatekeeper blocks first-run of unsigned apps. The chrome-devtools-mcp binary in npx's temp directory may be blocked.

Fix:

Option A (recommended): Allow Node.js to run temp scripts:

xattr -d com.apple.quarantine ~/.npm/_npx/*/node_modules/chrome-devtools-mcp 2>/dev/null || true

Option B: Global install instead of npx:

npm install -g chrome-devtools-mcp
# Then MCP config uses:
"command": "chrome-devtools-mcp"

Option C: System Settings → Privacy & Security → find "blocked" → click "Open Anyway"

Pitfall 5: Claude Code Config JSON Syntax Error Crashes Startup

**Symptom**: Claude Code fails to launch, logs show JSON parse error.

**Cause**: claude_desktop_config.json has syntax errors (common: trailing commas, missing quotes, comments in wrong format).

Fix:

Validate JSON first:

cat ~/.config/claude/claude_desktop_config.json | python3 -m json.tool > /dev/null && echo "Valid JSON" || echo "Invalid JSON"

Common mistakes:

// ❌ Wrong: trailing commas
{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": ["chrome-devtools-mcp@latest"]
    },  // ← trailing comma NOT allowed
  }  // ← trailing comma NOT allowed
}

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

> **Tip**: Always validate with python3 -m json.tool before restarting Claude Code after config edits.

🔍 What You Can Do with chrome-devtools-mcp (Real Use Cases)

Once configured, these are real, usable scenarios:

Use Case 1: AI Screenshot + UI Analysis

Open https://github.com, take a screenshot, and tell me the dominant color palette

Use Case 2: Network Error Debugging

Open the console on https://example.com and list all 4xx/5xx errors with their URLs

Use Case 3: Automated Form Testing

Open the login page, fill in user: test@example.com, pass: Test123, and screenshot the result

Use Case 4: Performance Trace Analysis

Open https://example.com, run the Performance API, and report the First Contentful Paint time

Use Case 5: DOM Node Query

Find all divs with class containing "card" and list their text content

Advanced: Multiple Browser Profiles Isolation

Need multiple Claude Code instances, each connecting to a different Chrome profile? Use port isolation:

# Profile A - port 9222
google-chrome --remote-debugging-port=9222 \
  --user-data-dir=/tmp/chrome-profile-a

# Profile B - port 9223
google-chrome --remote-debugging-port=9223 \
  --user-data-dir=/tmp/chrome-profile-b

Corresponding MCP configs:

{
  "mcpServers": {
    "chrome-devtools-a": {
      "command": "npx",
      "args": ["chrome-devtools-mcp@latest", "--port=9222"]
    },
    "chrome-devtools-b": {
      "command": "npx",
      "args": ["chrome-devtools-mcp@latest", "--port=9223"]
    }
  }
}

TL;DR

chrome-devtools-mcp is a game changer for frontend developers — it gives Claude Code real eyes in the browser. The setup hits 5 common traps: port conflicts, user-data-dir permissions, protocol version mismatch, Gatekeeper blocking, and JSON syntax errors. All solvable.

Verification checklist:

[ ] `curl http://localhost:9222/json/version` returns JSON
[ ] Claude Code `/mcp list` shows chrome-devtools connected
[ ] Screenshot, DOM query, and console log reading all work

Related articles:

👉 Join MiniMax Token Plan: AI coding acceleration for businesses

👉 Join Zhipu Coding Plan: GLM-4.6/GLM-5 coding packages, China-stable, pay-per-token unlimited

👉 Join Aliyun AI: Top AI products with exclusive coupons for business innovation

📌 This article was AI-assisted generated and human-reviewed | TechPassive — An AI-driven content testing site focused on real tool reviews

🔗 Recommended Tools

These are carefully selected tools. Using our affiliate links supports us to keep producing quality content:

☁️ DigitalOcean Cloud ⚡ Vultr VPS ⭐ MiniMax Token Plan 🧩 Zhipu Coding Plan 🎁 Zhipu 20M Tokens Gift 🤖 QoderWork CN (Refer & Earn) ☁️ Aliyun AI Products 📚 WordPress Books 🔍 WordPress SEO Books 🌐 Web Hosting Books 🐳 Docker Books 🐧 Linux Books 🐍 Python Books 💰 Affiliate Marketing 💵 Passive Income Books 🖥️ Server Books ☁️ Cloud Computing Books 🚀 DevOps Books

← Back to Home