Facebook Ads Library MCP Server

How to use

Connect the MCP server to your client (Claude Desktop or Cursor) and start sending queries for brand ads, ad images, and video analyses. Use individual prompts to inspect a single brand, or use batch analyses to compare several brands at once. Take advantage of the new batch capabilities to reduce API calls and speed up your workloads. The server will handle authentication, batching, caching, and credit monitoring, returning structured results you can use to draw campaign insights.

Typical workflows you can perform include: querying the current ads for a brand and its platform IDs, analyzing ad images for visual elements and composition, analyzing ad videos with Gemini AI, and comparing messaging strategies across several brands. When you run batch queries, you’ll get consolidated results with reduced token usage and faster turnaround.

How to install

Prerequisites you need before installing: Python 3.12 or higher, an Anthropic Claude desktop app (or Cursor), Pip, a Scrape Creators API key, and a Google Gemini API key if you plan to analyze video ads.

# Quick Install (as described)
# 1) Clone the MCP project
git clone http://github.com/talknerdytome-labs/facebook-ads-library-mcp.git
cd facebook-ads-library-mcp

# 2) Run the install script (macOS/Linux) or Windows counterpart
./install.sh
# or on Windows
install.bat

# The install will:
# - Create a virtual environment
# - Install required dependencies
# - Create configuration files

# 3) Configure your API keys
# Edit the .env file created by the installer
# - SCRAPECREATORS_API_KEY=your_key_here
# - GEMINI_API_KEY=your_key_here (optional for video analysis)

# 4) Use the MCP configuration shown during setup
# The installer will display the exact MCP configuration to add to your client

Manual install steps, if you prefer to set things up yourself, are shown here. Follow these steps exactly to ensure your environment matches the expected configuration.

# 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
./venv/bin/pip install -r requirements.txt

# 3) Configure API keys
cp .env.template .env
# Edit .env to include:
# SCRAPECREATORS_API_KEY=your_key_here
# GEMINI_API_KEY=your_key_here (optional)

# 4) Connect to the MCP server from Claude Desktop or Cursor
# Add the following MCP configuration (see the code block below for exact syntax)

Additional setup and configuration

The MCP configuration is loaded from the environment file. API keys are read from the .env file, so you don’t pass them as command line arguments. If you need to verify the server and its environment, you can place the configuration snippet into your client as shown.

{
  "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"
      ]
    }
  }
}

Troubleshooting and notes

If you encounter Scrape Creators API credits exhaustion, top up your account via the Scrape Creators dashboard. The system will automatically resume once credits are available. If you hit rate limits, batch operations help reduce the likelihood, and spacing out large batch requests can prevent interruptions.

Video analysis requires a valid Google Gemini API key in your .env file. Check that GEMINI_API_KEY is set if you experience issues with video insights.

If the MCP server cannot connect, verify that the path in your client’s configuration points to the correct location, ensure the virtual environment is active, and restart your client after changes.

Tips for optimal use

Leverage the enhanced batch processing to run multiple brand queries in a single request. This reduces total API calls and speeds up results. Use the new video batch analysis to process several videos in one Gemini call, saving tokens and costs.

Monitor cache stats to understand how frequently responses are served from cache versus fetched from the Scrape Creators API. Enable deduplication to avoid repeating identical requests within batch operations.

get_meta_platform_id

Returns platform IDs for one or more brand names, enabling downstream queries for ads and metadata.

get_meta_ads

Retrieves ads for specific page IDs (platform IDs) with support for multiple IDs in batch queries.

analyze_ad_image

Analyzes ad images to extract visual elements, colors, and composition details.

analyze_ad_video

Analyzes a single ad video using Gemini AI for comprehensive insights.

analyze_ad_videos_batch

Analyzes multiple videos in a single Gemini API call to save tokens and speed up batch processing.

get_cache_stats

Provides statistics about cached media and storage usage.

search_cached_media

Searches previously analyzed media by brand, colors, people, or media type.

cleanup_media_cache

Cleans up old cached media files to reclaim disk space.