Chrome DevTools MCP Setup

Overview

This skill automates the setup and launch of Chrome with remote debugging for use with the chrome-devtools-mcp server. It handles environment detection, Chrome installation verification, MCP configuration, and browser launch across Windows, Linux, and WSL2.

GitHub Repository: https://github.com/ChromeDevTools/chrome-devtools-mcp

Why Give Claude Browser Access?

Without browser access, Claude is "coding blindfolded" - making changes without seeing the results. The Chrome DevTools MCP server provides 26 specialised tools that give Claude eyes into your running application:

Category	Capabilities
Visual Inspection	Take screenshots, capture DOM snapshots, see rendered output
Console & Logging	Read console messages, catch JavaScript errors, debug issues
Network Analysis	Inspect API requests/responses, analyse headers, debug fetch calls
Performance	Record traces, measure Core Web Vitals (LCP, CLS, TBT), identify bottlenecks
User Simulation	Click elements, fill forms, drag-and-drop, handle dialogs
Device Emulation	Simulate mobile viewports, throttle CPU/network, test responsive design

This enables Claude to:

• Verify changes visually instead of guessing if CSS/layout is correct
• Debug runtime errors by reading actual console output
• Test user flows by simulating clicks and form submissions
• Identify performance issues with real Core Web Vitals data
• Catch regressions by comparing screenshots before/after changes

Quick Start Workflow

Execute these steps in order:

Step 1: Detect Environment

Run the environment detection script to determine the platform:

bash ${CLAUDE_PLUGIN_ROOT}/skills/devtools/scripts/detect_environment.sh

The script returns one of: windows, linux, or wsl2

Step 2: Verify Chrome Installation

Run the Chrome check script with the detected environment:

bash ${CLAUDE_PLUGIN_ROOT}/skills/devtools/scripts/check_chrome.sh <environment>

The script outputs status:installed or status:not_installed. If Chrome is not installed, the script provides detailed installation instructions. See the Chrome Installation section below for manual installation options.

IMPORTANT: Do not proceed to later steps until Chrome is installed and verified.

Step 3: Check MCP Server Status

Verify if chrome-devtools-mcp is configured:

claude mcp list | grep -i chrome

If not installed, install with:

claude mcp add chrome-devtools -- npx chrome-devtools-mcp@latest --browserUrl http://127.0.0.1:9222

Step 4: Detect Running Dev Server

Check for running dev servers on common ports:

bash ${CLAUDE_PLUGIN_ROOT}/skills/devtools/scripts/detect_dev_server.sh

This checks ports 5173, 5174, 5175, 3000, 3001, 8080, and 8000.

If no dev server is running and one is needed, offer to start it:

• For Vite projects: npm run dev
• For Next.js: npm run dev or npx next dev
• For React CRA: npm start

Step 5: Launch Chrome with Debugging

Launch Chrome with remote debugging enabled:

bash ${CLAUDE_PLUGIN_ROOT}/skills/devtools/scripts/launch_chrome.sh <environment> <url> [headed]

Arguments:

