chrome-devtools-cli skill

INSTALL.md

Installation

Install the package globally to make the chrome-devtools command available. You only need to do this the first time you use it.

npm i chrome-devtools-mcp@latest -g
chrome-devtools status # check if install worked.

Browser Setup (Chrome)

1. Install Chrome

If Chrome is not already installed, install it with winget:

winget install --id Google.Chrome --accept-source-agreements --accept-package-agreements

2. Create a profile junction

Chrome requires a non-default --user-data-dir when enabling --remote-debugging-port. To reuse your existing Chrome profile, create a junction from a non-default path to the real profile:

New-Item -ItemType Directory -Path "$HOME\.cache\Google\Chrome" -Force
New-Item -ItemType Directory -Path "$HOME\AppData\Local\Google\Chrome\User Data" -Force
cmd /c mklink /J "$HOME\.cache\Google\Chrome\User Data" "$HOME\AppData\Local\Google\Chrome\User Data"

Tip: A junction does not require Administrator privileges or Developer Mode, unlike a symbolic link.

3. Create a Chrome shortcut with remote debugging

Create a new shortcut with the remote debugging flags baked in (overwrites any existing one):

$shell = New-Object -ComObject WScript.Shell
$lnk = $shell.CreateShortcut("$env:USERPROFILE\Desktop\Google Chrome.lnk")
$lnk.TargetPath = "C:\Program Files\Google\Chrome\Application\chrome.exe"
$lnk.Arguments = '--remote-debugging-port=9222 --user-data-dir="C:\Users\lijunle\.cache\Google\Chrome\User Data"'
$lnk.WorkingDirectory = "C:\Program Files\Google\Chrome\Application"
$lnk.Save()

Move the shortcut to your preferred location (e.g., Start Menu, taskbar). To verify the shortcut is correct, right-click it → Properties and confirm the Target field includes the --remote-debugging-port and --user-data-dir flags.

4. Launch Chrome

Close Chrome completely, then relaunch it from the updated shortcut, or run manually:

& "C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222 --user-data-dir="C:\Users\lijunle\.cache\Google\Chrome\User Data"

Note: Chrome must be fully closed before launching with these flags. The junction and shortcut setup are one-time steps.

5. Verify remote debugging

After Chrome is running, verify that the remote debugging port is active:

curl http://localhost:9222/json

A successful response returns a JSON array listing the open tabs. If the connection is refused, ensure Chrome was launched with the --remote-debugging-port=9222 flag and that no other process is using port 9222.

Troubleshooting

• Command not found: If chrome-devtools is not recognized, ensure your global npm bin directory is in your system's PATH. Restart your terminal or source your shell configuration file (e.g., .bashrc, .zshrc).
• Permission errors: If you encounter EACCES or permission errors during installation, avoid using sudo. Instead, use a node version manager like nvm, or configure npm to use a different global directory.
• Old version running: Run chrome-devtools stop && npm uninstall -g chrome-devtools-mcp before reinstalling, or ensure the latest version is being picked up by your path.

SKILL.md

name	chrome-devtools-cli
description	Use this skill to write shell scripts or run shell commands to automate tasks in the browser or otherwise use Chrome DevTools via CLI.

The chrome-devtools-mcp CLI lets you interact with the browser from your terminal.

Setup

Note: If this is your very first time using the CLI, see INSTALL.md for setup. Installation is a one-time prerequisite and is not part of the regular AI workflow.

AI Workflow

1. Start the daemon: Before running any commands, ensure the daemon is started with the correct browser connection:

   chrome-devtools start --browserUrl http://127.0.0.1:9222

   This connects to the running Chrome instance with remote debugging on port 9222. The daemon must be started explicitly because the implicit auto-start uses default args only (no --browserUrl or --executablePath).
2. Execute: Run tools directly (e.g., chrome-devtools list_pages).
3. Inspect: Use take_snapshot to get an element <uid>.
4. Act: Use click, fill, etc. State persists across commands.

Snapshot example:

uid=1_0 RootWebArea "Example Domain" url="https://example.com/"
  uid=1_1 heading "Example Domain" level="1"

Command Usage

chrome-devtools <tool> [arguments] [flags]

Use --help on any command. Output defaults to Markdown, use --output-format=json for JSON.

Input Automation ( from snapshot)

