Chrome devtools debugging

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

Use Case	This Skill	browser-discovery
Console error inspection	Yes	No
Network request analysis	Yes	Limited
Performance tracing	Yes	No
Authenticated sessions	Yes	No
Screenshots	No	Yes
Form filling	No	Yes
Basic navigation	Limited	Yes

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