Install Chrome DevTools MCP Server

Install the Chrome DevTools MCP server to enable debugging and network inspection capabilities.

What This Does

The Chrome DevTools MCP server provides:

Console inspection - View errors, warnings, and log messages
Network analysis - Inspect HTTP requests and responses
JavaScript evaluation - Run code in page context
Performance tracing - Analyze page performance
Screenshots - Capture page state

Installation Command

Run this command to install:

claude mcp add chrome-devtools -- npx -y chrome-devtools-mcp@latest

Scope Options

--scope local (default): Available only in current project
--scope project: Shared with team via .mcp.json
--scope user: Available across all your projects

# Install for user (all projects)
claude mcp add chrome-devtools --scope user -- npx -y chrome-devtools-mcp@latest

# Install for project (team shared)
claude mcp add chrome-devtools --scope project -- npx -y chrome-devtools-mcp@latest

Common Configurations

Headless Mode

For headless operation (no visible browser):

claude mcp add chrome-devtools -- npx -y chrome-devtools-mcp@latest --headless

Auto-Connect to Running Chrome

Connect to an already-running Chrome instance (Chrome 145+):

claude mcp add chrome-devtools -- npx -y chrome-devtools-mcp@latest --autoConnect

Connect to Specific Browser URL

For sandboxed environments or remote debugging:

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

Custom Viewport

Set initial window size:

claude mcp add chrome-devtools -- npx -y chrome-devtools-mcp@latest --viewport 1920x1080

Isolated Sessions (No Persistence)

Use temporary profile that cleans up automatically:

claude mcp add chrome-devtools -- npx -y chrome-devtools-mcp@latest --isolated

Verify Installation

After installation:

Restart Claude Code
Run /mcp to see the chrome-devtools server
Test with: "Navigate to google.com and list console messages"

Available Tools After Installation

Debugging Tools

evaluate_script - Run JavaScript in page context
get_console_message - Get specific console message
list_console_messages - List all console messages
take_screenshot - Capture page screenshots
take_snapshot - Capture accessibility snapshot

Network Tools

get_network_request - Get specific network request details
list_network_requests - List all network requests

Navigation & Input

navigate_page - Navigate to URL
click - Click elements
fill - Fill input fields
fill_form - Fill multiple form fields
wait_for - Wait for conditions

Performance Tools

performance_start_trace - Start performance trace
performance_stop_trace - Stop and analyze trace
performance_analyze_insight - Get performance insights

Page Management

new_page - Open new tab
close_page - Close current page
list_pages - List all open pages
select_page - Switch to specific page

Coexistence with Playwright

Chrome DevTools MCP works alongside Playwright MCP:

Use Case	Recommended Tool
QA Testing / Automation	Playwright
Debugging / Network inspection	Chrome DevTools
Form filling / Navigation	Either
Console inspection	Chrome DevTools
Accessibility snapshots	Either
Performance analysis	Chrome DevTools

Both can be installed simultaneously - they use different tool namespaces:

Playwright: mcp__playwright__*
Chrome DevTools: mcp__chrome-devtools__*

Browser Connection Modes

Mode 1: Managed (Default) - No Browser Setup

The MCP server launches and controls its own Chrome instance. No browser-side setup needed:

claude mcp add chrome-devtools -- npx -y chrome-devtools-mcp@latest

Best for: Simple debugging, isolated sessions, no existing login state needed.

Mode 2: Auto-Connect (Chrome 145+)

Connect to your regular Chrome browser to debug with your logged-in sessions.

Browser setup: Launch Chrome with remote debugging enabled:

# macOS
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222

# Linux
google-chrome --remote-debugging-port=9222

# Windows
chrome.exe --remote-debugging-port=9222

Install command:

claude mcp add chrome-devtools -- npx -y chrome-devtools-mcp@latest --autoConnect

Best for: Debugging pages that require your authentication/cookies.

Mode 3: Browser URL

For sandboxed environments or when auto-connect doesn't work.

Browser setup: Same as auto-connect - launch Chrome with --remote-debugging-port=9222

Install command:

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

Best for: Sandboxed environments, remote debugging, CI/CD pipelines.

Creating a Chrome Shortcut with Remote Debugging

macOS

Create an Automator app or alias:

alias chrome-debug='/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222'

Linux

Create a desktop shortcut with the --remote-debugging-port=9222 flag.

Windows

Copy Chrome shortcut
Right-click > Properties
Add --remote-debugging-port=9222 to Target field

Troubleshooting

Browser Won't Launch (Managed Mode)

On macOS with sandboxing restrictions:

# Use auto-connect mode instead
claude mcp add chrome-devtools -- npx -y chrome-devtools-mcp@latest --autoConnect

Connection Refused (Auto-Connect/Browser URL)

Verify Chrome is running with remote debugging:
- Visit http://127.0.0.1:9222/json in another browser
- Should show JSON with open tabs
Check no other process is using port 9222
Ensure Chrome was started with --remote-debugging-port=9222

Port Already in Use

# Use a different port
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9333

# Then connect with:
claude mcp add chrome-devtools -- npx -y chrome-devtools-mcp@latest --browserUrl http://127.0.0.1:9333

Execution Instructions

When the user runs this command:

Determine scope from arguments or default to local
Check for options:
- --headless -> add --headless flag
- --auto-connect -> add --autoConnect flag

Run installation:

claude mcp add chrome-devtools [--scope <scope>] -- npx -y chrome-devtools-mcp@latest [options]

Verify success by checking output
Inform user to restart Claude Code to use the new MCP server

install-chrome-devtools-mcp