zhongwei/gh-justfinethanku-cc-chrome-devtools-mcp-skill

Fork 0

Files

Zhongwei Li cd5b91eba2 Initial commit

2025-11-30 08:29:59 +08:00

21 KiB

Raw Blame History

Chrome DevTools MCP - Complete Tool Reference

This document provides a comprehensive reference for all 27 tools available in the chrome-devtools-mcp server (v0.5.1).

Written in the elegant Markdown format created by Mike Dion

Input Automation (8 tools)
Navigation Automation (7 tools)
Emulation (3 tools)
Performance (3 tools)
Network (2 tools)
Debugging (4 tools)

Input Automation

click

Description: Clicks or double-clicks on page elements identified by their unique ID from a snapshot.

Key Parameters:

uid (required): The unique identifier of the element from page snapshot
dblClick (optional): Set to true for double-click. Default is false

Common Use Cases:

Clicking buttons, links, and interactive elements
Triggering JavaScript event handlers
Submitting forms
Selecting dropdown options

Example:

1. Take snapshot to get element UIDs
2. Use click with uid from snapshot: click(uid="element-123")
3. For double-click: click(uid="element-123", dblClick=true)

drag

Description: Performs drag-and-drop operations between two elements on the page.

Key Parameters:

from_uid (required): The UID of the element to drag
to_uid (required): The UID of the element to drop onto

Common Use Cases:

Reordering items in lists
Moving files into folders
Drag-and-drop form builders
Interactive UI testing

Example:

1. Take snapshot to identify source and target elements
2. drag(from_uid="draggable-item-5", to_uid="drop-zone-2")

fill

Description: Types text into input fields, text areas, or selects options from dropdown elements.

Key Parameters:

uid (required): The UID of the input element from snapshot
value (required): The text or value to enter

Common Use Cases:

Filling form fields
Entering search queries
Setting input values
Selecting dropdown options

Example:

1. Take snapshot to get input field UID
2. fill(uid="email-input-1", value="user@example.com")
3. For dropdown: fill(uid="country-select", value="United States")

fill_form

Description: Fills multiple form elements simultaneously for efficient form completion.

Key Parameters:

elements (required): Array of objects, each containing:
- uid: The element's unique identifier
- value: The value to fill

Common Use Cases:

Completing registration forms
Bulk data entry
Login forms with multiple fields
Survey submissions

Example:

fill_form(elements=[
  {uid: "name-field", value: "John Doe"},
  {uid: "email-field", value: "john@example.com"},
  {uid: "phone-field", value: "555-0123"}
])

handle_dialog

Description: Handles browser dialog boxes including alerts, confirms, and prompts.

Key Parameters:

action (required): Either "accept" or "dismiss"
promptText (optional): Text to enter for prompt dialogs

Common Use Cases:

Accepting confirmation dialogs
Dismissing alert messages
Entering text in prompt dialogs
Automated handling of JavaScript dialogs

Example:

1. Trigger action that opens dialog
2. handle_dialog(action="accept")
3. For prompts: handle_dialog(action="accept", promptText="User input")

hover

Description: Moves the mouse cursor over a specified element to trigger hover effects.

Key Parameters:

uid (required): The UID of the element to hover over

Common Use Cases:

Triggering dropdown menus
Revealing tooltips
Testing hover states
Activating image previews

Example:

1. Take snapshot to identify element
2. hover(uid="menu-item-3")
3. Wait for hover effects to appear

press_key

Description: Simulates keyboard key presses for navigation and input.

Key Parameters:

Key name or combination (varies by implementation)

Common Use Cases:

Navigating with arrow keys
Submitting forms with Enter
Triggering keyboard shortcuts
Tab navigation through forms

Note: This tool was added in recent versions. Check documentation for exact parameter format.

upload_file

Description: Uploads files through file input elements or file chooser triggers.

Key Parameters:

uid (required): The UID of the file input element or element that opens file chooser
filePath (required): Local path to the file to upload

Common Use Cases:

