Selenium MCP Server

Instructions

Implementation Reference

• src/tools/browserTools.ts:15-44 (handler)

  The core handler function for the browser_open tool. It launches the specified browser using BrowserService.createDriver, generates a unique session ID, stores the driver in StateManager, sets the current session, and returns a success or error message in MCP format.

  async ({ browser, options = {} }) => {
    try {
      const driver = await BrowserService.createDriver(browser, {
        ...options,
        headless: typeof options.headless === 'boolean' ? options.headless : false,
        arguments: options.arguments ?? [],
      });
      const sessionId = `${browser}_${Date.now()}`;
  
      stateManager.addDriver(sessionId, driver);
      stateManager.setCurrentSession(sessionId);
  
      return {
        content: [
          {
            type: 'text',
            text: `Browser started with session_id: ${sessionId}`,
          },
        ],
      };
    } catch (e) {
      return {
        content: [
          {
            type: 'text',
            text: `Error starting browser: ${(e as Error).message}`,
          },
        ],
      };
    }

• src/tools/browserTools.ts:8-46 (registration)

  The registration of the browser_open tool using server.tool(), including the tool name, description, input schema (browser type and options), and the inline handler function.

  server.tool(
    'browser_open',
    'Open a new browser session',
    {
      browser: z.enum(['chrome', 'firefox', 'edge', 'safari']).describe('Browser to launch'),
      options: browserOptionsSchema,
    },
    async ({ browser, options = {} }) => {
      try {
        const driver = await BrowserService.createDriver(browser, {
          ...options,
          headless: typeof options.headless === 'boolean' ? options.headless : false,
          arguments: options.arguments ?? [],
        });
        const sessionId = `${browser}_${Date.now()}`;
  
        stateManager.addDriver(sessionId, driver);
        stateManager.setCurrentSession(sessionId);
  
        return {
          content: [
            {
              type: 'text',
              text: `Browser started with session_id: ${sessionId}`,
            },
          ],
        };
      } catch (e) {
        return {
          content: [
            {
              type: 'text',
              text: `Error starting browser: ${(e as Error).message}`,
            },
          ],
        };
      }
    }
  );

• src/types/index.ts:22-27 (schema)

  Zod schema definition for browserOptionsSchema, which defines optional headless mode and arguments parameters used in the browser_open tool's input schema.

  export const browserOptionsSchema = z
    .object({
      headless: z.boolean().optional().describe('Run browser in headless mode'),
      arguments: z.array(z.string()).optional().describe('Additional browser arguments'),
    })
    .optional();

• src/services/browserService.ts:47-63 (helper)

  BrowserService.createDriver method, a supporting utility called by the browser_open handler to instantiate the appropriate WebDriver based on the browser type and options.

  static async createDriver(
    browser: 'chrome' | 'firefox' | 'edge' | 'safari',
    options: BrowserOptions = {}
  ): Promise<WebDriver> {
    switch (browser) {
      case 'chrome':
        return this.createChromeDriver(options);
      case 'edge':
        return this.createEdgeDriver(options);
      case 'firefox':
        return this.createFirefoxDriver(options);
      case 'safari':
        return this.createSafariDriver();
      default:
        throw new Error(`Unsupported browser: ${browser}`);
    }
  }

• src/server.ts:54-55 (registration)

  Top-level call to registerAllTools during server initialization, which indirectly registers the browser_open tool via the tools index.

  // Register all tools
  registerAllTools(this.server, this.stateManager);