Facebook Ad Library MCP Server

A Model Context Protocol (MCP) server that provides access to Facebook's Ad Library through web scraping. This server exposes a single MCP tool for searching advertisements with comprehensive filtering options.

Features

• MCP-compliant: Built using the official MCP SDK
• Comprehensive ad data: Extracts advertiser, content, dates, impressions, spend, and more
• Advanced filtering: Filter by company, date range, and keywords
• Smart pagination: Auto-scrolling to retrieve up to 100 ads per search
• Flexible sorting: Sort by date (ascending/descending) or relevance

Installation

1. Clone the repository:

git clone <repository-url>
cd FbAdLibraryMCPServer

2. Install dependencies:

npm install

3. Install Playwright browsers:

npx playwright install

Usage

Development

npm run dev

Production

npm run build
npm start

The server will start on port 3000 (configurable via PORT environment variable).

API Documentation

MCP Tool: search_ads

Search for Facebook ads with optional filters.

Parameters:

• company (string, optional): Company/advertiser name to filter by
• start_date (string, optional): Start date in YYYY-MM-DD format
• end_date (string, optional): End date in YYYY-MM-DD format
• keywords (array of strings, optional): Keywords to search in ad content
• limit (integer, optional): Maximum ads to return (default: 50, max: 100)
• order (string, optional): Sort order - "date_desc", "date_asc", or "relevance" (default: "date_desc")

Example Tool Call:

{
  "tool": "search_ads",
  "arguments": {
    "company": "Nike",
    "start_date": "2024-01-01",
    "end_date": "2024-01-31",
    "keywords": ["running", "shoes"],
    "limit": 10,
    "order": "date_desc"
  }
}

Response Format:

{
  "ads": [
    {
      "id": "unique_ad_identifier",
      "advertiser": "Company Name",
      "content": "Ad text content",
      "start_date": "Jan 15, 2024",
      "end_date": "Feb 15, 2024",
      "impressions": "1,000-5,000",
      "spend": "$100-$500",
      "platforms": ["Facebook"],
      "creative_url": "https://...",
      "demographics": {"targeting": "..."},
      "scraped_at": "2024-01-20T10:30:00Z"
    }
  ]
}

MCP Client Connection

Connect to the server using any MCP-compatible client:

HTTP Transport:

• URL: http://localhost:3000/mcp
• Method: POST
• Headers: Content-Type: application/json

Health Check:

• URL: http://localhost:3000/healthz
• Method: GET

Architecture

• MCP Server (src/index.ts): Express HTTP server hosting MCP protocol
• Search Handler (src/mcp/searchAdsHandler.ts): Core business logic
• Web Scraper (src/scraper/scrapeFacebookAds.ts): Playwright-based Facebook scraper
• Filters (src/utils/filters.ts): Date parsing and filtering utilities

Performance Considerations

• Rate Limiting: Built-in delays between requests to avoid blocking
• Pagination: Auto-scrolling with intelligent stopping conditions
• Browser Management: Proper cleanup of Playwright browser instances
• Memory Efficiency: Streaming data processing where possible

Anti-Bot Detection Countermeasures

This server successfully bypasses Facebook's anti-bot detection through:

• Virtual Display (Xvfb): Runs non-headless browsers in cloud environments
• Natural Navigation: Mimics human browsing patterns (homepage → Ad Library)
• Simplified Browser Config: Avoids complex "stealth" techniques that trigger detection
• Smart Timeout Handling: 30-second browser launch timeout with fallback mechanisms
• Production-Optimized: Different behavior in production vs development environments

Known Limitations

• Runs in non-headless mode to avoid detection
• Limited to 100 ads per search to prevent timeouts
• Date formats depend on Facebook's display format
• Subject to Facebook's anti-bot measures

... View full README on GitHub