From faa144ac9ea47e94369c60149143d3867332d4b4 Mon Sep 17 00:00:00 2001 From: Alex Rudenko Date: Wed, 4 Mar 2026 17:41:35 +0100 Subject: [PATCH 1/4] chore: add a skill for chrome-devtools --- skills/chrome-devtools-cli/SKILL.md | 152 ++++++++++++++++++++++++++++ 1 file changed, 152 insertions(+) create mode 100644 skills/chrome-devtools-cli/SKILL.md diff --git a/skills/chrome-devtools-cli/SKILL.md b/skills/chrome-devtools-cli/SKILL.md new file mode 100644 index 000000000..36840ca79 --- /dev/null +++ b/skills/chrome-devtools-cli/SKILL.md @@ -0,0 +1,152 @@ +--- +name: chrome-devtools-cli +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. +--- + +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. + +## Getting started + +Install the package globally to make the `chrome-devtools` command available: + +```sh +npm i chrome-devtools-mcp@latest -g +chrome-devtools status # check if install worked. +``` + +## How it works + +The CLI acts as a client to a background `chrome-devtools-mcp` daemon. + +- **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. +- **Persistence**: The same background instance is reused for subsequent commands, preserving the browser state (open pages, cookies, etc.). +- **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`). + +Snapshots looks like this: + +``` +uid=1_0 RootWebArea "Example Domain" url="https://example.com/" + uid=1_1 heading "Example Domain" level="1" + uid=1_2 StaticText "This domain is for use in documentation examples without needing permission. Avoid use in operations." + uid=1_3 link "Learn more" url="https://iana.org/domains/example" + uid=1_4 StaticText "Learn more +``` + +## Command Usage + +The CLI supports all tools available in the Chrome DevTools MCP by default. + +```sh +chrome-devtools [arguments] [flags] +``` + +- **Required Arguments**: Passed as positional arguments. +- **Optional Arguments**: Passed as flags (e.g., `--filePath`, `--fullPage`). +- **--help**: Each command supports `--help` for details about arguments. + +Each command accepts `--format=json` to output in JSON format. The default format is Markdown (`md`). + +## Input Automation ( from snapshot) + +```bash +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 fill_form "json" # Fill out multiple form elements at once +chrome-devtools fill_form "json" --includeSnapshot true # Fill a form 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 + +```bash +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 +chrome-devtools wait_for "Success!" # Wait for the specified text to appear on the page +chrome-devtools wait_for "Success!" --timeout 10000 # Wait for text with a timeout +``` + +## Emulation + +```bash +chrome-devtools emulate --networkConditions "Offline" # Emulate network conditions +chrome-devtools emulate --cpuThrottlingRate 4 --geolocation "0,0" # 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 + +```bash +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 + +```bash +chrome-devtools get_network_request # Get the currently selected network request +chrome-devtools get_network_request --reqid 1 --requestFilePath req.json # Get request by id and save to file +chrome-devtools get_network_request --responseFilePath res.json # 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 + +```bash +chrome-devtools evaluate_script "() => document.title" # Evaluate a JavaScript function on the page +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"]' # 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 + +```bash +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 +``` From 8263f8480adb887e6a844c714246af8275e4daec Mon Sep 17 00:00:00 2001 From: Alex Rudenko Date: Wed, 4 Mar 2026 17:52:51 +0100 Subject: [PATCH 2/4] feat: enable Chrome DevTools CLI --- package-lock.json | 1 + package.json | 5 +- src/bin/chrome-devtools.ts | 5 +- src/daemon/daemon.ts | 9 +- src/third_party/index.ts | 2 + tests/third_party_notices.test.js.snapshot | 132 +++++++++++++++++++++ 6 files changed, 146 insertions(+), 8 deletions(-) diff --git a/package-lock.json b/package-lock.json index 59b202886..0d4d80f14 100644 --- a/package-lock.json +++ b/package-lock.json @@ -9,6 +9,7 @@ "version": "0.18.1", "license": "Apache-2.0", "bin": { + "chrome-devtools": "build/src/bin/chrome-devtools.js", "chrome-devtools-mcp": "build/src/index.js" }, "devDependencies": { diff --git a/package.json b/package.json index 46c73bbf6..eeeed24d2 100644 --- a/package.json +++ b/package.json @@ -3,7 +3,10 @@ "version": "0.18.1", "description": "MCP server for Chrome DevTools", "type": "module", - "bin": "./build/src/index.js", + "bin": { + "chrome-devtools-mcp": "./build/src/index.js", + "chrome-devtools": "./build/src/bin/chrome-devtools.js" + }, "main": "./build/src/server.js", "scripts": { "cli:generate": "node --experimental-strip-types scripts/generate-cli.ts", diff --git a/src/bin/chrome-devtools.ts b/src/bin/chrome-devtools.ts index 663b619ab..cd80431a3 100644 --- a/src/bin/chrome-devtools.ts +++ b/src/bin/chrome-devtools.ts @@ -8,8 +8,7 @@ import process from 'node:process'; -import yargs, {type Options, type PositionalOptions} from 'yargs'; -import {hideBin} from 'yargs/helpers'; +import type {Options, PositionalOptions} from 'yargs'; import {parseArguments} from '../cli.js'; import { @@ -20,7 +19,7 @@ import { } from '../daemon/client.js'; import {isDaemonRunning} from '../daemon/utils.js'; import {logDisclaimers} from '../server.js'; -import type {CallToolResult} from '../third_party/index.js'; +import {hideBin, yargs, type CallToolResult} from '../third_party/index.js'; import {VERSION} from '../version.js'; import {commands} from './cliDefinitions.js'; diff --git a/src/daemon/daemon.ts b/src/daemon/daemon.ts index b0cd3aea4..ba2fb4b85 100644 --- a/src/daemon/daemon.ts +++ b/src/daemon/daemon.ts @@ -11,11 +11,12 @@ import {createServer, type Server} from 'node:net'; import path from 'node:path'; import process from 'node:process'; -import {Client} from '@modelcontextprotocol/sdk/client/index.js'; -import {StdioClientTransport} from '@modelcontextprotocol/sdk/client/stdio.js'; - import {logger} from '../logger.js'; -import {PipeTransport} from '../third_party/index.js'; +import { + Client, + PipeTransport, + StdioClientTransport, +} from '../third_party/index.js'; import {VERSION} from '../version.js'; import type {DaemonMessage} from './types.js'; diff --git a/src/third_party/index.ts b/src/third_party/index.ts index a3d96ef18..f719f4df8 100644 --- a/src/third_party/index.ts +++ b/src/third_party/index.ts @@ -20,6 +20,8 @@ export {default as debug} from 'debug'; export type {Debugger} from 'debug'; export {McpServer} from '@modelcontextprotocol/sdk/server/mcp.js'; export {StdioServerTransport} from '@modelcontextprotocol/sdk/server/stdio.js'; +export {StdioClientTransport} from '@modelcontextprotocol/sdk/client/stdio.js'; +export {Client} from '@modelcontextprotocol/sdk/client/index.js'; export { type CallToolResult, SetLevelRequestSchema, diff --git a/tests/third_party_notices.test.js.snapshot b/tests/third_party_notices.test.js.snapshot index 215b702d8..09c720a3d 100644 --- a/tests/third_party_notices.test.js.snapshot +++ b/tests/third_party_notices.test.js.snapshot @@ -633,6 +633,138 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. +-------------------- DEPENDENCY DIVIDER -------------------- + +Name: cross-spawn +URL: https://github.com/moxystudio/node-cross-spawn +Version: +License: MIT + +The MIT License (MIT) + +Copyright (c) 2018 Made With MOXY Lda + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in +all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN +THE SOFTWARE. + + +-------------------- DEPENDENCY DIVIDER -------------------- + +Name: isexe +URL: https://github.com/isaacs/isexe#readme +Version: +License: ISC + +The ISC License + +Copyright (c) Isaac Z. Schlueter and Contributors + +Permission to use, copy, modify, and/or distribute this software for any +purpose with or without fee is hereby granted, provided that the above +copyright notice and this permission notice appear in all copies. + +THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR +IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. + + +-------------------- DEPENDENCY DIVIDER -------------------- + +Name: which +URL: git://github.com/isaacs/node-which.git +Version: +License: ISC + +The ISC License + +Copyright (c) Isaac Z. Schlueter and Contributors + +Permission to use, copy, modify, and/or distribute this software for any +purpose with or without fee is hereby granted, provided that the above +copyright notice and this permission notice appear in all copies. + +THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR +IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. + + +-------------------- DEPENDENCY DIVIDER -------------------- + +Name: path-key +URL: sindresorhus/path-key +Version: +License: MIT + +MIT License + +Copyright (c) Sindre Sorhus (sindresorhus.com) + +Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. + + +-------------------- DEPENDENCY DIVIDER -------------------- + +Name: shebang-regex +URL: sindresorhus/shebang-regex +Version: +License: MIT + +MIT License + +Copyright (c) Sindre Sorhus (sindresorhus.com) + +Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. + + +-------------------- DEPENDENCY DIVIDER -------------------- + +Name: shebang-command +URL: kevva/shebang-command +Version: +License: MIT + +MIT License + +Copyright (c) Kevin Mårtensson (github.com/kevva) + +Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. + + -------------------- DEPENDENCY DIVIDER -------------------- Name: puppeteer-core From 600829d30df39769a8362a11e791e5199df40f4c Mon Sep 17 00:00:00 2001 From: Alex Rudenko Date: Thu, 5 Mar 2026 10:09:44 +0100 Subject: [PATCH 3/4] chore: fix --- docs/cli.md | 2 +- skills/chrome-devtools-cli/SKILL.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/cli.md b/docs/cli.md index f9c009b16..85e898961 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -75,7 +75,7 @@ chrome-devtools lighthouse_audit --mode snapshot By default, the CLI outputs a human-readable summary of the tool's result. For programmatic use, you can request raw JSON: ```sh -chrome-devtools list_pages --format=json +chrome-devtools list_pages --output-format=json ``` ## Troubleshooting diff --git a/skills/chrome-devtools-cli/SKILL.md b/skills/chrome-devtools-cli/SKILL.md index 36840ca79..49b115209 100644 --- a/skills/chrome-devtools-cli/SKILL.md +++ b/skills/chrome-devtools-cli/SKILL.md @@ -44,7 +44,7 @@ chrome-devtools [arguments] [flags] - **Optional Arguments**: Passed as flags (e.g., `--filePath`, `--fullPage`). - **--help**: Each command supports `--help` for details about arguments. -Each command accepts `--format=json` to output in JSON format. The default format is Markdown (`md`). +Each command accepts `--output-format=json` to output in JSON format. The default format is Markdown (`md`). ## Input Automation ( from snapshot) From 753b64b2c4e64e7717d9af233d6d622e98625759 Mon Sep 17 00:00:00 2001 From: Alex Rudenko Date: Fri, 6 Mar 2026 07:18:53 +0100 Subject: [PATCH 4/4] refactor: improve skill --- skills/chrome-devtools-cli/SKILL.md | 46 ++++++------------- .../references/installation.md | 14 ++++++ 2 files changed, 27 insertions(+), 33 deletions(-) create mode 100644 skills/chrome-devtools-cli/references/installation.md diff --git a/skills/chrome-devtools-cli/SKILL.md b/skills/chrome-devtools-cli/SKILL.md index 49b115209..b6db1807a 100644 --- a/skills/chrome-devtools-cli/SKILL.md +++ b/skills/chrome-devtools-cli/SKILL.md @@ -3,48 +3,32 @@ name: chrome-devtools-cli 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. --- -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. +The `chrome-devtools-mcp` CLI lets you interact with the browser from your terminal. -## Getting started +## Setup -Install the package globally to make the `chrome-devtools` command available: +_Note: If this is your very first time using the CLI, see [references/installation.md](references/installation.md) for setup. Installation is a one-time prerequisite and is **not** part of the regular AI workflow._ -```sh -npm i chrome-devtools-mcp@latest -g -chrome-devtools status # check if install worked. -``` - -## How it works +## AI Workflow -The CLI acts as a client to a background `chrome-devtools-mcp` daemon. +1. **Execute**: Run tools directly (e.g., `chrome-devtools list_pages`). The background server starts implicitly; **do not** run `start`/`status`/`stop` before each use. +2. **Inspect**: Use `take_snapshot` to get an element ``. +3. **Act**: Use `click`, `fill`, etc. State persists across commands. -- **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. -- **Persistence**: The same background instance is reused for subsequent commands, preserving the browser state (open pages, cookies, etc.). -- **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`). - -Snapshots looks like this: +Snapshot example: ``` uid=1_0 RootWebArea "Example Domain" url="https://example.com/" uid=1_1 heading "Example Domain" level="1" - uid=1_2 StaticText "This domain is for use in documentation examples without needing permission. Avoid use in operations." - uid=1_3 link "Learn more" url="https://iana.org/domains/example" - uid=1_4 StaticText "Learn more ``` ## Command Usage -The CLI supports all tools available in the Chrome DevTools MCP by default. - ```sh chrome-devtools [arguments] [flags] ``` -- **Required Arguments**: Passed as positional arguments. -- **Optional Arguments**: Passed as flags (e.g., `--filePath`, `--fullPage`). -- **--help**: Each command supports `--help` for details about arguments. - -Each command accepts `--output-format=json` to output in JSON format. The default format is Markdown (`md`). +Use `--help` on any command. Output defaults to Markdown, use `--output-format=json` for JSON. ## Input Automation ( from snapshot) @@ -57,8 +41,6 @@ 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 fill_form "json" # Fill out multiple form elements at once -chrome-devtools fill_form "json" --includeSnapshot true # Fill a form 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 @@ -86,8 +68,6 @@ chrome-devtools new_page "https://example.com" --background true --timeout 5000 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 -chrome-devtools wait_for "Success!" # Wait for the specified text to appear on the page -chrome-devtools wait_for "Success!" --timeout 10000 # Wait for text with a timeout ``` ## Emulation @@ -115,11 +95,11 @@ chrome-devtools take_memory_snapshot "./snap.heapsnapshot" # Capture a memory he ```bash chrome-devtools get_network_request # Get the currently selected network request -chrome-devtools get_network_request --reqid 1 --requestFilePath req.json # Get request by id and save to file -chrome-devtools get_network_request --responseFilePath res.json # Save response body to file +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 --resourceTypes Fetch # Filter requests by resource type chrome-devtools list_network_requests --includePreservedRequests true # Include preserved requests ``` @@ -134,7 +114,7 @@ chrome-devtools lighthouse_audit --mode "snapshot" --device "mobile" # Run Light 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"]' # Filter console messages by type +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 diff --git a/skills/chrome-devtools-cli/references/installation.md b/skills/chrome-devtools-cli/references/installation.md new file mode 100644 index 000000000..179ecb401 --- /dev/null +++ b/skills/chrome-devtools-cli/references/installation.md @@ -0,0 +1,14 @@ +# Installation + +Install the package globally to make the `chrome-devtools` command available. You only need to do this the first time you use it. + +```sh +npm i chrome-devtools-mcp@latest -g +chrome-devtools status # check if install worked. +``` + +## 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.