• <environment>: windows, linux, or wsl2
• <url>: Target URL (e.g., http://localhost:5173)
• [headed]: Optional - pass headed for visible browser, omit for headless (default)

Examples:

# Headless (default)
bash ${CLAUDE_PLUGIN_ROOT}/skills/devtools/scripts/launch_chrome.sh wsl2 http://localhost:5173

# Headed (visible browser)
bash ${CLAUDE_PLUGIN_ROOT}/skills/devtools/scripts/launch_chrome.sh wsl2 http://localhost:5173 headed

Platform-Specific Commands

WSL2 / Linux

# Headless
google-chrome --headless --remote-debugging-port=9222 --no-first-run --user-data-dir=/tmp/chrome-mcp http://localhost:5173 &

# Headed
google-chrome --remote-debugging-port=9222 --no-first-run --user-data-dir=/tmp/chrome-mcp http://localhost:5173 &

Windows (CMD/PowerShell)

REM Headless
start chrome.exe --headless --remote-debugging-port=9222 --no-first-run --user-data-dir=%TEMP%\chrome-mcp http://localhost:5173

REM Headed
start chrome.exe --remote-debugging-port=9222 --no-first-run --user-data-dir=%TEMP%\chrome-mcp http://localhost:5173

Chrome Installation

If Chrome is not detected, install it using one of these methods:

Linux / WSL2

Option 1: Direct download (recommended)

wget https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb
sudo apt install -y ./google-chrome-stable_current_amd64.deb

Option 2: Add Google's repository

# Add signing key
wget -q -O - https://dl.google.com/linux/linux_signing_key.pub | sudo gpg --dearmor -o /usr/share/keyrings/google-chrome.gpg

# Add repository
echo 'deb [arch=amd64 signed-by=/usr/share/keyrings/google-chrome.gpg] http://dl.google.com/linux/chrome/deb/ stable main' | sudo tee /etc/apt/sources.list.d/google-chrome.list

# Install
sudo apt update
sudo apt install -y google-chrome-stable

Option 3: Chromium (open-source alternative)

sudo apt update
sudo apt install -y chromium-browser

Windows

Option 1: Download from Google Visit https://www.google.com/chrome/ and run the installer.

Option 2: Using winget

winget install Google.Chrome

Option 3: Using Chocolatey

choco install googlechrome

Option 4: PowerShell direct download

$installer = "$env:TEMP\chrome_installer.exe"
Invoke-WebRequest -Uri "https://dl.google.com/chrome/install/latest/chrome_installer.exe" -OutFile $installer
Start-Process -FilePath $installer -Args "/silent /install" -Wait
Remove-Item $installer

Verify Installation

After installation, verify with:

bash ${CLAUDE_PLUGIN_ROOT}/skills/devtools/scripts/check_chrome.sh <environment>

MCP Configuration

Quick Install

claude mcp add chrome-devtools -- npx chrome-devtools-mcp@latest --browserUrl http://127.0.0.1:9222

Configuration Reference

All flags can be passed via the args array in .mcp.json:

Flag	Description	Default
--browserUrl, -u	Connect to running Chrome (e.g., http://127.0.0.1:9222)	-
--autoConnect	Auto-connect to Chrome 145+ with remote debugging enabled	false
--headless	Run in headless (no UI) mode	false
--isolated	Use temporary user-data-dir, auto-cleaned on close	false
--channel	Chrome channel: stable, canary, beta, dev	stable
--viewport	Initial viewport size (e.g., 1280x720, max 3840x2160 headless)	-
--executablePath, -e	Path to custom Chrome executable	-
--userDataDir	Custom user data directory	~/.cache/chrome-devtools-mcp/chrome-profile
--wsEndpoint, -w	WebSocket endpoint (alternative to --browserUrl)	-
--wsHeaders	Custom WebSocket headers as JSON (use with --wsEndpoint)	-
--proxyServer	Proxy server for Chrome	-
--acceptInsecureCerts	Ignore self-signed/expired certificate errors	false
--chromeArg	Additional Chrome launch arguments (array)	-
--logFile	Debug log file path (set DEBUG=* for verbose)	-
--categoryEmulation	Include emulation tools	true
--categoryPerformance	Include performance tools	true
--categoryNetwork	Include network tools	true

Basic Configuration

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

Headless with Isolated Profile

Best for CI/CD or automated testing - uses a temporary profile that's cleaned up automatically:

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

Custom Viewport for Mobile Testing

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": [
        "chrome-devtools-mcp@latest",
        "--browserUrl=http://127.0.0.1:9222",
        "--viewport=390x844"
      ]
    }
  }
}

Using Chrome Canary/Beta

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

With Debug Logging

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": [
        "chrome-devtools-mcp@latest",
        "--browserUrl=http://127.0.0.1:9222",
        "--logFile=/tmp/chrome-devtools-mcp.log"
      ],
      "env": {
        "DEBUG": "*"
      }
    }
  }
}

