Facebook Ads Library MCP server for AI agents

The Facebook Ads Library MCP server allows you to search Facebook's public ads library to analyze advertising campaigns from any company or brand. You can examine current ads, analyze images and videos, compare strategies across companies, and gain insights into effective campaign techniques.

Installation

Prerequisites

Python 3.12+
Anthropic Claude Desktop app (or Cursor)
Pip (Python package manager)
An access token from Scrape Creators
Google Gemini API key (optional, only for video ad analysis)

Quick Installation

Clone the repository and run the install script:

git clone http://github.com/talknerdytome-labs/facebook-ads-library-mcp.git
cd facebook-ads-library-mcp

# For macOS/Linux:
./install.sh

# For Windows:
install.bat

Configure your API keys:

Edit the .env file that was created during installation and add your API keys:
- Scrape Creators API key from scrapecreators.com
- Gemini API key from Google AI Studio (optional, for video analysis)
Add the MCP configuration to Claude Desktop or Cursor as shown by the installation script.

Manual Installation

If you prefer to install manually:

Clone the repository:

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

Create a virtual environment and install dependencies:

python3 -m venv venv
./venv/bin/pip install -r requirements.txt

Configure your API keys:

cp .env.template .env
# Edit .env with your API keys

Add the MCP server configuration to Claude Desktop or Cursor:

{
  "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 your repository.

For Claude Desktop, save as:

~/Library/Application Support/Claude/claude_desktop_config.json

For Cursor, save as:

~/.cursor/mcp.json

Restart Claude Desktop or Cursor

Usage Examples

Single Brand Analysis

You can ask Claude questions like:

How many ads is 'AnthropicAI' running? What's their split across video and image?

What messaging is 'AnthropicAI' running right now in their ads?

Analyze the video ads from 'Nike' and extract their visual storytelling strategy, pacing, and brand messaging techniques.

Batch Analysis

For comparing multiple brands:

Compare the current advertising strategies across Nike, Adidas, and Under Armour. Show me their ad volumes, messaging themes, and creative approaches.

Do a deep comparison to the messaging between 'AnthropicAI', 'Perplexity AI' and 'OpenAI'. Give it a nice forwardable summary.

Analyze the holiday campaign strategies for Coca-Cola, Pepsi, Dr Pepper, and Sprite. What themes are they using?

Available Tools

The MCP server provides these tools:

Tool Name	Description	Batch Support
`get_meta_platform_id`	Returns platform ID for one or many brand names	✅ Multiple brands
`get_meta_ads`	Retrieves ads for specific page(s)	✅ Multiple platform IDs
`analyze_ad_image`	Analyzes ad images for visual elements, text, colors, and composition	⚡ Enhanced caching
`analyze_ad_video`	Analyzes single ad video using Gemini AI	⚡ Enhanced caching
`analyze_ad_videos_batch`	Analyzes multiple videos in a single API call	🎬 ~88% token savings
`get_cache_stats`	Gets 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 free disk space	-

Troubleshooting

Common Issues

ScrapeCreators API Credits Exhausted:

When you see this error, you need to top up your account
The error message includes a direct link to ScrapeCreators Dashboard
You can check your balance and purchase more credits there

Rate Limit Exceeded:

If you hit rate limits, the server will tell you how long to wait
Consider spacing out large batch requests

API Key Not Found Error:

Ensure your .env file is in the project root directory
Check that your API keys are correctly formatted
For video analysis, make sure GEMINI_API_KEY is added

Video Analysis Not Working:

Confirm you have a valid Google Gemini API key in your .env file

MCP Server Connection Issues:

Verify the path in your MCP configuration points to the correct location
Make sure you've created a virtual environment and installed dependencies
Ensure your MCP configuration uses the virtual environment Python path
Restart Claude Desktop/Cursor after configuration changes

For additional Claude Desktop integration troubleshooting, see the MCP documentation.

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "fb_ad_library" '{"command":"python","args":["{{PATH_TO_SRC}}/fb_ad_library_mcp/src/mcp_server.py","--scrapecreators-api-key","{{YOUR_SCRAPECREATORS_API_KEY}}"]}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "fb_ad_library": {
            "command": "python",
            "args": [
                "{{PATH_TO_SRC}}/fb_ad_library_mcp/src/mcp_server.py",
                "--scrapecreators-api-key",
                "{{YOUR_SCRAPECREATORS_API_KEY}}"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "mcpServers": {
        "fb_ad_library": {
            "command": "python",
            "args": [
                "{{PATH_TO_SRC}}/fb_ad_library_mcp/src/mcp_server.py",
                "--scrapecreators-api-key",
                "{{YOUR_SCRAPECREATORS_API_KEY}}"
            ]
        }
    }
}

3. Restart Claude Desktop for the changes to take effect