chrome-devtoolsSafety 100Repository ShareFavorite skill

Core Concepts

Browser lifecycle: Browser starts automatically on first tool call using a persistent Chrome profile. Configure via CLI args in the MCP server configuration: npx chrome-devtools-mcp@latest --help.

Page selection: Tools operate on the currently selected page. Use list_pages to see available pages, then select_page to switch context.

Element interaction: Use take_snapshot to get page structure with element uids. Each element has a unique uid for interaction. If an element isn't found, take a fresh snapshot - the element may have been removed or the page changed.

Using a local fork (Codex CLI)

If you are developing a local version of the MCP server, point Codex to your local entry file instead of npx ...@latest.

• Build once (and rebuild after changes): npm run build
• Configure Codex to launch your local server (stdio):
  • codex mcp remove chrome-devtools (if it already exists)
  • codex mcp add chrome-devtools -- node /absolute/path/to/build/src/index.js
• Add server flags by appending them to the command, for example:
  • codex mcp add chrome-devtools -- node /absolute/path/to/build/src/index.js --headless
  • codex mcp add chrome-devtools -- node /absolute/path/to/build/src/index.js --browser-url=http://127.0.0.1:9222

Workflow Patterns

Before interacting with a page

1. Navigate: navigate_page or new_page
2. Wait: wait_for to ensure content is loaded if you know what you look for.
3. Snapshot: take_snapshot to understand page structure
4. Interact: Use element uids from snapshot for click, fill, etc.

Debugging: breakpoints and “hooks”

Use the debugger_* tools to set breakpoints/logpoints and to step through code. A practical flow:

1. Ensure the right tab is active: list_pages → select_page
2. Enable debugging: debugger_enable
3. Find target script(s):
   • list_scripts (then narrow down)
   • search_scripts to locate filenames/URLs by keyword
   • If bundled/minified: pretty_print_script, then use search_pretty_script
4. Set a breakpoint/logpoint:
   • By URL: debugger_set_breakpoint_by_url
   • By script id: debugger_set_breakpoint_by_script_id
   • By pretty location (after pretty print): debugger_set_breakpoint_by_pretty_location
   • Logpoint variants: debugger_set_logpoint_by_*
5. Trigger the code path (use click/fill/press_key or evaluate_script)
6. Wait for pause + inspect:
   • debugger_wait_for_paused / debugger_get_paused_state
   • Evaluate in the paused frame: debugger_evaluate_on_call_frame
   • Inspect objects: runtime_get_properties
7. Step/continue: debugger_step_over / debugger_step_into / debugger_step_out / debugger_resume

“Hook” style breakpoints (useful when you don’t know the exact line yet):

• DOM mutation points: debugger_set_dom_breakpoint (and manage via debugger_list_dom_breakpoints / debugger_remove_dom_breakpoint)
• Event listener hooks: debugger_set_event_listener_breakpoint (list/remove available)
• XHR/fetch hooks: debugger_set_xhr_breakpoint
• Instrumentation hooks: debugger_set_instrumentation_breakpoint
• Exceptions: debugger_set_pause_on_exceptions

Housekeeping:

• Update conditions: debugger_update_breakpoint_condition
• List/remove breakpoints: debugger_list_breakpoints / debugger_remove_breakpoint
• Reset state: debugger_clear_breakpoints (and debugger_clear_dom_breakpoints)
• If you pretty-print, map positions: debugger_map_pretty_location_to_original

Efficient data retrieval

• Use filePath parameter for large outputs (screenshots, snapshots, traces)
• Use pagination (pageIdx, pageSize) and filtering (types) to minimize data
• Set includeSnapshot: false on input actions unless you need updated page state

Tool selection

• Automation/interaction: take_snapshot (text-based, faster, better for automation)
• Visual inspection: take_screenshot (when user needs to see visual state)
• Additional details: evaluate_script for data not in accessibility tree

Network and console triage

• Network:
  • List: list_network_requests (use resourceTypes, pagination)
  • Inspect one: get_network_request (save bodies to files when large)
• Console:
  • List: list_console_messages (use types, pagination)
  • Inspect one: get_console_message

Performance workflow

1. Navigate to the target: navigate_page / new_page
2. Start trace: performance_start_trace (optionally reload)
3. Reproduce interaction (click/scroll/type)
4. Stop trace: performance_stop_trace
5. Analyze: performance_analyze_insight

Inputs, dialogs, and uploads

• Keyboard: press_key (shortcuts, submit, navigation)
• Hover/drag: hover, drag
• Forms: fill_form (batch fill)
• Dialogs (alert/confirm/prompt): handle_dialog
• File upload: upload_file (use the file input element uid)

Emulation and viewport

• Device/viewport simulation: emulate
• Resize: resize_page

Parallel execution

You can send multiple tool calls in parallel, but maintain correct order: navigate → wait → snapshot → interact.

Troubleshooting

If chrome-devtools-mcp is insufficient, guide users to use Chrome DevTools UI:

• https://developer.chrome.com/docs/devtools
• https://developer.chrome.com/docs/devtools/ai-assistance