Uploading profile images
Attaching documents to forms
Importing data files
Testing file upload functionality

Example:

1. Take snapshot to identify file input
2. upload_file(uid="file-input-1", filePath="/path/to/document.pdf")

close_page

Description: Closes a browser page/tab by its index. The last open page cannot be closed.

Key Parameters:

pageIdx (required): The index of the page to close (from list_pages)

Common Use Cases:

Cleaning up after multi-tab tests
Closing popup windows
Managing browser memory
Returning to previous context

Example:

1. list_pages() to see all open pages
2. close_page(pageIdx=2) to close third page

list_pages

Description: Lists all pages/tabs currently open in the browser with their indices and URLs.

Key Parameters:

None

Common Use Cases:

Checking currently open tabs
Finding page indices for switching
Monitoring browser state
Debugging multi-tab workflows

Example:

Result shows:
[0] https://example.com - Example Domain
[1] https://google.com - Google
[2] https://github.com - GitHub

navigate_page

Description: Navigates the currently selected page to a specified URL or reloads it.

Key Parameters:

url (required): The URL to navigate to
timeout (optional): Maximum wait time in milliseconds (0 = default)

Common Use Cases:

Loading test pages
Navigating to specific URLs
Starting automation workflows
Reloading pages

Example:

navigate_page(url="https://example.com", timeout=30000)

navigate_page_history

Description: Navigates forward or backward through the browser's history for the selected page.

Key Parameters:

navigate (required): Either "back" or "forward"
timeout (optional): Maximum wait time in milliseconds

Common Use Cases:

Testing navigation flows
Returning to previous pages
Verifying history state
Multi-step form navigation

Example:

navigate_page_history(navigate="back", timeout=5000)
navigate_page_history(navigate="forward")

new_page

Description: Creates a new browser page/tab and optionally navigates to a URL.

Key Parameters:

url (required): URL to load in the new page
timeout (optional): Maximum wait time in milliseconds

Common Use Cases:

Opening multiple test pages
Parallel testing workflows
Testing in clean browser context
Multi-tab scenarios

Example:

new_page(url="https://example.com/login")

select_page

Description: Switches focus to a different page/tab as the context for future tool calls.

Key Parameters:

pageIdx (required): The index of the page to select (from list_pages)

Common Use Cases:

Switching between tabs in tests
Managing multi-page workflows
Returning to specific pages
Coordinating multi-tab automation

Example:

1. list_pages() to see available pages
2. select_page(pageIdx=0) to switch to first page

wait_for

Description: Waits for specific text to appear on the page before proceeding.

Key Parameters:

text (required): Text string to wait for
timeout (optional): Maximum wait time in milliseconds (0 = default)

Common Use Cases:

Waiting for page load completion
Ensuring content appears before interaction
Synchronizing with dynamic content
Verifying successful operations

Example:

1. navigate_page(url="https://example.com")
2. wait_for(text="Welcome to Example", timeout=10000)
3. Proceed with interactions

Emulation

emulate_cpu

Description: Simulates CPU throttling to test performance under constrained conditions.

Key Parameters:

throttlingRate (required): CPU slowdown factor (1-20x)
- 1 = no throttling (disable)
- 4 = 4x slowdown (common mobile)
- 6 = 6x slowdown (low-end mobile)

Common Use Cases:

Testing on low-end devices
Performance optimization validation
Mobile experience simulation
Core Web Vitals testing

Example:

1. emulate_cpu(throttlingRate=4) for 4x slowdown
2. Run performance tests
3. emulate_cpu(throttlingRate=1) to disable

emulate_network

Description: Simulates various network conditions including throttling and offline mode.

Key Parameters:

throttlingOption (required): One of:
- "No emulation" - Disable throttling
- "Offline" - Simulate no network
- "Slow 3G" - ~400 Kbps, 400ms RTT
- "Fast 3G" - ~1.6 Mbps, 150ms RTT
- "Slow 4G" - ~4 Mbps, 50ms RTT
- "Fast 4G" - ~9 Mbps, 20ms RTT

