devtools

Chrome DevTools MCP

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

Without browser access, Claude is "coding blindfolded" - making changes without seeing results. The Chrome DevTools MCP server provides 26 specialised tools across these categories:

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

Quick Start Workflow

Execute these steps in order:

Step 1: Detect Environment

bash scripts/detect_environment.sh

Returns one of: windows, linux, or wsl2

Step 2: Verify Chrome Installation

bash scripts/check_chrome.sh <environment>

Outputs status:installed or status:not_installed. If not installed, see references/chrome-installation.md for installation options.

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

Step 3: Check MCP Server Status

claude mcp list | grep -i chrome

If not installed:

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

For advanced configuration options and alternative connection methods, see references/mcp-configuration.md.

Step 4: Detect Running Dev Server

bash scripts/detect_dev_server.sh

Checks ports 5173, 5174, 5175, 3000, 3001, 8080, and 8000. If no dev server is running and one is needed, offer to start it.

Step 5: Launch Chrome with Debugging

bash scripts/launch_chrome.sh <environment> <url> [headed]

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

Step 6: Verify Connection

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

Once connected, test with the mcp__chrome-devtools__list_pages tool.

Quick Troubleshooting

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

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

References

• Chrome Installation: references/chrome-installation.md - platform-specific installation options
• MCP Configuration: references/mcp-configuration.md - all configuration flags, JSON examples, connection methods, platform commands, and known limitations
• Troubleshooting: references/troubleshooting.md - detailed error resolution, debugging with logs, and recovery scripts