Browserless MCP Server

Instructions

Implementation Reference

• src/client.ts:85-108 (handler)

  Core implementation of the take_screenshot tool: sends POST /screenshot to Browserless API, receives image buffer, formats response with filename.

  async takeScreenshot(request: ScreenshotRequest): Promise<BrowserlessResponse<ScreenshotResponse>> {
    try {
      const response: AxiosResponse<Buffer> = await this.httpClient.post('/screenshot', request, {
        responseType: 'arraybuffer',
        headers: {
          'Content-Type': 'application/json',
        },
      });
  
      const format = request.options?.type || 'png';
      const filename = `screenshot-${Date.now()}.${format}`;
  
      return {
        success: true,
        data: {
          image: Buffer.from(response.data),
          filename,
          format,
        },
      };
    } catch (error) {
      return this.handleError(error);
    }
  }

• src/index.ts:323-343 (handler)

  MCP server dispatch handler for 'take_screenshot': calls BrowserlessClient.takeScreenshot and returns MCP-formatted response with base64 image.

  case 'take_screenshot': {
    if (!args) throw new Error('Arguments are required');
    const result = await this.client!.takeScreenshot(args as any);
    if (result.success && result.data) {
      return {
        content: [
          {
            type: 'text',
            text: `Screenshot taken successfully. Filename: ${result.data.filename}`,
          },
          {
            type: 'binary',
            mimeType: `image/${result.data.format}`,
            data: result.data.image.toString('base64'),
          },
        ],
      };
    } else {
      throw new Error(result.error || 'Failed to take screenshot');
    }
  }

• src/index.ts:81-109 (registration)

  Tool registration in MCP ListToolsResponse: defines name, description, and JSON input schema for 'take_screenshot'.

  {
    name: 'take_screenshot',
    description: 'Take screenshot of a webpage',
    inputSchema: {
      type: 'object',
      properties: {
        url: { type: 'string' },
        options: {
          type: 'object',
          properties: {
            type: { type: 'string', enum: ['png', 'jpeg', 'webp'] },
            quality: { type: 'number' },
            fullPage: { type: 'boolean' },
            omitBackground: { type: 'boolean' },
            clip: {
              type: 'object',
              properties: {
                x: { type: 'number' },
                y: { type: 'number' },
                width: { type: 'number' },
                height: { type: 'number' },
              },
            },
          },
        },
      },
      required: ['url'],
    },
  },

• src/types.ts:131-148 (schema)

  Zod schema (ScreenshotRequestSchema) and TypeScript type for screenshot requests used internally by BrowserlessClient.

  export const ScreenshotRequestSchema = z.object({
    url: z.string(),
    options: ScreenshotOptionsSchema.optional(),
    addScriptTag: z.array(ScriptTagSchema).optional(),
    addStyleTag: z.array(StyleTagSchema).optional(),
    cookies: z.array(CookieSchema).optional(),
    headers: z.record(z.string()).optional(),
    viewport: ViewportSchema.optional(),
    gotoOptions: z.object({
      waitUntil: z.string().optional(),
      timeout: z.number().optional(),
    }).optional(),
    waitForSelector: WaitForSelectorSchema.optional(),
    waitForFunction: WaitForFunctionSchema.optional(),
    waitForTimeout: z.number().optional(),
  });
  
  export type ScreenshotRequest = z.infer<typeof ScreenshotRequestSchema>;