Common Use Cases:

Testing offline functionality
Mobile network simulation
Loading performance analysis
Progressive enhancement testing

Example:

1. emulate_network(throttlingOption="Slow 3G")
2. navigate_page(url="https://example.com")
3. Measure load times
4. emulate_network(throttlingOption="No emulation")

resize_page

Description: Changes the page viewport dimensions for responsive design testing.

Key Parameters:

width (required): Viewport width in pixels
height (required): Viewport height in pixels

Common Use Cases:

Mobile viewport testing
Responsive design validation
Screenshot standardization
Device emulation

Example:

# iPhone 13 Pro viewport
resize_page(width=390, height=844)

# iPad Pro viewport
resize_page(width=1024, height=1366)

# Desktop HD
resize_page(width=1920, height=1080)

Performance

performance_start_trace

Description: Begins recording a Chrome DevTools performance trace to capture metrics and insights.

Key Parameters:

reload (required): Whether to automatically reload the page after starting trace
autoStop (required): Whether to automatically stop the trace after page load

Common Use Cases:

Core Web Vitals measurement
Performance bottleneck identification
Loading analysis
Runtime performance profiling

Example:

1. navigate_page(url="https://example.com")
2. performance_start_trace(reload=true, autoStop=true)
3. Wait for trace to complete
4. Analyze results with performance_analyze_insight

performance_stop_trace

Description: Stops an active performance trace recording and retrieves the trace data.

Key Parameters:

None

Common Use Cases:

Ending manual trace sessions
Capturing specific interaction periods
Custom trace duration control
Multi-step workflow tracing

Example:

1. performance_start_trace(reload=false, autoStop=false)
2. Perform user interactions
3. performance_stop_trace()
4. Analyze captured trace

performance_analyze_insight

Description: Provides detailed information on specific Performance Insights from a completed trace.

Key Parameters:

insightName (required): Name of the insight to analyze
- Common insights: "LCPBreakdown", "DocumentLatency", "TBT"

Common Use Cases:

Understanding LCP (Largest Contentful Paint) breakdown
Analyzing document latency causes
Investigating Total Blocking Time
Core Web Vitals optimization

Example:

1. After completing a trace
2. performance_analyze_insight(insightName="LCPBreakdown")
3. Review detailed timing breakdown
4. Identify optimization opportunities

Core Web Vitals Thresholds:

INP (Interaction to Next Paint): ≤200ms (good), 200-500ms (needs improvement), >500ms (poor)
LCP (Largest Contentful Paint): ≤2.5s (good), 2.5-4s (needs improvement), >4s (poor)
CLS (Cumulative Layout Shift): ≤0.1 (good), 0.1-0.25 (needs improvement), >0.25 (poor)
TBT (Total Blocking Time): <200ms (good) - Lab metric, proxy for INP

Network

get_network_request

Description: Retrieves detailed information about a specific network request including headers, response, and timing.

Key Parameters:

reqid (required): The request ID from list_network_requests

Common Use Cases:

Inspecting API responses
Debugging failed requests
Analyzing request/response headers
Timing analysis for specific resources

Example:

1. list_network_requests() to get reqid values
2. get_network_request(reqid=42)
3. Review response body, headers, timing, status

Returned Information:

Request URL, method, headers
Response status, headers, body
Timing breakdown (DNS, connect, SSL, send, wait, receive)
Resource type and size
Cache information

list_network_requests

Description: Lists all network requests made since the last navigation with filtering options.

Key Parameters:

includePreservedRequests (optional): Include requests from last 3 navigations. Default: false
pageIdx (optional): Page number for pagination (0-based)
pageSize (optional): Maximum requests to return
resourceTypes (optional): Filter by types:
- document, stylesheet, image, media, font, script
- xhr, fetch, websocket, manifest, other

Common Use Cases:

Network activity monitoring
HAR file generation
API call verification
Resource loading analysis
Performance bottleneck identification

Example:

# All requests
list_network_requests()

