feat: Add CDP headers support for authenticated connections

- Add cdpHeaders option to browser configuration
- Support --cdp-headers CLI option for JSON header specification
- Add PLAYWRIGHT_MCP_CDP_HEADERS environment variable support
- Update CdpContextFactory to pass headers to connectOverCDP
- Add JSON parsing with error handling for CLI headers
- Add tests for headers functionality and invalid JSON handling
- Update documentation with usage examples

This enables connecting to CDP endpoints that require authentication,
such as AWS Bedrock AgentCore Browser instances.

Author: moritalous

README.md

@@ -155,6 +155,8 @@ Playwright MCP server supports following arguments. They can be provided in the
   --caps <caps>                comma-separated list of additional capabilities
                                to enable, possible values: vision, pdf.
   --cdp-endpoint <endpoint>    CDP endpoint to connect to.
+  --cdp-headers <headers>      JSON string of headers to send with CDP
+                               connection, e.g. '{"Authorization": "Bearer token"}'
   --config <path>              path to the configuration file.
   --device <device>            device to emulate, for example: "iPhone 15"
   --executable-path <path>     path to the browser executable.
@@ -231,6 +233,20 @@ state [here](https://playwright.dev/docs/auth).
 }
 ```
 
+#### CDP Headers
+
+When connecting to a CDP endpoint that requires authentication, you can pass headers:
+
+```bash
+npx @playwright/mcp --cdp-endpoint=http://localhost:9222 --cdp-headers='{"Authorization": "Bearer your-token"}'
+```
+
+Or via environment variable:
+```bash
+export PLAYWRIGHT_MCP_CDP_HEADERS='{"Authorization": "Bearer your-token"}'
+npx @playwright/mcp --cdp-endpoint=http://localhost:9222
+```
+
 ### Configuration file
 
 The Playwright MCP server can be configured using a JSON configuration file. You can specify the configuration file

config.d.ts

@@ -59,6 +59,12 @@ export type Config = {
      */
     cdpEndpoint?: string;
 
+    /**
+     * Additional HTTP headers to be sent with CDP connect request.
+     * Only used when cdpEndpoint is specified.
+     */
+    cdpHeaders?: Record<string, string>;
+
     /**
      * Remote endpoint to connect to an existing Playwright server.
      */

src/browserContextFactory.ts

@@ -134,7 +134,11 @@ class CdpContextFactory extends BaseContextFactory {
   }
 
   protected override async _doObtainBrowser(): Promise<playwright.Browser> {
-    return playwright.chromium.connectOverCDP(this.config.browser.cdpEndpoint!);
+    const options: any = {};
+    if (this.config.browser.cdpHeaders) {
+      options.headers = this.config.browser.cdpHeaders;
+    }
+    return playwright.chromium.connectOverCDP(this.config.browser.cdpEndpoint!, options);
   }
 
   protected override async _doCreateContext(browser: playwright.Browser): Promise<playwright.BrowserContext> {

src/config.ts

@@ -30,6 +30,7 @@ export type CLIOptions = {
   browser?: string;
   caps?: string[];
   cdpEndpoint?: string;
+  cdpHeaders?: Record<string, string>;
   config?: string;
   device?: string;
   executablePath?: string;
@@ -178,6 +179,7 @@ export function configFromCLIOptions(cliOptions: CLIOptions): Config {
       launchOptions,
       contextOptions,
       cdpEndpoint: cliOptions.cdpEndpoint,
+      cdpHeaders: cliOptions.cdpHeaders,
     },
     server: {
       port: cliOptions.port,
@@ -205,6 +207,7 @@ function configFromEnv(): Config {
   options.browser = envToString(process.env.PLAYWRIGHT_MCP_BROWSER);
   options.caps = commaSeparatedList(process.env.PLAYWRIGHT_MCP_CAPS);
   options.cdpEndpoint = envToString(process.env.PLAYWRIGHT_MCP_CDP_ENDPOINT);
+  options.cdpHeaders = parseJsonEnv(process.env.PLAYWRIGHT_MCP_CDP_HEADERS);
   options.config = envToString(process.env.PLAYWRIGHT_MCP_CONFIG);
   options.device = envToString(process.env.PLAYWRIGHT_MCP_DEVICE);
   options.executablePath = envToString(process.env.PLAYWRIGHT_MCP_EXECUTABLE_PATH);
@@ -295,6 +298,20 @@ export function semicolonSeparatedList(value: string | undefined): string[] | un
   return value.split(';').map(v => v.trim());
 }
 
+function parseJsonEnv(value: string | undefined): Record<string, string> | undefined {
+  if (!value)
+    return undefined;
+  try {
+    const parsed = JSON.parse(value);
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+      throw new Error('Expected JSON object');
+    }
+    return parsed;
+  } catch (error) {
+    throw new Error(`Invalid JSON in environment variable: ${error}`);
+  }
+}
+
 export function commaSeparatedList(value: string | undefined): string[] | undefined {
   if (!value)
     return undefined;

src/program.ts

@@ -36,6 +36,7 @@ program
     .option('--browser <browser>', 'browser or chrome channel to use, possible values: chrome, firefox, webkit, msedge.')
     .option('--caps <caps>', 'comma-separated list of additional capabilities to enable, possible values: vision, pdf.', commaSeparatedList)
     .option('--cdp-endpoint <endpoint>', 'CDP endpoint to connect to.')
+    .option('--cdp-headers <headers>', 'JSON string of headers to send with CDP connection, e.g. \'{"Authorization": "Bearer token"}\'')
     .option('--config <path>', 'path to the configuration file.')
     .option('--device <device>', 'device to emulate, for example: "iPhone 15"')
     .option('--executable-path <path>', 'path to the browser executable.')
@@ -67,6 +68,18 @@ program
         console.error('The --vision option is deprecated, use --caps=vision instead');
         options.caps = 'vision';
       }
+
+      // Parse CDP headers if provided
+      if (options.cdpHeaders) {
+        try {
+          options.cdpHeaders = JSON.parse(options.cdpHeaders);
+        } catch (error) {
+          // eslint-disable-next-line no-console
+          console.error('Invalid JSON format for --cdp-headers:', error);
+          process.exit(1);
+        }
+      }
+
       const config = await resolveCLIConfig(options);
 
       if (options.extension) {

tests/cdp.spec.ts

@@ -84,6 +84,31 @@ test('should throw connection error and allow re-connecting', async ({ cdpServer
   });
 });
 
+test('cdp server with headers', async ({ cdpServer, startClient, server }) => {
+  await cdpServer.start();
+  const headers = { 'X-Test-Header': 'test-value' };
+  const { client } = await startClient({ 
+    args: [`--cdp-endpoint=${cdpServer.endpoint}`, `--cdp-headers=${JSON.stringify(headers)}`] 
+  });
+  expect(await client.callTool({
+    name: 'browser_navigate',
+    arguments: { url: server.HELLO_WORLD },
+  })).toHaveResponse({
+    pageState: expect.stringContaining(`- generic [active] [ref=e1]: Hello, world!`),
+  });
+});
+
+test('cdp server with invalid headers JSON', async () => {
+  const result = spawnSync('node', [
+    path.join(__filename, '../../cli.js'), 
+    '--cdp-endpoint=http://localhost:1234',
+    '--cdp-headers=invalid-json'
+  ]);
+  expect(result.error).toBeUndefined();
+  expect(result.status).toBe(1);
+  expect(result.stderr.toString()).toContain('Invalid JSON format for --cdp-headers');
+});
+
 // NOTE: Can be removed when we drop Node.js 18 support and changed to import.meta.filename.
 const __filename = url.fileURLToPath(import.meta.url);