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

Legal & Ethical Notes

- Respects Facebook's rate limiting through built-in delays
- Does not store personal user data
- Intended for research and analysis purposes
- Users should comply with Facebook's Terms of Service

Dependencies

- @modelcontextprotocol/sdk: MCP protocol implementation
- playwright: Web scraping automation
- date-fns: Date parsing and manipulation
- express: HTTP server framework
- zod: Runtime type validation

Deployment (Fly.io)

1. Install flyctl:

curl -L https://fly.io/install.sh | sh

export FLYCTL_INSTALL="/root/.fly"

export PATH="$FLYCTL_INSTALL/bin:$PATH"

2. Deploy to Fly.io:

flyctl auth signup

flyctl launch --no-deploy

flyctl secrets set NODE_ENV=production

flyctl deploy

3. Live Deployment:
- App URL: https://fbadlibrarymcpserver.fly.dev
- Health check: https://fbadlibrarymcpserver.fly.dev/healthz
- MCP endpoint: https://fbadlibrarymcpserver.fly.dev/mcp (POST only)
- Test endpoint: https://fbadlibrarymcpserver.fly.dev/test-search (GET/POST)

Connection Details

Public URL: https://fbadlibrarymcpserver.fly.dev

Quick Test: https://fbadlibrarymcpserver.fly.dev/test-search?company=Nike&limit=3

MCP Client Configuration:

{

  "transport": "http",

  "url": "https://fbadlibrarymcpserver.fly.dev/mcp",

  "method": "POST",

  "headers": {

    "Content-Type": "application/json",

    "Accept": "application/json, text/event-stream"

  }

}

Authentication: None required

License

ISC