facebook-ads-library

This MCP server provides a Python-based integration for querying Facebook's public Ads Library. It exposes tools to map brand strings to platform IDs, fetch current ads for one or more pages, analyze ad creatives (images and videos), and batch-process multiple items to improve efficiency. Use the batch-enabled tools to perform bulk lookups and analyses across several brands or pages in a single request, with smart caching and credit management to minimize redundant calls. The server outputs structured data suitable for downstream analysis in Claude Desktop or Cursor, including insights on ad visuals, messaging, and video performance where you have a Gemini API key configured.

To use, connect this MCP server to Claude Desktop or Cursor using the provided configuration example. Once connected, you can invoke tools such as get_meta_platform_id to resolve brand names to platform IDs, get_meta_ads to retrieve current ads for specific pages, analyze_ad_image to inspect image elements, analyze_ad_video for video-level insights, and analyze_ad_videos_batch to process multiple videos in a single call. The tooling also includes cache and credit management utilities to keep operations fast and within API limits. When using the video analysis tools, ensure you have a Google Gemini API key configured if you plan to analyze video ads.

Prerequisites:

• Python 3.12+
• Pip (Python package manager)
• Scrape Creators API key
• Optional: Google Gemini API key for video analysis

Quick Install (Recommended):

1. Clone the repository and install dependencies in a virtual environment

   git clone http://github.com/talknerdytome-labs/facebook-ads-library-mcp.git
   cd facebook-ads-library-mcp
   python3 -m venv venv
   source venv/bin/activate  # macOS/Linux
   # Windows: .\venv\Scripts\activate
   pip install -r requirements.txt
   

2. Configure API keys

   # Create and edit .env or use provided template
   cp .env.template .env
   # Edit .env with your actual keys
   

   Required keys include SCRAPE_CREATORS_API_KEY and optionally GEMINI_API_KEY for video analysis.
3. Run the MCP server locally (development/testing)

   python mcp_server.py
   

4. Connect to Claude Desktop or Cursor by adding the MCP server configuration:

   {
     "mcpServers": {
       "fb_ad_library": {
         "command": "{{PATH_TO_PROJECT}}/facebook-ads-library-mcp/venv/bin/python",
         "args": ["{{PATH_TO_PROJECT}}/facebook-ads-library-mcp/mcp_server.py"]
       }
     }
   }
   

   Replace {{PATH_TO_PROJECT}} with the full path to the cloned repository.

Manual Install:

1. Clone the repository

   git clone https://github.com/trypeggy/facebook-ads-library-mcp.git
   cd facebook-ads-library-mcp
   

2. Create a virtual environment and install dependencies

   python3 -m venv venv
   source venv/bin/activate  # macOS/Linux
   # Windows: .\venv\Scripts\activate
   pip install -r requirements.txt
   

3. Configure API keys

   cp .env.template .env
   # Edit .env with actual API keys for SCRAPE_CREATORS_API_KEY and GEMINI_API_KEY (optional)
   

4. Connect to the MCP server in Claude Desktop or Cursor using the same JSON snippet as above.

Notes and tips:

• The server supports batch operations for get_meta_platform_id and get_meta_ads, allowing single strings or arrays of inputs for efficiency.
• If you enable video analysis, provide a Google Gemini API key; otherwise, video insights will be limited.
• The system includes smart credit management that detects API credit exhaustion and provides direct top-up links.
• Ensure your environment variables are loaded from a .env file rather than passing keys on the command line for security.
• If you encounter path issues, ensure the command points to the correct Python interpreter inside your virtual environment (venv/bin/python or equivalent on Windows).
• The MCP tools cache results to speed up repeated queries; you can inspect cache stats via get_cache_stats, and manage storage with cleanup_media_cache.