mirrors / chromedevtools--chrome-devtools-mcp

项目文件夹

文件

T

pidofme 73e1e24b26 fix(cli): avoid defaulting to isolated when userDataDir is provided (#1258 )

## Summary

Fix `chrome-devtools start` so it no longer implicitly enables
`isolated` when `--userDataDir` is provided.

Previously, the CLI wrapper always defaulted `isolated` to `true` for
`start`, which caused `userDataDir` and `isolated` to conflict even when
the user only specified `--userDataDir`. This made it impossible to
start the CLI daemon against a persistent browser profile.

   ## Changes

- Update `chrome-devtools start` default handling in
`src/bin/chrome-devtools.ts`
     - only default `isolated=true` when `userDataDir` is not set
- Clarify the `isolated` CLI description to document the conditional
default
   - Update `docs/cli.md` to reflect that:
     - `headless` is enabled by default
- `isolated` is enabled by default unless `--userDataDir` is provided
   - Fix a small error message typo

   ## Why

   This matches the intended semantics of the flags:

   - `--isolated` means use a temporary user data dir
   - `--userDataDir` means use a persistent, explicit user data dir

If the user passes `--userDataDir`, the CLI should not also implicitly
enable `isolated`.

   ## Testing

   - Ran:
     - `npm test -- tests/cli.test.ts`
     - `npm test -- tests/e2e/chrome-devtools.test.ts`

Added an e2e regression test in `tests/e2e/chrome-devtools.test.ts` to
verify that:

   - `chrome-devtools start --userDataDir <temp dir>` succeeds
- the CLI no longer fails with `Arguments userDataDir and isolated are
mutually exclusive`
   - the daemon starts successfully when `userDataDir` is provided

2026-04-01 05:51:40 +00:00

3.1 KiB

原始文件 永久链接 Blame 文件历史

Chrome DevTools CLI

The chrome-devtools-mcp package includes an experimental 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:

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 (uses Unix sockets on Linux/Mac and named pipes on Windows).

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) but not all args are supported. Run chrome-devtools start --help for supported args. Headless is enabled by default. Isolated is enabled by default unless --userDataDir is provided.

# Check if the daemon is running
chrome-devtools status

# Navigate the current page to a URL
chrome-devtools navigate_page "https://google.com"

# Take a screenshot and save it to a file
chrome-devtools take_screenshot --filePath screenshot.png

# Stop the background daemon when finished
chrome-devtools stop

Command Usage

The CLI supports all tools available in the Tool reference.

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

Required Arguments: Passed as positional arguments.
Optional Arguments: Passed as flags (e.g., --filePath, --fullPage).

Examples

New Page and Navigation:

chrome-devtools new_page "https://example.com"
chrome-devtools navigate_page "https://web.dev" --type url

Interaction:

# Click an element by its UID from a snapshot
chrome-devtools click "element-uid-123"

# Fill a form field
chrome-devtools fill "input-uid-456" "search query"

Analysis:

# Run a Lighthouse audit (defaults to navigation mode)
chrome-devtools lighthouse_audit --mode snapshot

Output format

By default, the CLI outputs a human-readable summary of the tool's result. For programmatic use, you can request raw JSON:

chrome-devtools list_pages --output-format=json

Troubleshooting

If the CLI hangs or fails to connect, try stopping the background process:

chrome-devtools stop

For more verbose logs, set the DEBUG environment variable:

DEBUG=* chrome-devtools list_pages

CLI generation

Implemented in scripts/generate-cli.ts. Some commands are excluded from CLI generation such as wait_for and fill_form.

chrome-devtools-mcp args are also filtered in src/bin/chrome-devtools.ts because not all args make sense in a CLI interface.

3.1 KiB 原始文件 永久链接 Blame 文件历史