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

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

bash scripts/check_chrome.sh <environment>

The script outputs

status:installed

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:

bash

claude mcp list | grep -i chrome

If not installed, install with:

bash

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

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

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:

bash

# 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

bash

# 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)

cmd

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)

bash

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

bash

# 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)

bash

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

powershell

winget install Google.Chrome

Option 3: Using Chocolatey

powershell

choco install googlechrome

Option 4: PowerShell direct download

powershell

$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

bash scripts/check_chrome.sh <environment>

MCP Configuration

Quick Install

bash

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

json

{
  "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:

json

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

Custom Viewport for Mobile Testing

json

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

Using Chrome Canary/Beta

json

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

With Debug Logging

json

{
  "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:

json

{
  "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:

Navigate to
```
chrome://inspect/#remote-debugging
```
Follow the dialog to allow debugging connections

Step 2: Configure MCP with

--autoConnect

json

{
  "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.

json

{
  "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

Test MCP server runs:
bash
```
npx chrome-devtools-mcp@latest --help
```

Verify Chrome is listening:

bash

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

Check for existing Chrome processes:

bash

# 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:

Disable sandboxing for chrome-devtools-mcp in your MCP client
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:

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

devtools

NPX Install

Tags

SKILL.md Content

Chrome DevTools MCP Setup

Overview

Why Give Claude Browser Access?

Quick Start Workflow

Step 1: Detect Environment

Step 2: Verify Chrome Installation

Step 3: Check MCP Server Status

Step 4: Detect Running Dev Server

Step 5: Launch Chrome with Debugging

Platform-Specific Commands

WSL2 / Linux

Windows (CMD/PowerShell)

Chrome Installation

Linux / WSL2

Windows

Verify Installation

MCP Configuration

Quick Install

Configuration Reference

Basic Configuration

Headless with Isolated Profile

Custom Viewport for Mobile Testing

Using Chrome Canary/Beta

With Debug Logging

WebSocket Connection with Auth Headers

Connection Methods

Method 1: Manual Connection (Recommended)

Method 2: Auto-Connect (Chrome 145+)

Method 3: Let MCP Launch Chrome

User Data Directory

Troubleshooting

Quick Checks

Common Issues

Known Limitations

Operating System Sandboxes

Security Considerations

Verification