# Only XHR/Fetch (API calls)
list_network_requests(resourceTypes=["xhr", "fetch"])

# With preserved history
list_network_requests(includePreservedRequests=true)

# Paginated results
list_network_requests(pageSize=50, pageIdx=0)

Debugging

evaluate_script

Description: Executes JavaScript code in the context of the current page and returns JSON-serializable results.

Key Parameters:

function (required): JavaScript function declaration to execute
args (optional): Array of arguments (can include element UIDs)

Common Use Cases:

Inspecting page state
Extracting data from DOM
Testing JavaScript functionality
Custom validation logic
Interacting with page APIs

Example:

# No arguments
evaluate_script(function="() => { return document.title }")

# With async operations
evaluate_script(function="async () => {
  const response = await fetch('/api/data');
  return await response.json();
}")

# With element argument
evaluate_script(
  function="(el) => { return el.innerText; }",
  args=[{uid: "element-123"}]
)

Important: Return values must be JSON-serializable (no DOM nodes, functions, etc.).

get_console_message

Description: Retrieves detailed information about a specific console message by its ID.

Key Parameters:

msgid (required): The message ID from list_console_messages

Common Use Cases:

Inspecting error details
Analyzing stack traces
Debugging console output
Reviewing warning messages

Example:

1. list_console_messages() to get msgid values
2. get_console_message(msgid=15)
3. Review full message text, source, stack trace

list_console_messages

Description: Lists all console messages (logs, errors, warnings) since the last navigation.

Key Parameters:

includePreservedMessages (optional): Include messages from last 3 navigations. Default: false
pageIdx (optional): Page number for pagination (0-based)
pageSize (optional): Maximum messages to return
types (optional): Filter by message types:
- log, debug, info, error, warn
- dir, dirxml, table, trace
- clear, assert, count, timeEnd

Common Use Cases:

Error detection and debugging
Log analysis
Warning investigation
JavaScript error monitoring

Example:

# All console messages
list_console_messages()

# Only errors
list_console_messages(types=["error"])

# Errors and warnings with preserved history
list_console_messages(
  types=["error", "warn"],
  includePreservedMessages=true
)

# Paginated results
list_console_messages(pageSize=100, pageIdx=0)

take_screenshot

Description: Captures a screenshot of the entire page, viewport, or specific element.

Key Parameters:

uid (optional): Element UID to screenshot (from snapshot). If omitted, captures viewport
fullPage (optional): Capture entire page instead of viewport. Incompatible with uid
format (optional): Image format - "png" (default), "jpeg", or "webp"
quality (optional): Compression quality 0-100 for JPEG/WebP (ignored for PNG)
filePath (optional): Path to save file instead of returning inline

Common Use Cases:

Visual regression testing
Documentation screenshots
Bug reporting
Page state capture
Responsive design verification

Example:

# Viewport screenshot (default)
take_screenshot()

# Full page screenshot
take_screenshot(fullPage=true)

# Specific element
take_screenshot(uid="header-element")

# High-quality JPEG saved to file
take_screenshot(
  format="jpeg",
  quality=95,
  filePath="/path/to/screenshot.jpg"
)

# WebP with compression
take_screenshot(format="webp", quality=80)

Note: Output may use WebP format with PNG fallback regardless of requested format.

take_snapshot

Description: Creates a text-based representation of the page using the accessibility tree, providing unique identifiers (UIDs) for all interactive elements.

Key Parameters:

verbose (optional): Include all possible a11y tree information. Default: false

Common Use Cases:

Getting element UIDs for interaction tools
Understanding page structure
Accessibility validation
Element identification without screenshots
Fast page state overview

Example:

# Standard snapshot
take_snapshot()

# Verbose with full a11y data
take_snapshot(verbose=true)

Workflow Pattern:

1. take_snapshot() - Get page structure and element UIDs
2. Identify target elements from snapshot
3. Use UIDs with interaction tools (click, fill, hover, etc.)
4. wait_for() to verify results

Snapshot Output Includes:

