FA
SearchCommunication

Facebook Ads Library Research MCP Server

Analyze Facebook Ads Library data quickly on an MCP server to get answers, perform deep research, test messaging and creatives, and run comparisons in seconds.

View on GitHub
Quick Install
npx -y @trypeggy/facebook-ads-library-mcp

Overview

This MCP (Model Context Protocol) server provides fast, programmatic access to Facebook Ads Library data optimized for research workflows. It wraps ad library search, retrieval, and lightweight analysis into an MCP-compatible API so you can ask targeted questions, run side‑by‑side comparisons, and evaluate messaging or creatives in seconds. The server is intended for developers and researchers who want to iterate quickly on ad-level insights without building their own ingestion and search stack.

Under the hood the server indexes raw Ads Library records and exposes tools for semantic search, comparisons, and metric aggregation. It can be integrated with LLMs or other analysis agents via the MCP spec so that context-rich answers can be constructed from fresh ad data. The project repository is available at https://github.com/trypeggy/facebook-ads-library-mcp.

Features

  • Fast semantic search across Facebook Ads Library entries (by text, advertiser, dates, and metadata).
  • Side‑by‑side ad comparison and delta summaries (messaging, creative format, targeting signals).
  • Creative testing helpers: extract headlines, descriptions, CTA, and image metadata for quick evaluation.
  • Prebuilt aggregation endpoints: impressions, spend, active dates, and ad frequency indicators.
  • MCP-compatible toolset for integration with LLMs and automated agents.
  • Configurable ingestion and caching for research-scale datasets.

Installation / Configuration

Prerequisites: Docker (recommended) or Node/Python toolchain, API access to Facebook Ads Library (if using live ingestion), and any LLM/embedding provider keys you plan to connect.

Clone and run (Docker Compose example)

git clone https://github.com/trypeggy/facebook-ads-library-mcp.git
cd facebook-ads-library-mcp
# start with docker-compose (builds and runs server + optional worker)
docker-compose up --build -d

Environment variables (example .env)

# Required to fetch Ads Library data (if you will ingest live)
FB_ADS_API_KEY=your_facebook_ads_library_api_key

# Optional: embedding or LLM provider for semantic features
EMBEDDING_API_KEY=your_embedding_provider_key
LLM_API_KEY=your_llm_provider_key

# Server
PORT=8080
CACHE_TTL_SECONDS=3600

Local development (npm/node example)

# If the project uses Node
cd facebook-ads-library-mcp
npm install
npm run dev
# or
NODE_ENV=production npm start

If the repository uses Python, replace the above commands with:

python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
python server.py

Check health

curl http://localhost:8080/health
# expected: {"status":"ok","version":"1.0.0"}

Available Tools / Resources

The server exposes several MCP tools and HTTP endpoints that are useful for research and automation:

  • /search — semantic and faceted search over ad copy and metadata
  • /compare — take two or more ad IDs and receive a structured comparison
  • /creative-test — extract creative components to assist A/B testing
  • /metrics — aggregate metrics like spend, impressions, and active date ranges
  • /ingest — (admin) trigger an ingestion or reindex of Ads Library data
  • /health — basic server health and readiness checks

Example API request (search):

curl -X POST http://localhost:8080/search \
  -H "Content-Type: application/json" \
  -d '{"query":"voter registration messaging", "filters":{"country":"US","date_from":"2024-01-01"}}'

Example simplified response structure:

{
  "results":[
    {"ad_id":"123","advertiser":"Org A","text":"Register to vote...", "impressions":12000},
    {"ad_id":"456","advertiser":"Org B","text":"Join our campaign...", "impressions":5400}
  ],
  "total":2
}

Use Cases

  • Rapid messaging research: Query large sets of active and historical ads for a theme (e.g., “climate policy”) and extract common headlines, CTAs, and framing to inform copywriting.
  • Creative comparisons: Use /compare to automatically highlight differences between two creatives (text, image presence, CTA) and produce a short summary for A/B test hypotheses.
  • Competitor tracking: Monitor top-performing ads for a set of competitors and aggregate spend/impression trends over time to detect strategy shifts.
  • Regulatory and compliance checks: Search for ads mentioning specific policy terms, export results with metadata, and keep an audit trail of ad content and timing.
  • Agent-enabled research: Connect the MCP server to an LLM-based agent to ask natural-language questions (e.g., “Which ads mention misinformation in Florida in Q1 2024?”) and receive concise, context-rich answers drawn from indexed ad records.

Remarks and Next Steps

  • For production use, secure API keys and enable rate limiting and caching. Configure the ingestion cadence to balance freshness and API usage costs.
  • The repo includes sample ingestion scripts and a minimal MCP toolset—refer to the code in the GitHub link for implementation details and contribution guidelines: https://github.com/trypeggy/facebook-ads-library-mcp.
Tags:communicationsearch