|
| 1 | +--- |
| 2 | +name: chrome-devtools-cli |
| 3 | +description: Use this to skill to write shell scripts or run shell commands to automate tasks in the browser or otherwise use Chrome DevTools via CLI. |
| 4 | +--- |
| 5 | + |
| 6 | +The `chrome-devtools-mcp` package includes a CLI interface that allows you to interact with the browser directly from your terminal. This is particularly useful for debugging or when you want an agent to generate scripts that automate browser actions. |
| 7 | + |
| 8 | +## Getting started |
| 9 | + |
| 10 | +Install the package globally to make the `chrome-devtools` command available: |
| 11 | + |
| 12 | +```sh |
| 13 | +npm i chrome-devtools-mcp@latest -g |
| 14 | +chrome-devtools status # check if install worked. |
| 15 | +``` |
| 16 | + |
| 17 | +## How it works |
| 18 | + |
| 19 | +The CLI acts as a client to a background `chrome-devtools-mcp` daemon. |
| 20 | + |
| 21 | +- **Automatic Start**: The first time you call a tool (e.g., `list_pages`), the CLI automatically starts the MCP server and the browser in the background if they aren't already running. |
| 22 | +- **Persistence**: The same background instance is reused for subsequent commands, preserving the browser state (open pages, cookies, etc.). |
| 23 | +- **Manual Control**: You can explicitly manage the background process using `start`, `stop`, and `status`. The `start` command forwards all subsequent arguments to the underlying MCP server (e.g., `--headless`, `--userDataDir`). |
| 24 | + |
| 25 | +Snapshots looks like this: |
| 26 | + |
| 27 | +``` |
| 28 | +uid=1_0 RootWebArea "Example Domain" url="https://example.com/" |
| 29 | + uid=1_1 heading "Example Domain" level="1" |
| 30 | + uid=1_2 StaticText "This domain is for use in documentation examples without needing permission. Avoid use in operations." |
| 31 | + uid=1_3 link "Learn more" url="https://iana.org/domains/example" |
| 32 | + uid=1_4 StaticText "Learn more |
| 33 | +``` |
| 34 | + |
| 35 | +## Command Usage |
| 36 | + |
| 37 | +The CLI supports all tools available in the Chrome DevTools MCP by default. |
| 38 | + |
| 39 | +```sh |
| 40 | +chrome-devtools <tool> [arguments] [flags] |
| 41 | +``` |
| 42 | + |
| 43 | +- **Required Arguments**: Passed as positional arguments. |
| 44 | +- **Optional Arguments**: Passed as flags (e.g., `--filePath`, `--fullPage`). |
| 45 | +- **--help**: Each command supports `--help` for details about arguments. |
| 46 | + |
| 47 | +Each command accepts `--format=json` to output in JSON format. The default format is Markdown (`md`). |
| 48 | + |
| 49 | +## Input Automation (<uid> from snapshot) |
| 50 | + |
| 51 | +```bash |
| 52 | +chrome-devtools take_snapshot --help # Help message for commands, works for any command. |
| 53 | +chrome-devtools take_snapshot # Take a text snapshot of the page to get UIDs for elements |
| 54 | +chrome-devtools click "id" # Clicks on the provided element |
| 55 | +chrome-devtools click "id" --dblClick true --includeSnapshot true # Double clicks and returns a snapshot |
| 56 | +chrome-devtools drag "src" "dst" # Drag an element onto another element |
| 57 | +chrome-devtools drag "src" "dst" --includeSnapshot true # Drag an element and return a snapshot |
| 58 | +chrome-devtools fill "id" "text" # Type text into an input or select an option |
| 59 | +chrome-devtools fill "id" "text" --includeSnapshot true # Fill an element and return a snapshot |
| 60 | +chrome-devtools fill_form "json" # Fill out multiple form elements at once |
| 61 | +chrome-devtools fill_form "json" --includeSnapshot true # Fill a form and return a snapshot |
| 62 | +chrome-devtools handle_dialog accept # Handle a browser dialog |
| 63 | +chrome-devtools handle_dialog dismiss --promptText "hi" # Dismiss a dialog with prompt text |
| 64 | +chrome-devtools hover "id" # Hover over the provided element |
| 65 | +chrome-devtools hover "id" --includeSnapshot true # Hover over an element and return a snapshot |
| 66 | +chrome-devtools press_key "Enter" # Press a key or key combination |
| 67 | +chrome-devtools press_key "Control+A" --includeSnapshot true # Press a key and return a snapshot |
| 68 | +chrome-devtools type_text "hello" # Type text using keyboard into a focused input |
| 69 | +chrome-devtools type_text "hello" --submitKey "Enter" # Type text and press a submit key |
| 70 | +chrome-devtools upload_file "id" "file.txt" # Upload a file through a provided element |
| 71 | +chrome-devtools upload_file "id" "file.txt" --includeSnapshot true # Upload a file and return a snapshot |
| 72 | +``` |
| 73 | + |
| 74 | +## Navigation |
| 75 | + |
| 76 | +```bash |
| 77 | +chrome-devtools close_page 1 # Closes the page by its index |
| 78 | +chrome-devtools list_pages # Get a list of pages open in the browser |
| 79 | +chrome-devtools navigate_page --url "https://example.com" # Navigates the currently selected page to a URL |
| 80 | +chrome-devtools navigate_page --type "reload" --ignoreCache true # Reload page ignoring cache |
| 81 | +chrome-devtools navigate_page --url "https://example.com" --timeout 5000 # Navigate with a timeout |
| 82 | +chrome-devtools navigate_page --handleBeforeUnload "accept" # Handle before unload dialog |
| 83 | +chrome-devtools navigate_page --type "back" --initScript "foo()" # Navigate back and run an init script |
| 84 | +chrome-devtools new_page "https://example.com" # Creates a new page |
| 85 | +chrome-devtools new_page "https://example.com" --background true --timeout 5000 # Create new page in background |
| 86 | +chrome-devtools new_page "https://example.com" --isolatedContext "ctx" # Create new page with isolated context |
| 87 | +chrome-devtools select_page 1 # Select a page as a context for future tool calls |
| 88 | +chrome-devtools select_page 1 --bringToFront true # Select a page and bring it to front |
| 89 | +chrome-devtools wait_for "Success!" # Wait for the specified text to appear on the page |
| 90 | +chrome-devtools wait_for "Success!" --timeout 10000 # Wait for text with a timeout |
| 91 | +``` |
| 92 | + |
| 93 | +## Emulation |
| 94 | + |
| 95 | +```bash |
| 96 | +chrome-devtools emulate --networkConditions "Offline" # Emulate network conditions |
| 97 | +chrome-devtools emulate --cpuThrottlingRate 4 --geolocation "0,0" # Emulate CPU throttling and geolocation |
| 98 | +chrome-devtools emulate --colorScheme "dark" --viewport "1920x1080" # Emulate color scheme and viewport |
| 99 | +chrome-devtools emulate --userAgent "Mozilla/5.0..." # Emulate user agent |
| 100 | +chrome-devtools resize_page 1920 1080 # Resizes the selected page's window |
| 101 | +``` |
| 102 | + |
| 103 | +## Performance |
| 104 | + |
| 105 | +```bash |
| 106 | +chrome-devtools performance_analyze_insight "1" "LCPBreakdown" # Get more details on a specific Performance Insight |
| 107 | +chrome-devtools performance_start_trace true false # Starts a performance trace recording |
| 108 | +chrome-devtools performance_start_trace true true --filePath t.gz # Start trace and save to a file |
| 109 | +chrome-devtools performance_stop_trace # Stops the active performance trace |
| 110 | +chrome-devtools performance_stop_trace --filePath "t.json" # Stop trace and save to a file |
| 111 | +chrome-devtools take_memory_snapshot "./snap.heapsnapshot" # Capture a memory heapsnapshot |
| 112 | +``` |
| 113 | + |
| 114 | +## Network |
| 115 | + |
| 116 | +```bash |
| 117 | +chrome-devtools get_network_request # Get the currently selected network request |
| 118 | +chrome-devtools get_network_request --reqid 1 --requestFilePath req.json # Get request by id and save to file |
| 119 | +chrome-devtools get_network_request --responseFilePath res.json # Save response body to file |
| 120 | +chrome-devtools list_network_requests # List all network requests |
| 121 | +chrome-devtools list_network_requests --pageSize 50 --pageIdx 0 # List network requests with pagination |
| 122 | +chrome-devtools list_network_requests --resourceTypes '["Fetch"]' # Filter requests by resource type |
| 123 | +chrome-devtools list_network_requests --includePreservedRequests true # Include preserved requests |
| 124 | +``` |
| 125 | + |
| 126 | +## Debugging & Inspection |
| 127 | + |
| 128 | +```bash |
| 129 | +chrome-devtools evaluate_script "() => document.title" # Evaluate a JavaScript function on the page |
| 130 | +evaluate_script "(a) => a.innerText" --args 1_4 # Evaluate JS with UID arguments |
| 131 | +chrome-devtools get_console_message 1 # Gets a console message by its ID |
| 132 | +chrome-devtools lighthouse_audit --mode "navigation" # Run Lighthouse audit for navigation |
| 133 | +chrome-devtools lighthouse_audit --mode "snapshot" --device "mobile" # Run Lighthouse audit for a snapshot on mobile |
| 134 | +chrome-devtools lighthouse_audit --outputDirPath ./out # Run Lighthouse audit and save reports |
| 135 | +chrome-devtools list_console_messages # List all console messages |
| 136 | +chrome-devtools list_console_messages --pageSize 20 --pageIdx 1 # List console messages with pagination |
| 137 | +chrome-devtools list_console_messages --types '["error"]' # Filter console messages by type |
| 138 | +chrome-devtools list_console_messages --includePreservedMessages true # Include preserved messages |
| 139 | +chrome-devtools take_screenshot # Take a screenshot of the page viewport |
| 140 | +chrome-devtools take_screenshot --fullPage true --format "jpeg" --quality 80 # Take a full page screenshot as JPEG with quality |
| 141 | +chrome-devtools take_screenshot --uid "id" --filePath "s.png" # Take a screenshot of an element |
| 142 | +chrome-devtools take_snapshot # Take a text snapshot of the page from the a11y tree |
| 143 | +chrome-devtools take_snapshot --verbose true --filePath "s.txt" # Take a verbose snapshot and save to file |
| 144 | +``` |
| 145 | + |
| 146 | +## Service Management |
| 147 | + |
| 148 | +```bash |
| 149 | +chrome-devtools start # Start or restart chrome-devtools-mcp |
| 150 | +chrome-devtools status # Checks if chrome-devtools-mcp is running |
| 151 | +chrome-devtools stop # Stop chrome-devtools-mcp if any |
| 152 | +``` |
0 commit comments