Comprehensive Chrome DevTools automation for performance testing, Core Web Vitals measurement (INP, LCP, CLS), network monitoring, accessibility validation, responsive testing, and browser automation...
This skill enables automated Chrome browser testing and performance analysis using the Chrome DevTools Protocol (CDP) via the chrome-devtools-mcp server. It provides access to 27 professional-grade tools for web application testing, performance measurement, accessibility validation, and browser automation.
Key capabilities:
Browser support: Chrome/Chromium only (stable, beta, dev, canary channels)
Node.js requirement: v20.19 or newer
# Add to Claude Code via CLI
claude mcp add chrome-devtools npx chrome-devtools-mcp@latest
# Verify installation
claude mcp list
{
"mcpServers": {
"chrome-devtools": {
"command": "npx",
"args": [
"chrome-devtools-mcp@latest",
"--isolated=true",
"--viewport=1920x1080"
]
}
}
}
--isolated=true for security (creates temporary user data directories that auto-cleanup)Three official metrics measured at 75th percentile of page loads:
Interaction to Next Paint (INP) - Replaced FID on March 12, 2024
Largest Contentful Paint (LCP)
Cumulative Layout Shift (CLS)
Total Blocking Time (TBT) is NOT a Core Web Vital - it's a lab proxy metric for INP.
Measure Core Web Vitals and analyze performance bottlenecks:
1. Start performance trace: performance_start_trace
2. Navigate to target URL: navigate_page
3. Wait for page load: wait_for
4. Stop trace and get metrics: performance_stop_trace
5. Analyze specific insights: performance_analyze_insight
Metrics captured:
Example:
performance_start_trace with reload=true, autoStop=false
wait_for page to stabilize
performance_stop_trace
performance_analyze_insight with insightName="LCPBreakdown"
Capture all HTTP requests/responses with timing details:
1. Navigate to URL: navigate_page
2. List all network requests: list_network_requests
3. Get specific request details: get_network_request
Captured data:
Export as HAR: Use list_network_requests to generate HTTP Archive v1.2 format
Filter requests:
list_network_requests with resourceTypes=["xhr", "fetch", "document"]
list_network_requests with pageSize=50, pageIdx=0
Inspect accessibility tree for WCAG compliance:
1. Navigate to page: navigate_page
2. Take accessibility snapshot: take_snapshot
3. Interact with elements using UIDs
Snapshot provides:
Example workflow:
take_snapshot verbose=false (returns text-based a11y tree)
# Identify element UIDs from snapshot
click uid="element-123"
fill uid="input-456" value="test data"
Test across devices and network conditions:
1. Resize viewport: resize_page width=375 height=667
2. Emulate network: emulate_network throttlingOption="Slow 3G"
3. Emulate CPU: emulate_cpu throttlingRate=4
4. Take screenshot: take_screenshot fullPage=true
Device emulation options:
Screenshot formats: PNG, JPEG, WebP (with quality settings)
Automated form filling, navigation, and interaction:
1. Take snapshot to get element UIDs: take_snapshot
2. Fill form fields: fill_form elements=[{uid, value}, ...]
3. Click buttons: click uid="submit-button"
4. Handle dialogs: handle_dialog action="accept"
5. Wait for results: wait_for text="Success"
Interaction tools:
Navigation tools:
Work with multiple pages and frames:
1. List open pages: list_pages
2. Create new page: new_page url="https://example.com"
3. Switch context: select_page pageIdx=1
4. Close pages: close_page pageIdx=2
Frame handling:
1. resize_page width=390 height=844 (iPhone 14 Pro)
2. emulate_network throttlingOption="Fast 4G"
3. emulate_cpu throttlingRate=4
4. performance_start_trace reload=true
5. performance_stop_trace
6. performance_analyze_insight insightName="DocumentLatency"
1. navigate_page url="https://example.com"
2. list_network_requests resourceTypes=["script", "fetch", "xhr"]
3. Filter by: pageSize=100, pageIdx=0, includePreservedRequests=true
4. get_network_request reqid=123 (detailed timing/headers/body)
1. navigate_page url="https://example.com"
2. take_snapshot verbose=true (full a11y tree with all properties)
3. Validate: roles, names, ARIA attributes, relationships
4. Test interactions: click, fill, keyboard navigation via UIDs
1. Define breakpoints: [320, 768, 1024, 1920]
2. For each breakpoint:
- resize_page width=X height=Y
- take_screenshot format="png" quality=90
- take_snapshot (verify accessibility)
3. Compare layouts and a11y across sizes
27 tools available across 6 categories:
Input automation (8): click, drag, fill, fill_form, handle_dialog, hover, press_key, upload_file
Navigation (7): close_page, list_pages, navigate_page, navigate_page_history, new_page, select_page, wait_for
Emulation (3): emulate_cpu, emulate_network, resize_page
Performance (3): performance_analyze_insight, performance_start_trace, performance_stop_trace
Network (2): get_network_request, list_network_requests
Debugging (4): evaluate_script, get_console_message, list_console_messages, take_screenshot, take_snapshot
For detailed tool parameters and examples, see TOOLS.md
For complete workflow patterns, see WORKFLOWS.md
For Core Web Vitals thresholds and measurement guide, see METRICS.md
--browserUrl, -u <string> - Connect to running Chrome instance (port forwarding)--wsEndpoint, -w <string> - WebSocket endpoint for Chrome connection--wsHeaders <JSON> - Custom headers for authenticated WebSocket connections--headless <boolean> - Run in headless mode (default: false)--executablePath, -e <string> - Path to custom Chrome executable--channel <string> - Chrome channel: stable, canary, beta, dev (default: stable)--viewport <string> - Initial viewport size (format: WIDTHxHEIGHT, e.g., 1280x720)--isolated <boolean> - RECOMMENDED: Creates temporary user-data-dir, auto-cleanup (default: false)--user-data-dir <string> - Custom user data directory--acceptInsecureCerts <boolean> - Ignore certificate errors (SECURITY RISK - dev/test only)--proxyServer <string> - Proxy server configuration--logFile <string> - Path for debug logs (set DEBUG=* env var for verbose logs)--chromeArg <string> - Additional Chrome arguments (repeatable)View all options: npx chrome-devtools-mcp@latest --help
{
"mcpServers": {
"chrome-devtools": {
"command": "npx",
"args": [
"chrome-devtools-mcp@latest",
"--isolated=true",
"--headless=true",
"--viewport=1920x1080",
"--channel=stable"
]
}
}
}
# Launch Chrome with remote debugging
google-chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-profile
# Get WebSocket endpoint
curl http://127.0.0.1:9222/json/version | jq -r '.webSocketDebuggerUrl'
{
"mcpServers": {
"chrome-devtools": {
"command": "npx",
"args": [
"chrome-devtools-mcp@latest",
"--wsEndpoint=ws://127.0.0.1:9222/devtools/browser/<id>"
]
}
}
}
{
"mcpServers": {
"chrome-devtools-prod": {
"command": "npx",
"args": [
"chrome-devtools-mcp@latest",
"--browserUrl=http://127.0.0.1:9222",
"--isolated=true",
"--logFile=/var/log/chrome-devtools-mcp.log"
],
"env": {
"DEBUG": "*"
}
}
}
}
Official Chrome DevTools MCP security notice:
"chrome-devtools-mcp exposes content of the browser instance to the MCP clients allowing them to inspect, debug, and modify any data in the browser or DevTools. Avoid sharing sensitive or personal information that you don't want to share with MCP clients."
Use isolated mode for sensitive workflows
--isolated=true creates temporary user data directoriesCertificate handling caution
--acceptInsecureCerts is a security riskUser data directory management
--isolated or custom --user-data-dir for controlWebSocket authentication
--wsHeaders for authenticated connections--wsHeaders='{"Authorization":"Bearer token"}'--wsEndpointBrowser support: Chrome/Chromium only (no Firefox, Safari, Edge legacy)
Node.js requirement: v20.19 or newer (latest maintenance LTS)
Browser lifecycle: Browser auto-starts on first tool use, NOT on MCP server connection
Default persistence: User data directory persists between runs unless --isolated=true is used
Permission requirements:
Screenshot formats: Specified format (JPEG/PNG) for initial capture, final output uses WebP with PNG fallback
Tool availability: All 27 tools available immediately after connection; no progressive unlocking
