all-about-ads-mcp

An MCP (Model Context Protocol) server that gives AI agents live, structured ad intelligence across Facebook, Google, and Instagram — data that no base model can produce from training alone.

Powered by Apify actors. Works with any MCP-compatible client: Cursor, Claude, etc.

Demo

Related MCP server: ArmaVita Meta Ads MCP

Why this MCP exists

A base AI model can tell you what lululemon's general marketing strategy looks like — based on articles it was trained on, months ago. It cannot tell you:

• What ad copy is running right now on Facebook or Google

• Whether a competitor started or stopped a campaign last week

• Which countries a brand is targeting today

• How long a specific ad has been active (days_active)

This MCP fetches live truth, not remembered facts.

Platform coverage

How results are handled

Tools run in parallel — an AI agent can fire off Facebook, Google, and Instagram scrapers simultaneously rather than waiting for each one to finish before starting the next. That's why a full multi-platform research session completes in minutes, not hours.

Scraper runs take 30 seconds to a few minutes. Raw payloads can be enormous, so the architecture keeps the AI's context window safe:

Full results are never sent to the model in one shot. The preview gives enough signal; read_saved_results provides paginated, filterable access to the rest.

Use cases

1. Competitive intelligence before a pitch

An agency pitching a new client can build a full picture in minutes instead of days:

No base AI can give you what's actually running today across all three platforms simultaneously.

2. Evergreen ad detection

The days_active field in Google Ads shows exactly how long each creative has been live. An ad running for 1,000+ days is a proven, high-converting asset. Use this to find what competitors refuse to turn off:

3. Market entry gap analysis

Before entering a new market, check who's already advertising there:

A base AI would guess based on 2023 data. This gives real-time confirmation.

4. PR crisis correlation

When a brand faces a scandal, do they pull ads or keep running? Track it in real time:

5. Ad creative pattern analysis at scale

Pull 100 ads from a fast-growing brand and let the AI find the formula:

This requires structured bulk data to reason over — not 3 examples recalled from training.

6. Political ad transparency

Track political advertising by region with verifiable, primary-source data:

7. Full brand research loop

The complete workflow an AI agent can run autonomously:

Project layout

all-about-ads-mcp/
├── src/
│   ├── server.py      # FastMCP server instance
│   ├── tools.py       # 6 MCP tool definitions
│   ├── storage.py     # Result persistence + per-platform summarisers
│   └── resources.py   # ads://about resource
├── main.py            # Entry point (stdio transport)
├── pyproject.toml
└── uv.lock

Setup

1. Install dependencies:

uv sync

2. Configure your Apify API token:

cp .env.example .env
# edit .env and set APIFY_API_TOKEN=<your token>

Get a free token at apify.com — the free tier covers light research use.

Connecting MCP clients

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (Mac) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "all-about-ads": {
      "command": "uv",
      "args": ["run", "--directory", "/absolute/path/to/all-about-ads-mcp", "main.py"],
      "env": {
        "APIFY_API_TOKEN": "your_apify_token_here"
      }
    }
  }
}

Cursor

Add to ~/.cursor/mcp.json (global) or .cursor/mcp.json (per-project):

{
  "mcpServers": {
    "all-about-ads": {
      "command": "uv",
      "args": ["run", "--directory", "/absolute/path/to/all-about-ads-mcp", "main.py"],
      "env": {
        "APIFY_API_TOKEN": "your_apify_token_here"
      }
    }
  }
}

Windsurf

Edit ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "all-about-ads": {
      "command": "uv",
      "args": ["run", "--directory", "/absolute/path/to/all-about-ads-mcp", "main.py"],
      "env": {
        "APIFY_API_TOKEN": "your_apify_token_here"
      }
    }
  }
}

VS Code (with GitHub Copilot)

Add to your .vscode/mcp.json in the workspace root:

{
  "servers": {
    "all-about-ads": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "--directory", "/absolute/path/to/all-about-ads-mcp", "main.py"],
      "env": {
        "APIFY_API_TOKEN": "your_apify_token_here"
      }
    }
  }
}

Docker (any client)

If you prefer not to install Python/uv locally, run the pre-built container. The container communicates over stdio just like the native install:

Build the image:

docker build -t all-about-ads-mcp .

Claude Desktop / Cursor / Windsurf config:

{
  "mcpServers": {
    "all-about-ads": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "-e", "APIFY_API_TOKEN", "all-about-ads-mcp"],
      "env": {
        "APIFY_API_TOKEN": "your_apify_token_here"
      }
    }
  }
}

-i is required (stdin must stay open for stdio transport). Do not use -t (no TTY needed).

Publishing to MCP directories

Smithery

Smithery reads the smithery.yaml in this repo automatically. To publish:

1. Push this repo to GitHub

2. Go to smithery.ai → Submit a server → paste your GitHub URL

3. Smithery reads smithery.yaml and handles deployment — users configure their APIFY_API_TOKEN in the Smithery UI

Glama

Glama indexes public GitHub repos. To publish:

1. Push this repo to GitHub (public)

2. Go to glama.ai/mcp/servers → Add Server → paste your GitHub URL

mcpservers.org

mcpservers.org is a community directory. To submit:

1. Push to GitHub

2. Go to mcpservers.org/submit and fill in the form

Tools

search_facebook_ads

Search the Facebook (Meta) Ads Library by keyword or brand name.

Returns: file_path, result_count, queries, ads (compact preview)

search_google_ads

Search the Google Ads Transparency Center — covers Search, Display, YouTube, and Shopping ads.

Returns: file_path, result_count, advertisers, ads (compact preview with days_active, headline, format, regions, destination_url)

search_instagram_profiles

Fetch public Instagram profile data including follower counts, bio, and recent posts.

Returns: file_path, result_count, profiles (compact preview with followers, bio, verified status)

search_google

Search Google for organic results — use for brand research, news, and context about ads you've discovered.

Returns: file_path, result_count (individual URLs), queries, results (compact preview)

list_saved_results

List all previously saved result files with path, size, item count, tool name, and queries. No Apify call — instant.

read_saved_results

Read a slice of items from a saved file — fast access without re-running scrapers.

Resources

• ads://about — full parameter reference for all tools, readable by the AI agent at session start.