AgentSkillsCN

chrome-devtools

通过 MCP 利用 Chrome DevTools 实现高效调试、故障排除与浏览器自动化。适用于调试网页、自动化浏览器交互、分析性能，或检查网络请求时使用。

SKILL.md
--- frontmatter
name: chrome-devtools
description: Uses Chrome DevTools via MCP for efficient debugging, troubleshooting and browser automation. Use when debugging web pages, automating browser interactions, analyzing performance, or inspecting network requests.

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: