---

name: devtools description: This skill helps launch and configure the Chrome DevTools MCP server, giving Claude visual access to a live browser for debugging and automation. Use when the user asks to set up browser debugging, launch Chrome with DevTools, configure chrome-devtools-mcp, see what my app looks like, take screenshots of my web application, check the browser console, debug console errors, inspect network requests, analyse API responses, measure Core Web Vitals or page performance, run a Lighthouse audit, test button clicks or form submissions, automate browser interactions, fill out forms programmatically, simulate user actions, emulate mobile devices or slow networks, capture DOM snapshots, execute JavaScript in the browser, or troubleshoot Chrome DevTools MCP connection issues. Supports Windows, Linux, and WSL2 environments.

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 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 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 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 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 scripts/launch_chrome.sh wsl2 http://localhost:5173

# Headed (visible browser)
bash 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 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