Chrome DevTools MCP CLI Arguments: Complete Configuration Reference

The chrome-devtools-mcp command line interface exposes over 40 configuration options defined in 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, 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.

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.

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.

• --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:

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

Connect via WebSocket with custom authorization headers:

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:

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

Disable Network tools and enable experimental vision features:

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

Enable verbose logging to a file:

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 (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.
• 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.

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.

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 (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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}