# Chrome DevTools MCP CLI Arguments: Complete Configuration Reference

> Explore over 40 MCP CLI arguments to configure Chrome DevTools connection methods launch behavior tool categories experimental features and telemetry settings.

- Repository: [ChromeDevTools/chrome-devtools-mcp](https://github.com/chromedevtools/chrome-devtools-mcp)
- Tags: api-reference
- Published: 2026-02-16

---

**The chrome-devtools-mcp command line interface exposes over 40 configuration options defined in [`src/cli.ts`](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/cli.ts), allowing developers to control Chrome connection methods, launch behavior, tool categories, experimental features, and telemetry settings through Yargs-powered MCP CLI arguments.**

The ChromeDevTools/chrome-devtools-mcp repository provides a Model Context Protocol (MCP) server that enables AI assistants to interact with Chrome DevTools programmatically. Understanding the available MCP CLI arguments is essential for configuring how the server connects to Chrome instances, which debugging capabilities are exposed, and how diagnostic data is handled.

## Connection and Launch Options

These arguments control whether the MCP server attaches to an existing Chrome instance or launches a new one. According to the source code in [`src/cli.ts`](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/cli.ts), these options are mutually exclusive—you cannot combine connection flags with launch flags.

### Attaching to Existing Chrome Instances

- `--browserUrl` (alias `-u`): Connect via HTTP to a debuggable Chrome instance (e.g., `http://127.0.0.1:9222`). Conflicts with `--wsEndpoint`.
- `--wsEndpoint` (alias `-w`): Connect via WebSocket endpoint (e.g., `ws://127.0.0.1:9222/devtools/browser/<id>`). Conflicts with `--browserUrl`.
- `--wsHeaders`: JSON string of custom HTTP headers for WebSocket connections (e.g., `{"Authorization":"Bearer token"}`). Requires `--wsEndpoint`.

### Launching New Chrome Instances

- `--auto-connect`: Automatically connects to Chrome 144+ running with the user-data directory for the selected channel. Conflicts with `--isolated` and `--executablePath`.
- `--executablePath` (alias `-e`): Path to a custom Chrome executable. Conflicts with connection flags.
- `--channel`: Chrome channel to launch (`stable`, `canary`, `beta`, `dev`). Defaults to `stable` when no connection flags are provided, as implemented in the `parseArguments` function (lines 36-117) of [`src/cli.ts`](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/cli.ts).

## Chrome Configuration Arguments

Control the behavior and environment of launched Chrome processes.

- `--headless`: Run Chrome without a UI (default: `false`).
- `--isolated`: Launch Chrome with a temporary profile deleted after the session (default: `false`). Conflicts with `--userDataDir`.
- `--userDataDir`: Explicit directory for Chrome's user data. Conflicts with connection flags and `--isolated`.
- `--viewport`: Initial viewport size as `<width>x<height>` (e.g., `1280x720`). Maximum 3840×2160 in headless mode.
- `--proxyServer`: Proxy configuration passed to Chrome (`--proxy-server` flag).
- `--acceptInsecureCerts`: Ignore self-signed or expired certificate errors (default: `false`).
- `--chrome-arg`: Array of additional command-line arguments passed to Chrome.
- `--ignore-default-chrome-arg`: Array of default Chrome arguments to disable (provided by Puppeteer).

## Tool Category Flags

These boolean flags enable or disable specific categories of DevTools tools. All default to `true` except where noted.

- `--categoryEmulation`: Include Emulation category tools.
- `--categoryPerformance`: Include Performance category tools.
- `--categoryNetwork`: Include Network category tools.
- `--categoryExtensions`: Include Extensions category tools (default: `false`, hidden flag).

The mapping of these flags to specific tool sets is handled in [`src/tools/categories.ts`](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/tools/categories.ts).

## Experimental Features

Hidden flags for upcoming functionality, all defaulting to `false`:

- `--experimentalDevtools`: Enable automation over DevTools targets.
- `--experimentalVision`: Enable vision-related tools.
- `--experimentalStructuredContent`: Output structured formatted content.
- `--experimentalIncludeAllPages`: Include webviews and background pages.
- `--experimentalInteropTools`: Enable interoperability tools.

## Telemetry and Logging Options

Control diagnostic output and usage statistics collection, processed by [`src/telemetry/WatchdogClient.ts`](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/telemetry/WatchdogClient.ts).

- `--logFile`: File path to write debug logs. Enable verbose output by setting the `DEBUG=*` environment variable.
- `--usageStatistics`: Opt-out of usage statistics collection when set to `false` (default: `true`).
- `--clearcutEndpoint`: Custom endpoint for Clearcut telemetry (hidden).
- `--clearcutForceFlushIntervalMs`: Force telemetry flush interval in milliseconds (hidden, test use).
- `--clearcutIncludePidHeader`: Include watchdog PID in Clearcut headers (hidden, test use).

## Usage Examples

Connect to an already-running Chrome instance via HTTP:

```bash
npx chrome-devtools-mcp@latest --browserUrl http://127.0.0.1:9222

```

Connect via WebSocket with custom authorization headers:

```bash
npx chrome-devtools-mcp@latest \
  --wsEndpoint ws://127.0.0.1:9222/devtools/browser/abc123 \
  --wsHeaders '{"Authorization":"Bearer token"}'

```

Launch a fresh Chrome Canary instance in headless mode with specific viewport:

```bash
npx chrome-devtools-mcp@latest \
  --channel canary \
  --headless \
  --viewport 1280x720

```

Disable Network tools and enable experimental vision features:

```bash
npx chrome-devtools-mcp@latest \
  --no-category-network \
  --experimentalVision

```

Enable verbose logging to a file:

```bash
DEBUG=* npx chrome-devtools-mcp@latest --logFile /tmp/mcp.log

```

## Summary

- The chrome-devtools-mcp CLI exposes over 40 configuration options via the `cliOptions` constant in [`src/cli.ts`](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/cli.ts) (lines 10-34).
- **Connection options** (`--browserUrl`, `--wsEndpoint`, `--auto-connect`) control how the server attaches to Chrome, while **launch options** (`--headless`, `--channel`, `--viewport`) configure new instances.
- **Tool category flags** (`--categoryNetwork`, `--categoryPerformance`, etc.) enable or disable specific DevTools capabilities via [`src/tools/categories.ts`](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/tools/categories.ts).
- **Experimental flags** provide early access to vision tools, structured content output, and DevTools target automation.
- **Telemetry controls** (`--usageStatistics`, `--logFile`) manage diagnostic output and usage collection through [`src/telemetry/WatchdogClient.ts`](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/telemetry/WatchdogClient.ts).

## Frequently Asked Questions

### How do I connect to an already running Chrome instance using MCP CLI arguments?

Use the `--browserUrl` flag to connect via HTTP (e.g., `--browserUrl http://127.0.0.1:9222`) or the `--wsEndpoint` flag for WebSocket connections. These options conflict with launch flags like `--executablePath` or `--channel`, so you must choose between connecting to an existing instance or launching a new one.

### What is the difference between --isolated and --userDataDir in chrome-devtools-mcp?

The `--isolated` flag launches Chrome with a temporary profile that is automatically deleted when the session ends, ensuring a clean state. In contrast, `--userDataDir` specifies a persistent directory for Chrome's user data, allowing cookies, local storage, and extensions to persist across sessions. These flags conflict with each other and with connection flags like `--browserUrl`.

### How do I disable specific DevTools tool categories using CLI arguments?

Use the category flags prefixed with `--category` followed by the category name. For example, `--no-category-network` disables Network tools, `--no-category-performance` disables Performance tools, and `--no-category-emulation` disables Emulation tools. All categories default to enabled (`true`) except Extensions, which defaults to disabled. The mapping is handled in [`src/tools/categories.ts`](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/tools/categories.ts).

### Where are the MCP CLI arguments defined in the source code?

All CLI arguments are defined in the `cliOptions` constant located in [`src/cli.ts`](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/cli.ts) (lines 10-34). The Yargs parser configuration and default value logic (such as defaulting `channel` to `stable`) are implemented in the `parseArguments` function (lines 36-117) within the same file. The parsed configuration is then consumed by the entry point in [`src/main.ts`](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/src/main.ts).