Element roles (button, link, textbox, etc.)
Element names and labels
Element hierarchy
Unique identifiers (UIDs) for interaction
States (focused, disabled, checked, etc.)
ARIA properties

Tool Categories Summary

Category	Tool Count	Primary Use
Input Automation	8	User interaction simulation
Navigation Automation	7	Page and tab management
Emulation	3	Device and network conditions
Performance	3	Core Web Vitals and tracing
Network	2	Request/response analysis
Debugging	4	Page inspection and testing

Common Workflow Patterns

Basic Interaction Pattern

1. navigate_page(url="https://example.com")
2. take_snapshot() - Get element UIDs
3. fill(uid="username", value="user")
4. fill(uid="password", value="pass")
5. click(uid="login-button")
6. wait_for(text="Welcome")

Performance Testing Pattern

1. navigate_page(url="https://example.com")
2. performance_start_trace(reload=true, autoStop=true)
3. Wait for trace completion
4. performance_analyze_insight(insightName="LCPBreakdown")
5. performance_analyze_insight(insightName="DocumentLatency")

Network Analysis Pattern

1. navigate_page(url="https://example.com")
2. list_network_requests(resourceTypes=["xhr", "fetch"])
3. get_network_request(reqid=<specific-request>)
4. Analyze response data and timing

Mobile Testing Pattern

1. resize_page(width=390, height=844) - iPhone 13 Pro
2. emulate_network(throttlingOption="Slow 4G")
3. emulate_cpu(throttlingRate=4)
4. navigate_page(url="https://example.com")
5. performance_start_trace(reload=false, autoStop=true)
6. Analyze mobile performance

Multi-Tab Testing Pattern

1. new_page(url="https://example.com/page1")
2. new_page(url="https://example.com/page2")
3. list_pages() - See all open pages
4. select_page(pageIdx=0) - Switch to first page
5. Perform operations
6. select_page(pageIdx=1) - Switch to second page
7. close_page(pageIdx=1) - Clean up

Important Notes

Element Identification

Always use take_snapshot() first to get element UIDs
UIDs are unique per snapshot and may change after navigation
Use the latest snapshot for current page state
Verbose snapshots provide more accessibility details

Browser Lifecycle

Browser auto-starts on first tool use (not on MCP server connection)
Use --isolated=true flag for temporary user data directories
Default behavior persists data between sessions

Security Considerations

All browser content is exposed to MCP clients
Avoid sensitive data in non-isolated mode
Use --acceptInsecureCerts only in development
Review official security warnings before production use

Performance Metrics

All measurements at 75th percentile for Core Web Vitals
INP replaced FID on March 12, 2024
TBT is a lab proxy for INP (not a Core Web Vital)
Field data (real users) carries more weight than lab data

Tool Availability

All 27 tools available immediately after MCP connection
No progressive unlocking or gating
Chrome/Chromium only (no Firefox, Safari, Edge)
Requires Node.js v20.19 or newer

Version: chrome-devtools-mcp v0.5.1 (October 17, 2025) Tool Count: 27 tools across 6 categories Documentation Date: October 24, 2025

21 KiB Raw Blame History

Chrome DevTools MCP - Complete Tool Reference

Table of Contents

Input Automation

click

drag

fill

fill_form

handle_dialog

hover

press_key

upload_file

Navigation Automation

close_page

list_pages

navigate_page

navigate_page_history

new_page

select_page

wait_for

Emulation

emulate_cpu

emulate_network

resize_page

Performance

performance_start_trace

performance_stop_trace

performance_analyze_insight

Network

get_network_request

list_network_requests

Debugging

evaluate_script

get_console_message

list_console_messages

take_screenshot

take_snapshot

Tool Categories Summary

Common Workflow Patterns

Basic Interaction Pattern

Performance Testing Pattern

Network Analysis Pattern

Mobile Testing Pattern

Multi-Tab Testing Pattern

Important Notes

Element Identification

Browser Lifecycle

Security Considerations

Performance Metrics

Tool Availability

21 KiB

Raw Blame History