feat: add --marionette-host for remote/tunneled Firefox

Adds a --marionette-host CLI parameter (and MARIONETTE_HOST env var)
that controls which host geckodriver connects to for Marionette and
where the BiDi WebSocket connection is directed.

When connecting to a remote or tunneled Firefox (e.g., via SSH port
forwarding), the Marionette and BiDi ports are on a different host
than localhost. This parameter lets geckodriver reach the tunnel
endpoint while preserving the original Host header for Firefox's
WebSocket allowHosts check.

Author: MayCXC

src/cli.ts

@@ -110,6 +110,11 @@ export const cliOptions = {
     description: 'Marionette port to connect to when using --connect-existing (default: 2828)',
     default: Number(process.env.MARIONETTE_PORT ?? '2828'),
   },
+  marionetteHost: {
+    type: 'string',
+    description: 'Marionette host to connect to when using --connect-existing (default: 127.0.0.1). Also used as the BiDi WebSocket connect address when different from 127.0.0.1.',
+    default: process.env.MARIONETTE_HOST ?? '127.0.0.1',
+  },
   env: {
     type: 'array',
     description:

src/firefox/core.ts

@@ -140,7 +140,7 @@ class GeckodriverHttpDriver implements IDriver {
     this.webSocketUrl = webSocketUrl;
   }
 
-  static async connect(marionettePort: number): Promise<GeckodriverHttpDriver> {
+  static async connect(marionettePort: number, marionetteHost = '127.0.0.1'): Promise<GeckodriverHttpDriver> {
     // Find geckodriver binary via selenium-manager
     const path = await import('node:path');
     const { execFileSync } = await import('node:child_process');
@@ -179,7 +179,7 @@ class GeckodriverHttpDriver implements IDriver {
     // Use --port=0 to let the OS assign a free port atomically (geckodriver ≥0.34.0)
     const gd = spawn(
       geckodriverPath,
-      ['--connect-existing', '--marionette-port', String(marionettePort), '--port', '0'],
+      ['--connect-existing', '--marionette-host', marionetteHost, '--marionette-port', String(marionettePort), '--port', '0'],
       { stdio: ['ignore', 'pipe', 'pipe'] }
     );
 
@@ -223,7 +223,14 @@ class GeckodriverHttpDriver implements IDriver {
       throw new Error(`Failed to create session: ${JSON.stringify(json)}`);
     }
 
-    const wsUrl = json.value.capabilities.webSocketUrl as string | undefined;
+    let wsUrl = json.value.capabilities.webSocketUrl as string | undefined;
+    logDebug(`Session capabilities webSocketUrl: ${wsUrl ?? 'not present'}, marionetteHost: ${marionetteHost}`);
+    if (wsUrl && marionetteHost !== '127.0.0.1') {
+      // Rewrite the URL to connect through the remote host / tunnel.
+      const parsed = new URL(wsUrl);
+      parsed.hostname = marionetteHost;
+      wsUrl = parsed.toString();
+    }
     if (wsUrl) {
       logDebug(`BiDi WebSocket URL: ${wsUrl}`);
     } else {
@@ -445,12 +452,18 @@ class GeckodriverHttpDriver implements IDriver {
     this.gdProcess.kill();
   }
 
-  /** Kill the geckodriver process without closing Firefox */
-  kill(): void {
+  /** Kill the geckodriver process without closing Firefox.
+   *  Deletes the session first so Marionette accepts new connections. */
+  async kill(): Promise<void> {
     if (this.bidiConnection) {
       (this.bidiConnection.socket as unknown as WebSocket).close();
       this.bidiConnection = null;
     }
+    try {
+      await this.cmd('DELETE', '');
+    } catch {
+      // ignore
+    }
     this.gdProcess.kill();
   }
 
@@ -470,9 +483,11 @@ class GeckodriverHttpDriver implements IDriver {
     const ws = new WebSocket(this.webSocketUrl);
     await new Promise<void>((resolve, reject) => {
       ws.on('open', resolve);
-      ws.on('error', reject);
+      ws.on('error', (e: any) => {
+        const msg = e?.message || e?.error?.message || e?.error || e?.type || JSON.stringify(e) || String(e);
+        reject(new Error(`BiDi WS to ${this.webSocketUrl}: ${msg}`));
+      });
     });
-    logDebug('BiDi WebSocket connected');
 
     let cmdId = 0;
     const subscribe = async (event: string, contexts?: string[]): Promise<void> => {
@@ -572,7 +587,8 @@ export class FirefoxCore {
       // We bypass selenium-webdriver because its BiDi auto-upgrade hangs
       // when used with geckodriver's --connect-existing mode.
       const port = this.options.marionettePort ?? 2828;
-      this.driver = await GeckodriverHttpDriver.connect(port);
+      const host = this.options.marionetteHost ?? '127.0.0.1';
+      this.driver = await GeckodriverHttpDriver.connect(port, host);
     } else {
       // Set up output file for capturing Firefox stdout/stderr
       if (this.options.logFile) {
@@ -709,7 +725,7 @@ export class FirefoxCore {
    */
   reset(): void {
     if (this.driver && this.options.connectExisting && 'kill' in this.driver) {
-      (this.driver as { kill(): void }).kill();
+      (this.driver as { kill(): Promise<void> }).kill();
     }
     this.driver = null;
     this.currentContextId = null;
@@ -831,7 +847,7 @@ export class FirefoxCore {
   async close(): Promise<void> {
     if (this.driver) {
       if (this.options.connectExisting && 'kill' in this.driver) {
-        (this.driver as { kill(): void }).kill();
+        await (this.driver as { kill(): Promise<void> }).kill();
       } else if ('quit' in this.driver) {
         await (this.driver as { quit(): Promise<void> }).quit();
       }

src/firefox/index.ts

@@ -74,12 +74,20 @@ export class FirefoxClient {
       (id: string) => this.core.setCurrentContextId(id)
     );
 
-    // Subscribe to console and network events for ALL contexts (not just current)
-    if (this.consoleEvents) {
-      await this.consoleEvents.subscribe(undefined);
-    }
-    if (this.networkEvents) {
-      await this.networkEvents.subscribe(undefined);
+    // Subscribe to console and network events for ALL contexts (not just current).
+    // BiDi may not be available (e.g., tunneled connect-existing without
+    // Remote Agent). Treat subscription failure as non-fatal.
+    try {
+      if (this.consoleEvents) {
+        await this.consoleEvents.subscribe(undefined);
+      }
+      if (this.networkEvents) {
+        await this.networkEvents.subscribe(undefined);
+      }
+    } catch (e) {
+      console.error(`[firefox-devtools-mcp] BiDi subscription failed (non-fatal): ${e}`);
+      this.consoleEvents = undefined as any;
+      this.networkEvents = undefined as any;
     }
   }
 

src/firefox/types.ts

@@ -60,6 +60,7 @@ export interface FirefoxLaunchOptions {
   acceptInsecureCerts?: boolean | undefined;
   connectExisting?: boolean | undefined;
   marionettePort?: number | undefined;
+  marionetteHost?: string | undefined;
   env?: Record<string, string> | undefined;
   logFile?: string | undefined;
   /** Firefox preferences to set at startup via moz:firefoxOptions */

src/index.ts

@@ -142,6 +142,7 @@ export async function getFirefox(): Promise<FirefoxDevTools> {
       acceptInsecureCerts: args.acceptInsecureCerts,
       connectExisting: args.connectExisting,
       marionettePort: args.marionettePort,
+      marionetteHost: args.marionetteHost,
       env: envVars,
       logFile: args.outputFile ?? undefined,
       prefs,
@@ -358,6 +359,21 @@ async function main() {
 
   log('Firefox DevTools MCP server running on stdio');
   log('Ready to accept tool requests');
+
+  // Graceful shutdown: clean up the Marionette session so Firefox
+  // accepts new connections. Without this, the session stays locked.
+  const cleanup = async () => {
+    if (firefox) {
+      try {
+        await firefox.close();
+      } catch {
+        // ignore
+      }
+    }
+    process.exit(0);
+  };
+  process.on('SIGTERM', cleanup);
+  process.on('SIGINT', cleanup);
 }
 
 // Only run main() if this file is executed directly (not imported)