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

# Run installer
./install.sh  # macOS/Linux
# OR
install.bat   # Windows

# Clone repository
git clone https://github.com/proxy-intell/facebook-ads-library-mcp.git
cd facebook-ads-library-mcp

# Create virtual environment
python3 -m venv venv
./venv/bin/pip install -r requirements.txt

# Configure environment
cp .env.template .env
# Edit .env and add:
# SCRAPECREATORS_API_KEY=your_key_here
# GEMINI_API_KEY=your_gemini_key_here (optional, for video analysis)

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

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

SCRAPECREATORS_API_KEY=your_scrapecreators_key
GEMINI_API_KEY=your_gemini_key

# Single brand
{
  "brand_name": "Nike"
}

# Multiple brands (batch)
{
  "brand_name": ["Nike", "Adidas", "Under Armour"]
}

{
  "Nike": "123456789",
  "Adidas": "987654321",
  "Under Armour": "456789123"
}

# Single platform
{
  "platform_id": "123456789"
}

# Multiple platforms (batch)
{
  "platform_id": ["123456789", "987654321"]
}

{
  "123456789": {
    "ads": [
      {
        "id": "ad_id_123",
        "ad_creative_body": "Ad text content",
        "ad_snapshot_url": "https://...",
        "images": ["https://image1.jpg"],
        "videos": ["https://video1.mp4"]
      }
    ]
  }
}

{
  "image_url": "https://example.com/ad-image.jpg"
}

{
  "video_url": "https://example.com/ad-video.mp4"
}

{
  "video_urls": [
    "https://example.com/video1.mp4",
    "https://example.com/video2.mp4",
    "https://example.com/video3.mp4"
  ]
}

{
  "total_cached_items": 42,
  "images": 30,
  "videos": 12,
  "total_size_mb": 156.7,
  "oldest_cache": "2025-01-15T10:30:00Z"
}

{
  "brand": "Nike",          # Optional
  "colors": ["red", "blue"], # Optional
  "has_people": true,       # Optional
  "media_type": "image"     # Optional: "image" or "video"
}

{
  "days_old": 30  # Remove cache older than 30 days
}

# Agent workflow:
# 1. Get platform ID
platform_id_result = get_meta_platform_id({"brand_name": "Nike"})
platform_id = platform_id_result["Nike"]

# 2. Get ads
ads_result = get_meta_ads({"platform_id": platform_id})
ads = ads_result[platform_id]["ads"]

# 3. Analyze first video ad
video_url = ads[0]["videos"][0]
video_analysis = analyze_ad_video({"video_url": video_url})

# Agent workflow for batch processing:
brands = ["Nike", "Adidas", "Under Armour", "Puma"]

# 1. Get all platform IDs at once (batch)
platform_ids = get_meta_platform_id({"brand_name": brands})

# 2. Get all ads at once (batch)
all_platform_ids = list(platform_ids.values())
ads_data = get_meta_ads({"platform_id": all_platform_ids})

# 3. Collect video URLs
video_urls = []
for platform_id, data in ads_data.items():
    for ad in data["ads"]:
        if ad.get("videos"):
            video_urls.extend(ad["videos"][:2])  # First 2 videos per brand

# 4. Batch analyze all videos (huge token savings)
video_analyses = analyze_ad_videos_batch({"video_urls": video_urls})

# Find all Nike ads with people in red/white colors
cached_results = search_cached_media({
    "brand": "Nike",
    "colors": ["red", "white"],
    "has_people": True,
    "media_type": "image"
})

# Get fresh data and analyze
for result in cached_results:
    print(f"Ad ID: {result['ad_id']}")
    print(f"Analysis: {result['analysis']}")

import json
from mcp import get_meta_platform_id, get_meta_ads

# Get Nike's platform ID
platform_data = get_meta_platform_id({"brand_name": "Nike"})
nike_id = platform_data["Nike"]

# Get their current ads
ads = get_meta_ads({"platform_id": nike_id})
nike_ads = ads[nike_id]["ads"]

print(f"Nike is running {len(nike_ads)} ads")
for ad in nike_ads:
    print(f"- {ad['ad_creative_body'][:100]}...")

from mcp import get_meta_platform_id, get_meta_ads, analyze_ad_videos_batch

# Define competitors
brands = ["Coca-Cola", "Pepsi", "Dr Pepper"]

# Get platform IDs (batch)
platform_ids = get_meta_platform_id({"brand_name": brands})

# Get all ads (batch)
all_ids = list(platform_ids.values())
all_ads = get_meta_ads({"platform_id": all_ids})

# Collect video URLs
video_map = {}  # Maps video URL to brand
for brand, pid in platform_ids.items():
    for ad in all_ads[pid]["ads"]:
        if ad.get("videos"):
            for video_url in ad["videos"][:1]:  # First video only
                video_map[video_url] = brand

# Batch analyze
video_urls = list(video_map.keys())
analyses = analyze_ad_videos_batch({"video_urls": video_urls})

# Map results back to brands
brand_strategies = {}
for i, video_url in enumerate(video_urls):
    brand = video_map[video_url]
    if brand not in brand_strategies:
        brand_strategies[brand] = []
    brand_strategies[brand].append(analyses[i])

# Print comparison
for brand, strategies in brand_strategies.items():
    print(f"\n{brand} Video Strategy:")
    print(json.dumps(strategies[0], indent=2))

from mcp import get_meta_ads, analyze_ad_image

# Get ads for a platform
ads = get_meta_ads({"platform_id": "123456789"})

# Analyze images
for ad in ads["123456789"]["ads"]:
    if ad.get("images"):
        image_url = ad["images"][0]
        analysis = analyze_ad_image({"image_url": image_url})
        
        # Check if red color is dominant
        colors = analysis.get("dominant_colors", [])
        if any("red" in c.lower() for c in colors):
            print(f"Red-dominant ad found: {ad['id']}")
            print(f"Colors: {colors}")
            print(f"Has people: {analysis.get('has_people', False)}")

# Required for ad retrieval
SCRAPECREATORS_API_KEY=your_api_key_here

# Optional for video analysis
GEMINI_API_KEY=your_gemini_api_key_here

# Optional cache settings (defaults shown)
CACHE_DIR=./cache
MAX_CACHE_SIZE_MB=1000
CACHE_EXPIRY_DAYS=30

cd facebook-ads-library-mcp
./venv/bin/pip install -r requirements.txt --upgrade

# Clean old cache (older than 7 days)
cleanup_media_cache({"days_old": 7})

# Or manually remove cache directory
rm -rf ./cache

from langchain.tools import Tool
from mcp import get_meta_platform_id, get_meta_ads

tools = [
    Tool(
        name="get_facebook_ads",
        func=lambda brand: get_meta_ads({
            "platform_id": get_meta_platform_id({"brand_name": brand})[brand]
        }),
        description="Get current Facebook ads for a brand"
    )
]

#!/usr/bin/env python3
import sys
import json
from pathlib import Path

# Add MCP server to path
sys.path.insert(0, str(Path(__file__).parent / "facebook-ads-library-mcp"))

from mcp_server import get_meta_platform_id, get_meta_ads

def main():
    brand = input("Enter brand name: ")
    platform_id = get_meta_platform_id({"brand_name": brand})[brand]
    ads = get_meta_ads({"platform_id": platform_id})
    print(json.dumps(ads, indent=2))

if __name__ == "__main__":
    main()