Browserless MCP Server

Instructions

Implementation Reference

• src/index.ts:191-204 (registration)

  Registration of the 'unblock' tool in the MCP server's listTools handler, defining name, description, and input schema.

  name: 'unblock',
  description: 'Bypass bot detection and anti-scraping measures',
  inputSchema: {
    type: 'object',
    properties: {
      url: { type: 'string' },
      content: { type: 'boolean' },
      screenshot: { type: 'boolean' },
      stealth: { type: 'boolean' },
      blockAds: { type: 'boolean' },
      headers: { type: 'object' },
    },
    required: ['url'],
  },

• src/index.ts:458-488 (handler)

  MCP server handler for the 'unblock' tool. Calls BrowserlessClient.unblock(), handles response including text content and binary screenshot, returns MCP content array.

  case 'unblock': {
    if (!args) throw new Error('Arguments are required');
    const result = await this.client!.unblock(args as any);
    if (result.success && result.data) {
      const content = [
        {
          type: 'text',
          text: 'Unblock operation completed successfully.',
        },
      ];
  
      if (result.data.content) {
        content.push({
          type: 'text',
          text: result.data.content,
        });
      }
  
      if (result.data.screenshot) {
        content.push({
          type: 'binary',
          mimeType: 'image/png',
          data: result.data.screenshot.toString('base64'),
        } as any);
      }
  
      return { content };
    } else {
      throw new Error(result.error || 'Failed to unblock');
    }
  }

• src/types.ts:211-223 (schema)

  Zod schema and TypeScript type for UnblockRequest used by the client.unblock method.

  export const UnblockRequestSchema = z.object({
    url: z.string(),
    browserWSEndpoint: z.boolean().optional(),
    cookies: z.boolean().optional(),
    content: z.boolean().optional(),
    screenshot: z.boolean().optional(),
    ttl: z.number().optional(),
    stealth: z.boolean().optional(),
    blockAds: z.boolean().optional(),
    headers: z.record(z.string()).optional(),
  });
  
  export type UnblockRequest = z.infer<typeof UnblockRequestSchema>;

• src/types.ts:298-303 (schema)

  TypeScript interface for UnblockResponse returned by the Browserless /unblock endpoint.

  export interface UnblockResponse {
    content?: string;
    screenshot?: Buffer;
    cookies?: Cookie[];
    browserWSEndpoint?: string;
  }

• src/client.ts:201-212 (helper)

  BrowserlessClient.unblock method that proxies the request to the Browserless server's /unblock HTTP endpoint via axios.

  async unblock(request: UnblockRequest): Promise<BrowserlessResponse<UnblockResponse>> {
    try {
      const response: AxiosResponse<UnblockResponse> = await this.httpClient.post('/unblock', request);
  
      return {
        success: true,
        data: response.data,
      };
    } catch (error) {
      return this.handleError(error);
    }
  }