WebSocket Connection with Auth Headers

For connecting to remote Chrome instances with authentication:

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": [
        "chrome-devtools-mcp@latest",
        "--wsEndpoint=ws://127.0.0.1:9222/devtools/browser/<id>",
        "--wsHeaders={\"Authorization\":\"Bearer YOUR_TOKEN\"}"
      ]
    }
  }
}

To get the WebSocket endpoint, visit http://127.0.0.1:9222/json/version and look for webSocketDebuggerUrl.

Connection Methods

Method 1: Manual Connection (Recommended)

Start Chrome yourself with remote debugging, then connect via --browserUrl. This is the approach used in the Quick Start Workflow above.

When to use:

• Running Claude in a sandboxed environment
• Need full control over Chrome launch options
• Working with self-signed certificates

Method 2: Auto-Connect (Chrome 145+)

Let chrome-devtools-mcp automatically connect to a running Chrome instance.

Step 1: Enable remote debugging in Chrome:

1. Navigate to chrome://inspect/#remote-debugging
2. Follow the dialog to allow debugging connections

Step 2: Configure MCP with --autoConnect:

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

When to use:

• Sharing state between manual testing and Claude-driven testing
• Avoiding WebDriver sign-in blocks (some sites block automated browsers)
• Want Chrome to prompt for permission before Claude connects

Method 3: Let MCP Launch Chrome

If you omit --browserUrl and --autoConnect, the MCP server will launch its own Chrome instance.

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

When to use:

• Fully automated workflows
• No need to maintain browser state
• CI/CD pipelines

User Data Directory

By default, chrome-devtools-mcp uses a persistent profile at:

• Linux/macOS: $HOME/.cache/chrome-devtools-mcp/chrome-profile-$CHANNEL
• Windows: %HOMEPATH%/.cache/chrome-devtools-mcp/chrome-profile-$CHANNEL

This profile is shared across all MCP sessions, preserving cookies, local storage, and login state.

Use --isolated for a fresh, temporary profile that's automatically cleaned up when the browser closes.

Troubleshooting

For detailed troubleshooting steps, read references/troubleshooting.md.

Quick Checks

1. Test MCP server runs:

   npx chrome-devtools-mcp@latest --help
   

2. Verify Chrome is listening:

   curl -s http://127.0.0.1:9222/json/version
   

3. Check for existing Chrome processes:

   # Linux/WSL2
   pgrep -a chrome
   
   # Windows
   tasklist | findstr chrome
   

Common Issues

Issue	Solution
"Target closed" error	Close all Chrome instances, restart with debugging
Module not found	Clear npm cache: rm -rf ~/.npm/_npx && npm cache clean --force
Connection refused	Ensure Chrome launched with --remote-debugging-port=9222
Port already in use	Kill existing Chrome or use different port
Chrome won't start in sandbox	Use --browserUrl to connect to manually-started Chrome
WebDriver sign-in blocked	Use --autoConnect to connect to your normal browser session
VM-to-host connection fails	See references/troubleshooting.md for port forwarding guidance

Known Limitations

Operating System Sandboxes

Some MCP clients sandbox the server using macOS Seatbelt or Linux containers. In sandboxed environments, chrome-devtools-mcp cannot start Chrome (which requires its own sandbox permissions).

Workarounds:

1. Disable sandboxing for chrome-devtools-mcp in your MCP client
2. Use --browserUrl to connect to a Chrome instance started outside the sandbox

Security Considerations

The remote debugging port exposes your browser to any application on your machine. When debugging is enabled:

• Avoid browsing sensitive sites (banking, email with sensitive data)
• Use --isolated for a separate profile
• Close Chrome when done debugging

Verification

After setup, verify the connection works:

1. Chrome should be running with remote debugging
2. MCP server should connect to http://127.0.0.1:9222
3. Test with mcp__chrome-devtools__list_pages tool