MetaAdsCollector

Collect ads from the Meta Ad Library using a command-line tool, Python, or an AI assistant through MCP. No Meta API key is required.

Installation

Install Python first. The collector requires Python 3.9+; MCP requires Python 3.10+. On Windows, enable Add Python to PATH during installation. Open PowerShell on Windows or Terminal on macOS/Linux.

Create a separate environment for this project:

Windows (PowerShell):

py -m venv .venv
.venv\Scripts\Activate.ps1

If PowerShell blocks activation, use .venv\Scripts\python.exe wherever the commands below say python; use the module form shown below for the MCP server.

macOS/Linux:

python3 -m venv .venv
source .venv/bin/activate

Choose the installation you need:

The MCP extra includes the collector and adds its optional server dependencies. You do not need to install both commands. MCP is available in version 1.6.0 or newer.

If you already cloned this repository, run python -m pip install -e "." from its root for the collector, or python -m pip install -e ".[mcp]" for MCP. Installing from a checkout uses that checkout's version; installing by package name uses a published PyPI release.

MCP quick start

MCP connects an AI assistant to tools it can use. Install the MCP extra above, then:

1. Open your AI application's MCP server settings. It must support local stdio servers. Applications differ in where this setting lives; some accept JSON, while others ask for a command and arguments.
2. Add the following server configuration:

{
  "mcpServers": {
    "meta-ads": {
      "command": "meta-ads-mcp",
      "args": []
    }
  }
}

3. Replace meta-ads-mcp with the absolute path to the executable in your environment: .venv/Scripts/meta-ads-mcp.exe on Windows or .venv/bin/meta-ads-mcp on macOS/Linux. An absolute path lets the AI application find the server even when your terminal environment is not activated.
4. Restart or reconnect the AI application. Ask: "Use the Meta Ads tools to find up to 10 active Nike ads in the US. Summarize the creatives and export the results to CSV."

The AI client starts the server automatically. You do not need to run a second server in your terminal. To check installation yourself:

python -m meta_ads_collector_mcp discover

This prints capabilities without collecting ads. If your client cannot use the executable directly, set its command to the absolute path of your environment's Python and its arguments to ["-m", "meta_ads_collector_mcp"].

What you can ask the assistant to do:

Results and job progress are saved locally in ~/.meta-ads-collector-mcp. Later inspection and export reuse the saved collection. Interrupted jobs can resume; Meta may invalidate an old cursor, requiring a fresh search with deduplication. "Newly observed" means new to that monitor, not necessarily newly launched.

For monitoring or jobs that should keep running after the AI client closes, open a separate terminal in the same environment and run:

python -m meta_ads_collector_mcp worker

Keep the terminal open. The server and worker must use the same data directory; both use the default above unless you pass --data-dir. You can ask the assistant to configure a proxy using a private environment-variable or file reference. Keep actual credentials out of chat, committed files, and shared client configurations. See the full MCP guide for configuration, budgets, and recovery details.

Collector basics

Collect ads without writing code. Copy this command into your terminal:

python -m meta_ads_collector -q "nike" -c US -n 10 -o ads.csv

It saves up to 10 matching active ads to ads.csv in your current folder. Open that file in Excel, Numbers, or another spreadsheet app. Change nike to your search term, US to another country code such as GB or EG, and 10 to your result limit. Change the output filename to ads.json or ads.jsonl for those formats.

Use it in Python. Save this as collect_ads.py and run python collect_ads.py:

from meta_ads_collector import MetaAdsCollector

with MetaAdsCollector() as collector:
    for ad in collector.search(query="nike", country="US", max_results=5):
        advertiser = ad.page.name if ad.page is not None else "Unknown page"
        print(ad.id, advertiser)

The library also supports pagination, async collection, filters, exports, media downloads, and HTTP/HTTPS/SOCKS proxies. Fields supplied by Meta are preserved in ad.api_fields; individual ads may lack spend, impressions, media, or audience details. JSON/JSONL exports retain api_fields; CSV includes it as a JSON column. Pass --enrich (or call collector.enrich_ad(ad)) to add the Ad Library "See ad details" payload: EU/UK transparency audience and reach, US political demographics, payer/beneficiary data and advertiser page details.

MetaAdsCollector uses internal Meta endpoints. Meta can change or restrict access, so network, proxy, verification, or rate-limit failures can occur. An empty query result does not establish that no matching ads exist. Keep result limits small when starting, and check errors before treating a collection as complete.

Visit the documentation website for the full collector guides and API reference, or the issue tracker to report a problem.