BrowserStack MCP server

Instructions

Implementation Reference

• src/tools/live.ts:127-160 (registration)

  Registers the 'runBrowserLiveSession' tool on the McpServer, specifying name, description, input schema (LiveArgsShape), and the handler function that calls runBrowserSession with error handling and tracking.

  tools.runBrowserLiveSession = server.tool(
    "runBrowserLiveSession",
    "Launch a BrowserStack Live session (desktop or mobile).",
    LiveArgsShape,
    async (args) => {
      try {
        trackMCP(
          "runBrowserLiveSession",
          server.server.getClientVersion()!,
          undefined,
          config,
        );
        return await runBrowserSession(args, config);
      } catch (error) {
        logger.error("Live session failed: %s", error);
        trackMCP(
          "runBrowserLiveSession",
          server.server.getClientVersion()!,
          error,
          config,
        );
        return {
          content: [
            {
              type: "text" as const,
              text: `Failed to start a browser live session. Error: ${error}`,
              isError: true,
            },
          ],
          isError: true,
        };
      }
    },
  );

• src/tools/live.ts:11-38 (schema)

  Defines the Zod input schema (LiveArgsShape and LiveArgsSchema) used for validating tool arguments including platformType, desiredURL, OS, browser, etc.

  const LiveArgsShape = {
    platformType: z
      .nativeEnum(PlatformType)
      .describe("Must be 'desktop' or 'mobile'"),
    desiredURL: z.string().url().describe("The URL to test"),
    desiredOS: z
      .enum(["Windows", "OS X", "android", "ios", "winphone"])
      .describe(
        "Desktop OS ('Windows' or 'OS X') or mobile OS ('android','ios','winphone')",
      ),
    desiredOSVersion: z
      .string()
      .describe(
        "The OS version must be specified as a version number (e.g., '10', '14.0') or as a keyword such as 'latest' or 'oldest'. Normalize variations like 'newest' or 'most recent' to 'latest', and terms like 'earliest' or 'first' to 'oldest'. For macOS, version names (e.g., 'Sequoia') must be used instead of numeric versions.",
      ),
    desiredBrowser: z
      .enum(["chrome", "firefox", "safari", "edge", "ie"])
      .describe("Browser for desktop (Chrome, IE, Firefox, Safari, Edge)"),
    desiredBrowserVersion: z
      .string()
      .optional()
      .describe(
        "Browser version for desktop (e.g. '133.2', 'latest'). If the user says 'latest', 'newest', or similar, normalize it to 'latest'. Likewise, convert terms like 'earliest' or 'oldest' to 'oldest'.",
      ),
    desiredDevice: z.string().optional().describe("Device name for mobile"),
  };
  
  const LiveArgsSchema = z.object(LiveArgsShape);

• src/tools/live.ts:90-119 (handler)

  Core handler function invoked by the registered tool handler. Validates input args, determines desktop/mobile, launches the session via launchDesktopSession or launchMobileSession, and returns the launch URL in a response object.

  async function runBrowserSession(rawArgs: any, config: BrowserStackConfig) {
    // Validate and narrow
    const args = LiveArgsSchema.parse(rawArgs);
  
    // Branch desktop vs mobile and delegate
    const launchUrl =
      args.platformType === PlatformType.DESKTOP
        ? await launchDesktopSession(args, config)
        : await launchMobileSession(args, config);
  
    let response = [
      {
        type: "text" as const,
        text: `✅ Session started. If it didn't open automatically, visit:\n${launchUrl}`,
      },
    ];
  
    if (globalConfig.REMOTE_MCP) {
      response = [
        {
          type: "text" as const,
          text: `✅ To start the session. Click on ${launchUrl}`,
        },
      ];
    }
  
    return {
      content: response,
    };
  }

• src/tools/live-utils/start-session.ts:47-80 (helper)

  Key helper function that starts the browser session: filters device/browser capabilities, sets up local tunnel if needed, builds the BrowserStack dashboard URL with parameters, opens browser if local, returns the URL.

  export async function startBrowserSession(
    args: DesktopSearchArgs | MobileSearchArgs,
    config: BrowserStackConfig,
  ): Promise<string> {
    const entry =
      args.platformType === PlatformType.DESKTOP
        ? await filterDesktop(args as DesktopSearchArgs)
        : await filterMobile(args as MobileSearchArgs);
  
    // Get credentials from config
    const authString = getBrowserStackAuth(config);
    const [username, password] = authString.split(":");
  
    if (!username || !password) {
      throw new Error(
        "BrowserStack credentials are not set. Please configure them in the server settings.",
      );
    }
  
    const isLocal = await prepareLocalTunnel(args.url, username, password);
  
    const url =
      args.platformType === PlatformType.DESKTOP
        ? buildDesktopUrl(
            args as DesktopSearchArgs,
            entry as DesktopEntry,
            isLocal,
          )
        : buildMobileUrl(args as MobileSearchArgs, entry as MobileEntry, isLocal);
    if (!envConfig.REMOTE_MCP) {
      openBrowser(url);
    }
    return entry.notes ? `${url}, ${entry.notes}` : url;
  }