Skip to content

Chrome DevTools for coding agents

refactor: extract browser options (#2654)

Nikolay Vitkova918b7b4086b
diff --git a/docs/configuration.md b/docs/configuration.md
index 6b911086..3132f642 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -80,6 +80,21 @@ The Chrome DevTools MCP server supports the following configuration option:
- **Choices:** `canary`, `dev`, `beta`, `stable`
- **Default:** `false`
+- **`--proxyServer`/ `--proxy-server`**
+ Proxy server configuration for Chrome passed as --proxy-server when launching the browser. See https://www.chromium.org/developers/design-documents/network-settings/ for details.
+ - **Type:** string
+ - **Default:** `false`
+
+- **`--chromeArg`/ `--chrome-arg`**
+ Additional arguments for Chrome. Only applies when Chrome is launched by chrome-devtools-mcp.
+ - **Type:** array
+ - **Default:** `false`
+
+- **`--ignoreDefaultChromeArg`/ `--ignore-default-chrome-arg`**
+ Explicitly disable default arguments for Chrome. Only applies when Chrome is launched by chrome-devtools-mcp.
+ - **Type:** array
+ - **Default:** `false`
+
- **`--logFile`/ `--log-file`**
Path to a file to write debug logs to. Set the env variable `DEBUG` to `*` to enable verbose logs. Useful for submitting bug reports.
- **Type:** string
@@ -90,11 +105,6 @@ The Chrome DevTools MCP server supports the following configuration option:
- **Type:** string
- **Default:** `false`
-- **`--proxyServer`/ `--proxy-server`**
- Proxy server configuration for Chrome passed as --proxy-server when launching the browser. See https://www.chromium.org/developers/design-documents/network-settings/ for details.
- - **Type:** string
- - **Default:** `false`
-
- **`--acceptInsecureCerts`/ `--accept-insecure-certs`**
If enabled, ignores errors relative to self-signed and expired certificates. Use with caution.
- **Type:** boolean
@@ -145,11 +155,6 @@ The Chrome DevTools MCP server supports the following configuration option:
- **Type:** number
- **Default:** `false`
-- **`--chromeArg`/ `--chrome-arg`**
- Additional arguments for Chrome. Only applies when Chrome is launched by chrome-devtools-mcp.
- - **Type:** array
- - **Default:** `false`
-
- **`--blockedUrlPattern`/ `--blocked-url-pattern`**
Restricts browser's network access by blocking specified URL patterns (uses https://urlpattern.spec.whatwg.org/). Silently detaches from targets with blocked URLs upon connection, and blocks runtime requests (including navigations and subresources). Accepts an array of patterns.
- **Type:** array
@@ -160,11 +165,6 @@ The Chrome DevTools MCP server supports the following configuration option:
- **Type:** array
- **Default:** `false`
-- **`--ignoreDefaultChromeArg`/ `--ignore-default-chrome-arg`**
- Explicitly disable default arguments for Chrome. Only applies when Chrome is launched by chrome-devtools-mcp.
- - **Type:** array
- - **Default:** `false`
-
- **`--performanceCrux`/ `--performance-crux`**
Set to false to disable sending URLs from performance traces to CrUX API to get field performance data.
- **Type:** boolean
diff --git a/src/config/browser-options.ts b/src/config/browser-options.ts
new file mode 100644
index 00000000..6fbfac53
--- /dev/null
+++ b/src/config/browser-options.ts
@@ -0,0 +1,136 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type {YargsOptions} from '../third_party/index.js';
+
+export const browserOptions = {
+ autoConnect: {
+ type: 'boolean',
+ description:
+ 'If specified, automatically connects to a browser (Chrome 144+) running locally from the user data directory identified by the channel param (default channel is stable). Requires the remote debugging server to be started in the Chrome instance via chrome://inspect/#remote-debugging.',
+ conflicts: ['isolated', 'executablePath'],
+ default: false,
+ coerce: (value: boolean | undefined) => {
+ if (!value) {
+ return;
+ }
+ return value;
+ },
+ },
+ browserUrl: {
+ type: 'string',
+ description:
+ 'Connect to a running, debuggable Chrome instance (e.g. `http://127.0.0.1:9222`). For more details see: https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/docs/advanced-usage.md#connecting-to-a-running-chrome-instance.',
+ alias: 'u',
+ conflicts: ['wsEndpoint'],
+ coerce: (url: string | undefined) => {
+ if (!url) {
+ return;
+ }
+ try {
+ new URL(url);
+ } catch {
+ throw new Error(`Provided browserUrl ${url} is not valid URL.`);
+ }
+ return url;
+ },
+ },
+ wsEndpoint: {
+ type: 'string',
+ description:
+ 'WebSocket endpoint to connect to a running Chrome instance (e.g., ws://127.0.0.1:9222/devtools/browser/<id>). Alternative to --browserUrl.',
+ alias: 'w',
+ conflicts: ['browserUrl'],
+ coerce: (url: string | undefined) => {
+ if (!url) {
+ return;
+ }
+ try {
+ const parsed = new URL(url);
+ if (parsed.protocol !== 'ws:' && parsed.protocol !== 'wss:') {
+ throw new Error(
+ `Provided wsEndpoint ${url} must use ws:// or wss:// protocol.`,
+ );
+ }
+ return url;
+ } catch (error) {
+ if ((error as Error).message.includes('ws://')) {
+ throw error;
+ }
+ throw new Error(`Provided wsEndpoint ${url} is not valid URL.`);
+ }
+ },
+ },
+ wsHeaders: {
+ type: 'string',
+ description:
+ 'Custom headers for WebSocket connection in JSON format (e.g., \'{"Authorization":"Bearer token"}\'). Only works with --wsEndpoint.',
+ implies: 'wsEndpoint',
+ coerce: (val: string | undefined) => {
+ if (!val) {
+ return;
+ }
+ try {
+ const parsed = JSON.parse(val);
+ if (typeof parsed !== 'object' || Array.isArray(parsed)) {
+ throw new Error('Headers must be a JSON object');
+ }
+ return parsed as Record<string, string>;
+ } catch (error) {
+ throw new Error(
+ `Invalid JSON for wsHeaders: ${(error as Error).message}`,
+ );
+ }
+ },
+ },
+ headless: {
+ type: 'boolean',
+ description: 'Whether to run in headless (no UI) mode.',
+ default: false,
+ },
+ executablePath: {
+ type: 'string',
+ description: 'Path to custom Chrome executable.',
+ conflicts: ['browserUrl', 'wsEndpoint'],
+ alias: 'e',
+ },
+ isolated: {
+ type: 'boolean',
+ description:
+ 'If specified, creates a temporary user-data-dir that is automatically cleaned up after the browser is closed. Defaults to false.',
+ },
+ userDataDir: {
+ type: 'string',
+ description:
+ 'Path to the user data directory for Chrome. Default is $HOME/.cache/chrome-devtools-mcp/chrome-profile$CHANNEL_SUFFIX_IF_NON_STABLE',
+ conflicts: ['browserUrl', 'wsEndpoint', 'isolated'],
+ },
+ channel: {
+ type: 'string',
+ description:
+ 'Specify a different Chrome channel that should be used. The default is the stable channel version.',
+ choices: ['canary', 'dev', 'beta', 'stable'] as const,
+ conflicts: ['browserUrl', 'wsEndpoint', 'executablePath'],
+ },
+ proxyServer: {
+ type: 'string',
+ description: `Proxy server configuration for Chrome passed as --proxy-server when launching the browser. See https://www.chromium.org/developers/design-documents/network-settings/ for details.`,
+ },
+ chromeArg: {
+ type: 'array',
+ describe:
+ 'Additional arguments for Chrome. Only applies when Chrome is launched by chrome-devtools-mcp.',
+ },
+ ignoreDefaultChromeArg: {
+ type: 'array',
+ describe:
+ 'Explicitly disable default arguments for Chrome. Only applies when Chrome is launched by chrome-devtools-mcp.',
+ },
+} satisfies Record<string, YargsOptions>;
+
+export function getBrowserOptions(): typeof browserOptions {
+ return browserOptions;
+}
diff --git a/src/config/mcp-options.ts b/src/config/mcp-options.ts
index d7c0d1ff..8fe83fb3 100644
--- a/src/config/mcp-options.ts
+++ b/src/config/mcp-options.ts
@@ -11,117 +11,11 @@ import os from 'node:os';
export const DEFAULT_FILESYSTEM_ROOT = [os.tmpdir()];
import {getCategoryOptions} from './category-options.js';
+import {getBrowserOptions} from './browser-options.js';
export const mcpOptions = {
...getCategoryOptions(),
- autoConnect: {
- type: 'boolean',
- description:
- 'If specified, automatically connects to a browser (Chrome 144+) running locally from the user data directory identified by the channel param (default channel is stable). Requires the remote debugging server to be started in the Chrome instance via chrome://inspect/#remote-debugging.',
- conflicts: ['isolated', 'executablePath'],
- default: false,
- coerce: (value: boolean | undefined) => {
- if (!value) {
- return;
- }
- return value;
- },
- },
- browserUrl: {
- type: 'string',
- description:
- 'Connect to a running, debuggable Chrome instance (e.g. `http://127.0.0.1:9222`). For more details see: https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/docs/advanced-usage.md#connecting-to-a-running-chrome-instance.',
- alias: 'u',
- conflicts: ['wsEndpoint'],
- coerce: (url: string | undefined) => {
- if (!url) {
- return;
- }
- try {
- new URL(url);
- } catch {
- throw new Error(`Provided browserUrl ${url} is not valid URL.`);
- }
- return url;
- },
- },
- wsEndpoint: {
- type: 'string',
- description:
- 'WebSocket endpoint to connect to a running Chrome instance (e.g., ws://127.0.0.1:9222/devtools/browser/<id>). Alternative to --browserUrl.',
- alias: 'w',
- conflicts: ['browserUrl'],
- coerce: (url: string | undefined) => {
- if (!url) {
- return;
- }
- try {
- const parsed = new URL(url);
- if (parsed.protocol !== 'ws:' && parsed.protocol !== 'wss:') {
- throw new Error(
- `Provided wsEndpoint ${url} must use ws:// or wss:// protocol.`,
- );
- }
- return url;
- } catch (error) {
- if ((error as Error).message.includes('ws://')) {
- throw error;
- }
- throw new Error(`Provided wsEndpoint ${url} is not valid URL.`);
- }
- },
- },
- wsHeaders: {
- type: 'string',
- description:
- 'Custom headers for WebSocket connection in JSON format (e.g., \'{"Authorization":"Bearer token"}\'). Only works with --wsEndpoint.',
- implies: 'wsEndpoint',
- coerce: (val: string | undefined) => {
- if (!val) {
- return;
- }
- try {
- const parsed = JSON.parse(val);
- if (typeof parsed !== 'object' || Array.isArray(parsed)) {
- throw new Error('Headers must be a JSON object');
- }
- return parsed as Record<string, string>;
- } catch (error) {
- throw new Error(
- `Invalid JSON for wsHeaders: ${(error as Error).message}`,
- );
- }
- },
- },
- headless: {
- type: 'boolean',
- description: 'Whether to run in headless (no UI) mode.',
- default: false,
- },
- executablePath: {
- type: 'string',
- description: 'Path to custom Chrome executable.',
- conflicts: ['browserUrl', 'wsEndpoint'],
- alias: 'e',
- },
- isolated: {
- type: 'boolean',
- description:
- 'If specified, creates a temporary user-data-dir that is automatically cleaned up after the browser is closed. Defaults to false.',
- },
- userDataDir: {
- type: 'string',
- description:
- 'Path to the user data directory for Chrome. Default is $HOME/.cache/chrome-devtools-mcp/chrome-profile$CHANNEL_SUFFIX_IF_NON_STABLE',
- conflicts: ['browserUrl', 'wsEndpoint', 'isolated'],
- },
- channel: {
- type: 'string',
- description:
- 'Specify a different Chrome channel that should be used. The default is the stable channel version.',
- choices: ['canary', 'dev', 'beta', 'stable'] as const,
- conflicts: ['browserUrl', 'wsEndpoint', 'executablePath'],
- },
+ ...getBrowserOptions(),
logFile: {
type: 'string',
describe:
@@ -145,10 +39,6 @@ export const mcpOptions = {
};
},
},
- proxyServer: {
- type: 'string',
- description: `Proxy server configuration for Chrome passed as --proxy-server when launching the browser. See https://www.chromium.org/developers/design-documents/network-settings/ for details.`,
- },
acceptInsecureCerts: {
type: 'boolean',
description: `If enabled, ignores errors relative to self-signed and expired certificates. Use with caution.`,
@@ -229,11 +119,6 @@ export const mcpOptions = {
return value;
},
},
- chromeArg: {
- type: 'array',
- describe:
- 'Additional arguments for Chrome. Only applies when Chrome is launched by chrome-devtools-mcp.',
- },
blockedUrlPattern: {
type: 'array',
describe:
@@ -246,11 +131,6 @@ export const mcpOptions = {
"Restricts browser's network access by allowing only specified URL patterns (uses https://urlpattern.spec.whatwg.org/). Requires Chrome 149+. Silently detaches from targets with unallowed URLs upon connection, and blocks runtime requests (including navigations and subresources). Accepts an array of patterns.",
conflicts: ['blockedUrlPattern'],
},
- ignoreDefaultChromeArg: {
- type: 'array',
- describe:
- 'Explicitly disable default arguments for Chrome. Only applies when Chrome is launched by chrome-devtools-mcp.',
- },
performanceCrux: {
type: 'boolean',
default: true,