Skip to content

Chrome DevTools for coding agents

feat: support --auto-connect to a Chrome instance (#651)

Alex Rudenko6ab6d85d5022
diff --git a/README.md b/README.md
index a51a92ca..637176e0 100644
--- a/README.md
+++ b/README.md
@@ -350,6 +350,11 @@ The Chrome DevTools MCP server supports the following configuration option:
<!-- BEGIN AUTO GENERATED OPTIONS -->
+- **`--autoConnect`**
+ If specified, automatically connects to a browser (Chrome 145+) running in the user data directory identified by the channel param.
+ - **Type:** boolean
+ - **Default:** `false`
+
- **`--browserUrl`, `-u`**
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#connecting-to-a-running-chrome-instance.
- **Type:** string
diff --git a/src/browser.ts b/src/browser.ts
index 3120a413..b15b5efa 100644
--- a/src/browser.ts
+++ b/src/browser.ts
@@ -48,7 +48,9 @@ export async function ensureBrowserConnected(options: {
wsEndpoint?: string;
wsHeaders?: Record<string, string>;
devtools: boolean;
+ channel?: Channel;
}) {
+ const {channel} = options;
if (browser?.connected) {
return browser;
}
@@ -66,12 +68,29 @@ export async function ensureBrowserConnected(options: {
}
} else if (options.browserURL) {
connectOptions.browserURL = options.browserURL;
+ } else if (channel) {
+ const puppeteerChannel =
+ channel !== 'stable'
+ ? (`chrome-${channel}` as ChromeReleaseChannel)
+ : 'chrome';
+ connectOptions.channel = puppeteerChannel;
} else {
- throw new Error('Either browserURL or wsEndpoint must be provided');
+ throw new Error(
+ 'Either browserURL, wsEndpoint or channel must be provided',
+ );
}
logger('Connecting Puppeteer to ', JSON.stringify(connectOptions));
- browser = await puppeteer.connect(connectOptions);
+ try {
+ browser = await puppeteer.connect(connectOptions);
+ } catch (err) {
+ throw new Error(
+ 'Could not connect to Chrome. Check if Chrome is running and remote debugging is enabled.',
+ {
+ cause: err,
+ },
+ );
+ }
logger('Connected Puppeteer');
return browser;
}
diff --git a/src/cli.ts b/src/cli.ts
index 4a5d89ce..9da40751 100644
--- a/src/cli.ts
+++ b/src/cli.ts
@@ -8,6 +8,19 @@ import type {YargsOptions} from './third_party/index.js';
import {yargs, hideBin} from './third_party/index.js';
export const cliOptions = {
+ autoConnect: {
+ type: 'boolean',
+ description:
+ 'If specified, automatically connects to a browser (Chrome 145+) running in the user data directory identified by the channel param.',
+ conflicts: ['isolated', 'executablePath', 'userDataDir'],
+ default: false,
+ coerce: (value: boolean | undefined) => {
+ if (!value) {
+ return;
+ }
+ return value;
+ },
+ },
browserUrl: {
type: 'string',
description:
@@ -221,6 +234,14 @@ export function parseArguments(version: string, argv = process.argv) {
'$0 --user-data-dir=/tmp/user-data-dir',
'Use a custom user data directory',
],
+ [
+ '$0 --auto-connect',
+ 'Connect to a stable Chrome instance (Chrome 145+) running instead of launching a new instance',
+ ],
+ [
+ '$0 --auto-connect --channel=canary',
+ 'Connect to a canary Chrome instance (Chrome 145+) running instead of launching a new instance',
+ ],
]);
return yargsInstance
diff --git a/src/main.ts b/src/main.ts
index 2d96ab40..e785e9c7 100644
--- a/src/main.ts
+++ b/src/main.ts
@@ -54,11 +54,13 @@ async function getContext(): Promise<McpContext> {
}
const devtools = args.experimentalDevtools ?? false;
const browser =
- args.browserUrl || args.wsEndpoint
+ args.browserUrl || args.wsEndpoint || args.autoConnect
? await ensureBrowserConnected({
browserURL: args.browserUrl,
wsEndpoint: args.wsEndpoint,
wsHeaders: args.wsHeaders,
+ // Important: only pass channel, if autoConnect is true.
+ channel: args.autoConnect ? (args.channel as Channel) : undefined,
devtools,
})
: await ensureBrowserLaunched({
@@ -140,7 +142,10 @@ function registerTool(tool: ToolDefinition): void {
};
} catch (err) {
logger(`${tool.name} error:`, err, err?.stack);
- const errorText = err && 'message' in err ? err.message : String(err);
+ let errorText = err && 'message' in err ? err.message : String(err);
+ if ('cause' in err && err.cause) {
+ errorText += `\nCause: ${err.cause.message}`;
+ }
return {
content: [
{
diff --git a/tests/cli.test.ts b/tests/cli.test.ts
index df0835c1..11e93a3d 100644
--- a/tests/cli.test.ts
+++ b/tests/cli.test.ts
@@ -17,6 +17,8 @@ describe('cli args parsing', () => {
categoryPerformance: true,
'category-network': true,
categoryNetwork: true,
+ 'auto-connect': undefined,
+ autoConnect: undefined,
};
it('parses with default args', async () => {
@@ -208,4 +210,16 @@ describe('cli args parsing', () => {
categoryEmulation: false,
});
});
+ it('parses auto-connect', async () => {
+ const args = parseArguments('1.0.0', ['node', 'main.js', '--auto-connect']);
+ assert.deepStrictEqual(args, {
+ ...defaultArgs,
+ _: [],
+ headless: false,
+ $0: 'npx chrome-devtools-mcp@latest',
+ channel: 'stable',
+ 'auto-connect': true,
+ autoConnect: true,
+ });
+ });
});