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

This PR adds a new connection mode called `--auto-connect`. To activate
it, add the `--auto-connect` flag to the chrome-devtools-mcp server
configuration. With this, chrome-devtools-mcp will automatically connect
to the running Chrome instance by looking up the port and the URL in the
user data dir for the specified `--channel` (by default, `stable`).
Requires Chrome M145.

Author: OrKoN

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

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;
 }

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

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: [
             {

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,
+    });
+  });
 });