This project offers an MCP (Model Context Protocol) server for Facebook's Ads Library, enabling users to instantly query and analyze public ad data for any company or brand. It targets researchers, marketers, and analysts seeking to understand competitor advertising strategies, creative approaches, and messaging. The primary benefit is streamlined access to detailed ad insights, including text, image, and video analysis, with options for both self-hosting and a fully managed hosted version.

How It Works

The MCP server acts as an intermediary, allowing AI assistants like Claude or Cursor to interact with Facebook's ad library data. It intelligently batches and optimizes queries to external ads data APIs, employs smart caching to reduce redundant API calls and improve performance, and includes credit monitoring to prevent workflow interruptions. For advanced video ad analysis, it integrates with Google Gemini's AI capabilities.

Quick Start & Requirements

• Primary install: Clone the repository (git clone http://github.com/talknerdytome-labs/facebook-ads-library-mcp.git), navigate into the directory, and run the platform-specific install script (./install.sh for macOS/Linux, install.bat for Windows).
• Prerequisites: Python 3.12+, Pip, an API key for an ads data provider (set as SCRAPECREATORS_API_KEY), and optionally a Google Gemini API key for video analysis.
• Setup: The install script creates a virtual environment, installs dependencies, and sets up configuration files. Users must edit the .env file with their API keys and follow the displayed MCP configuration for their AI assistant.
• Links: Hosted version available via "Start for free here" (link not provided in README). Google AI Studio for Gemini API key.

Highlighted Details

• Provides tools for querying Facebook Ads Library objects, including get_meta_platform_id, get_meta_ads, analyze_ad_image, and analyze_ad_video.
• Features batch analysis capabilities, such as analyze_ad_videos_batch, designed for token efficiency (~88% savings).
• Includes smart caching for ad media and tools for cache statistics and cleanup.
• Offers a fully hosted version, eliminating the need for setup, infrastructure, or API key management.

Maintenance & Community

No specific details regarding notable contributors, sponsorships, community channels (like Discord/Slack), or roadmap are provided in the README.

Licensing & Compatibility

This project is licensed under the MIT License, which is generally permissive for commercial use and integration into closed-source projects.

Limitations & Caveats

Video ad analysis is optional and requires a separate Google Gemini API key. Users managing their own instance must handle API key provisioning and monitor API credit usage to avoid service interruptions. Potential issues like API credit exhaustion and rate limiting are documented with troubleshooting steps.