# Facebook Ads Library MCP Server

[![License: MIT](https://img.shields.io/badge/License-MIT-1f1f1f?style=flat-square)](LICENSE)

Search the Meta / Facebook ads library from your AI assistant: find the ads a brand or a
competitor is running, see the advertisers behind them, pull the creatives and the media,
and rank what is scaling — in one conversation, without opening a dashboard.

This is a scenario adapter for the hosted [Spytrend MCP server](https://spytrend.com/mcp/?utm_source=github-facebook-ads-library-mcp&utm_medium=repo&utm_campaign=mcp-launch).
Spytrend adds 170M+ new Meta ads a month across placements, groups them by advertiser and
destination, and sorts them into 33 business categories. This adapter exposes the Meta part of
that corpus with Facebook-specific tool names, so an assistant never has to guess which source
it is querying.

## Example prompts

> Which ads is **nike.com** running right now, and since when? Show the longest-running ones first.

> Find Facebook ads mentioning "collagen gummies" in Germany in the last 30 days. Group them by advertiser.

> Who are the biggest advertisers in the pet-supplies category in the United States this month?

> Take this ad id and find related ads from the same page or the same landing domain.

> Download the video and the image variants for these three ad ids.

![Example answer](assets/screenshot.png)

## Connect

### Option A — hosted server, nothing to install (recommended)

**Endpoint**

```text
https://mcp.spytrend.com/mcp
```

**Sign-in:** your Spytrend account, in the browser. No API key, no token to paste. Works on
every plan, including the free one.

1. Open your client's connector settings.
2. Add a remote MCP server and give it the URL above.
3. Sign in when the browser window opens, and start asking.

Per-client walkthroughs (Claude, ChatGPT, Cursor, Codex, VS Code):
[Spytrend/spytrend-mcp → docs/quickstart.md](https://github.com/Spytrend/spytrend-mcp/blob/main/docs/quickstart.md).

### Option B — this adapter (Facebook-only tool names)

Requires Node 20+ (20.18.1 or newer). The adapter runs locally over stdio and forwards its tool calls to the hosted
server above; the first call opens the same Spytrend sign-in in your browser. The sign-in token is kept on your
machine by [mcp-remote](https://github.com/geelen/mcp-remote) in `~/.mcp-auth` (set
`MCP_REMOTE_CONFIG_DIR` to move it); delete that folder to sign out. Nothing goes into this
repository or your client config.

Claude Desktop, Cursor, or any stdio client:

```json
{
  "mcpServers": {
    "facebook-ads-library": {
      "command": "npx",
      "args": ["-y", "github:Spytrend/facebook-ads-library-mcp"]
    }
  }
}
```

Claude Code:

```bash
claude mcp add facebook-ads-library -- npx -y github:Spytrend/facebook-ads-library-mcp
```

## Tools (8)

| Tool | What it does |
|---|---|
| `search_facebook_ads` | Search Meta ads by text, country, category, advertiser or landing domain |
| `get_facebook_ad` | Open one ad: copy, destination, run dates, creative |
| `search_facebook_advertisers` | Find advertiser pages by name or filters |
| `get_facebook_advertiser` | One advertiser page: volume, countries, active ads |
| `get_facebook_ads_analytics` | Aggregates over a filtered ad selection (Pro plan or higher) |
| `find_similar_facebook_ads` | Ads related by page or landing domain |
| `get_facebook_ad_media` | Download images and videos for ad ids |
| `get_usage` | Your plan and remaining quota (free) |

Every tool maps to one tool of the hosted server, with the source pinned to Meta. Pricing is
the server's: every delivered row costs one Spytrend token; opening an ad with media costs one
token (fifty for multi-language uploads). Details:
[spytrend.com/mcp](https://spytrend.com/mcp/?utm_source=github-facebook-ads-library-mcp&utm_medium=repo&utm_campaign=mcp-launch).

## What this is and is not

- It queries Spytrend's own database. It does not scrape Facebook, does not ship Meta code and
  does not bypass any platform access control.
- Meta, Facebook and Instagram are trademarks of Meta Platforms, Inc. This project is not
  affiliated with, endorsed by or sponsored by Meta Platforms, Inc.
- Results are the hosted server's answers in this adapter's names: tool and parameter names in errors
  and parameter notes are this adapter's, and fields the hosted server keeps for its own use are
  left out. What advertisers published (ad copy, names, links) is passed on as is.
- For the full server with all 22 tools, six ready-made research workflows and TikTok coverage,
  see the canonical repository: [Spytrend/spytrend-mcp](https://github.com/Spytrend/spytrend-mcp).

## Support

Questions about connecting, access or your account: [spytrend.com/contact](https://spytrend.com/contact/?utm_source=github-facebook-ads-library-mcp&utm_medium=repo&utm_campaign=mcp-launch).
Something wrong in this repository: open an issue. Security reports go through the route
described in the canonical repository's [SECURITY.md](https://github.com/Spytrend/spytrend-mcp/blob/main/SECURITY.md),
never through issues.

## License

MIT — see [LICENSE](LICENSE). The licence covers this adapter and its documentation. The
server itself is part of the Spytrend platform.