Chrome DevTools Debugging

Debug web applications by connecting to Chrome's DevTools Protocol. This skill enables:

• Console inspection: View errors, warnings, and log messages
• Network analysis: Monitor XHR/fetch requests with full headers/body
• Performance tracing: Record and analyze performance traces
• JavaScript evaluation: Execute code in browser context
• Authenticated session debugging: Connect to existing logged-in browsers

When to Use This Skill

Setup Requirements

Option 1: Connect to Existing Chrome (Recommended)

Start Chrome with remote debugging enabled:

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

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

# Windows
"C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222

Set the environment variable:

export CHROME_DEVTOOLS_URL=http://127.0.0.1:9222

Option 2: Chrome Auto-Connect (145+)

For Chrome 145+, enable remote debugging at chrome://inspect/#remote-debugging.

Progressive Disclosure Pattern

This skill uses progressive MCP disclosure for token efficiency:

Chrome DevTools MCP Server
         |
         v
Python Wrappers (.claude/ai-dev-kit/dev-tools/mcp_servers/chrome_devtools/)
         |
         v
Claude executes Python via Bash (on-demand)
         |
         v
Results returned (tools NOT in system prompt)

Benefits: 98%+ token reduction vs loading all MCP tools in system prompt.

Quick Examples

Get Console Errors

uv run python -c "
import sys; sys.path.insert(0, 'dev-tools')
from mcp_servers.chrome_devtools import console

errors = console.list_console_messages(types=['error'])
print(errors)
"

List Network Requests

uv run python -c "
import sys; sys.path.insert(0, 'dev-tools')
from mcp_servers.chrome_devtools import network

requests = network.list_network_requests(resource_types=['xhr', 'fetch'])
print(requests)
"

Execute JavaScript

uv run python -c "
import sys; sys.path.insert(0, 'dev-tools')
from mcp_servers.chrome_devtools import debug

title = debug.evaluate_script('document.title')
print(f'Page title: {title}')
"

Debug Authenticated Session

# 1. Log into the site manually in Chrome (started with --remote-debugging-port=9222)
# 2. Then analyze the authenticated state:

uv run python -c "
import sys; sys.path.insert(0, 'dev-tools')
from mcp_servers.chrome_devtools import navigation, network, debug

# List open tabs
pages = navigation.list_pages()
print(pages)

# Get auth tokens from localStorage
tokens = debug.evaluate_script('JSON.stringify(localStorage)')
print(f'localStorage: {tokens}')

# See recent API calls
api_calls = network.get_api_requests()
print(api_calls)
"

Available Tool Modules

console

• list_console_messages(types, page_size, page_idx) - Get console output
• get_console_message(message_id) - Get specific message details
• get_errors() - Convenience: get error messages only
• get_warnings() - Convenience: get warnings only

network

• list_network_requests(resource_types, page_size, page_idx) - List requests
• get_network_request(request_id) - Get full request/response details
• get_failed_requests() - Convenience: get 4xx/5xx requests
• get_api_requests() - Convenience: get XHR/fetch requests
• get_slow_requests(threshold_ms) - Convenience: get slow requests

performance

• start_trace(reload, auto_stop) - Start recording trace
• stop_trace() - Stop and get trace data
• get_insights() - Get available insight sets
• analyze_insight(insight_set_id, insight_name) - AI-powered insight analysis

debug

• evaluate_script(expression) - Execute JavaScript

navigation

• navigate_page(url, nav_type, ignore_cache, timeout) - Navigate page
• list_pages() - List all tabs
• select_page(page_idx, bring_to_front) - Switch to tab by index
• new_page(url, timeout) - Open new tab
• close_page(page_idx) - Close tab by index
• wait_for(text, timeout) - Wait for text on page

Red Flags

• Chrome not started with --remote-debugging-port=9222
• CHROME_DEVTOOLS_URL environment variable not set
• Port 9222 blocked by firewall
• Trying to use for screenshots (use browser-discovery instead)
• MCP server not installed (npx chrome-devtools-mcp@latest)

See Also

• reference.md - Full API documentation
• cookbook/console-debugging.md - Console debugging patterns
• cookbook/network-debugging.md - Network analysis patterns
• browser-discovery skill - For screenshots, basic automation
• Chrome DevTools Protocol