| name | devtools |
| description | Chrome DevTools MCP setup and live-browser debugging for visual app inspection, console/network/performance triage, 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. Do NOT use for headless CI test runs - use Playwright tests directly. Do NOT use for Selenium/Puppeteer setup. |
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