chrome-devtools take_snapshot --help # Help message for commands, works for any command.
chrome-devtools take_snapshot # Take a text snapshot of the page to get UIDs for elements
chrome-devtools click "id" # Clicks on the provided element
chrome-devtools click "id" --dblClick true --includeSnapshot true # Double clicks and returns a snapshot
chrome-devtools drag "src" "dst" # Drag an element onto another element
chrome-devtools drag "src" "dst" --includeSnapshot true # Drag an element and return a snapshot
chrome-devtools fill "id" "text" # Type text into an input or select an option
chrome-devtools fill "id" "text" --includeSnapshot true # Fill an element and return a snapshot
chrome-devtools handle_dialog accept # Handle a browser dialog
chrome-devtools handle_dialog dismiss --promptText "hi" # Dismiss a dialog with prompt text
chrome-devtools hover "id" # Hover over the provided element
chrome-devtools hover "id" --includeSnapshot true # Hover over an element and return a snapshot
chrome-devtools press_key "Enter" # Press a key or key combination
chrome-devtools press_key "Control+A" --includeSnapshot true # Press a key and return a snapshot
chrome-devtools type_text "hello" # Type text using keyboard into a focused input
chrome-devtools type_text "hello" --submitKey "Enter" # Type text and press a submit key
chrome-devtools upload_file "id" "file.txt" # Upload a file through a provided element
chrome-devtools upload_file "id" "file.txt" --includeSnapshot true # Upload a file and return a snapshot

Navigation

chrome-devtools close_page 1 # Closes the page by its index
chrome-devtools list_pages # Get a list of pages open in the browser
chrome-devtools navigate_page --url "https://example.com" # Navigates the currently selected page to a URL
chrome-devtools navigate_page --type "reload" --ignoreCache true # Reload page ignoring cache
chrome-devtools navigate_page --url "https://example.com" --timeout 5000 # Navigate with a timeout
chrome-devtools navigate_page --handleBeforeUnload "accept" # Handle before unload dialog
chrome-devtools navigate_page --type "back" --initScript "foo()" # Navigate back and run an init script
chrome-devtools new_page "https://example.com" # Creates a new page
chrome-devtools new_page "https://example.com" --background true --timeout 5000 # Create new page in background
chrome-devtools new_page "https://example.com" --isolatedContext "ctx" # Create new page with isolated context
chrome-devtools select_page 1 # Select a page as a context for future tool calls
chrome-devtools select_page 1 --bringToFront true # Select a page and bring it to front

Emulation

chrome-devtools emulate --networkConditions "Offline" # Emulate network conditions
chrome-devtools emulate --cpuThrottlingRate 4 --geolocation "0x0" # Emulate CPU throttling and geolocation
chrome-devtools emulate --colorScheme "dark" --viewport "1920x1080" # Emulate color scheme and viewport
chrome-devtools emulate --userAgent "Mozilla/5.0..." # Emulate user agent
chrome-devtools resize_page 1920 1080 # Resizes the selected page's window

Performance

chrome-devtools performance_analyze_insight "1" "LCPBreakdown" # Get more details on a specific Performance Insight
chrome-devtools performance_start_trace true false # Starts a performance trace recording
chrome-devtools performance_start_trace true true --filePath t.gz # Start trace and save to a file
chrome-devtools performance_stop_trace # Stops the active performance trace
chrome-devtools performance_stop_trace --filePath "t.json" # Stop trace and save to a file
chrome-devtools take_memory_snapshot "./snap.heapsnapshot" # Capture a memory heapsnapshot

Network

chrome-devtools get_network_request # Get the currently selected network request
chrome-devtools get_network_request --reqid 1 --requestFilePath req.md # Get request by id and save to file
chrome-devtools get_network_request --responseFilePath res.md # Save response body to file
chrome-devtools list_network_requests # List all network requests
chrome-devtools list_network_requests --pageSize 50 --pageIdx 0 # List network requests with pagination
chrome-devtools list_network_requests --resourceTypes Fetch # Filter requests by resource type
chrome-devtools list_network_requests --includePreservedRequests true # Include preserved requests

Debugging & Inspection

chrome-devtools evaluate_script "() => document.title" # Evaluate a JavaScript function on the page
chrome-devtools evaluate_script "(a) => a.innerText" --args 1_4 # Evaluate JS with UID arguments
chrome-devtools get_console_message 1 # Gets a console message by its ID
chrome-devtools lighthouse_audit --mode "navigation" # Run Lighthouse audit for navigation
chrome-devtools lighthouse_audit --mode "snapshot" --device "mobile" # Run Lighthouse audit for a snapshot on mobile
chrome-devtools lighthouse_audit --outputDirPath ./out # Run Lighthouse audit and save reports
chrome-devtools list_console_messages # List all console messages
chrome-devtools list_console_messages --pageSize 20 --pageIdx 1 # List console messages with pagination
chrome-devtools list_console_messages --types error --types info # Filter console messages by type
chrome-devtools list_console_messages --includePreservedMessages true # Include preserved messages
chrome-devtools take_screenshot # Take a screenshot of the page viewport
chrome-devtools take_screenshot --fullPage true --format "jpeg" --quality 80 # Take a full page screenshot as JPEG with quality
chrome-devtools take_screenshot --uid "id" --filePath "s.png" # Take a screenshot of an element
chrome-devtools take_snapshot # Take a text snapshot of the page from the a11y tree
chrome-devtools take_snapshot --verbose true --filePath "s.txt" # Take a verbose snapshot and save to file

Service Management

chrome-devtools start   # Start or restart chrome-devtools-mcp
chrome-devtools status  # Checks if chrome-devtools-mcp is running
chrome-devtools stop    # Stop chrome-devtools-mcp if any