Facebook Ad Library MCP Server & CLI

What is the Facebook Ad Library MCP server & CLI?

The Facebook Ad Library MCP server & CLI is a free, open source program that lets AI agents research the ads any brand is running on Facebook and Instagram for you, in 2 ways. The MCP server is what an AI app like Claude, Codex or Cursor connects to, through MCP (Model Context Protocol), the open standard AI apps use to call outside tools.

You ask in plain language. Your AI picks the right tool, and the server makes the call to Meta's public Ad Library, the way a browser reads it.

The CLI is the same program as commands. facebook-ad-library-cli search-ads --query "cold plunge" --country US runs the same code your AI runs when you ask what a market is advertising, whether an agent like Claude Code runs it or you do.

What can you ask it?

Once it's set up, you ask the way you'd ask an assistant. These are real prompts it handles:

Try asking
What ads is this brand running right now, and which has been live longest?
Show me every hook this competitor is testing this month, grouped by angle.
Compare 2 competitors: who runs more creative, and who refreshes it faster?
Find advertisers running cold plunge ads in the UK, ranked by ad count.
What changed for this advertiser since last week?
This ad has run for 8 months. Read the copy and tell me why it works.

The fifth one shows why this is useful. The Ad Library only shows what's running now, and the server keeps its own snapshot, so it can tell you what started and what stopped.

How to install the Facebook Ad Library MCP server

Pick your app in the box at the top of this page. Each one is a single command or a pasted block, with no account and no key.

Set up the Facebook Ad Library

There's no account and no key. The only setup is the browser the free backend drives.

A search on the free backend takes 30 to 60 seconds, because it opens the Ad Library and scrolls it like a person would. Meta slows you down if you run a lot of searches in a row, so wait a few minutes when results come back empty.

Optional: EU spend and reach

Meta's official Ad Library API publishes spend, impressions and demographics for ads delivered in the EU and for political ads anywhere. It's free: create an app at developers.facebook.com, generate an access token and set it as META_ADS_ARCHIVE_TOKEN. get_eu_transparency then returns data, and everything else works without it.

Check that it works

Run the doctor. It launches the browser, runs a real search and tells you whether ads came back.

npx -y @thenavidm/facebook-ad-library-mcp-cli doctor

If Chromium won't launch, run npx playwright install chromium. If Meta served a captcha, wait a few minutes and try again.

Use the Facebook Ad Library CLI

The CLI is the same 9 tools as commands. AI agents that run commands, like Claude Code, Codex and OpenCode, use it on their own, and you can type the same commands in a terminal or a script.

Every tool name becomes a command with dashes, so search_ads runs as facebook-ad-library-cli search-ads.

npm install -g @thenavidm/facebook-ad-library-mcp-cli
facebook-ad-library-cli
facebook-ad-library-cli search-ads --query "cold plunge" --country GB --limit 10
facebook-ad-library-cli list-advertisers --query "Ridge"
facebook-ad-library-cli diff-advertiser --page-id 112577918783959

The bare facebook-ad-library-cli lists every command, and facebook-ad-library-cli <command> --help shows what a command takes. Nothing asks for a confirm check, because nothing here writes.

These flags work on every command:

A script can branch on the exit code:

MCP server or CLI: which one?

Both are the same program with the same 9 tools. The difference is when your AI pays for them, in the tokens it reads.

An app that loads every tool up front sends the full list with every message, whether you mention Facebook Ad Library or not. Claude Code doesn't by default: its tool search sends only the tool names and the server's instructions, and loads a tool's full definition when your AI reaches for it.

The CLI costs nothing until Facebook Ad Library comes up. Then your agent reads its skill file once and runs the commands it needs. With the skill added, Claude Code also lists its one-line description with every message, about 170 tokens.

When the whole conversation is about Facebook Ad Library, the gap closes. Then the MCP server is the better experience, because you ask in plain language and your AI never has to look up a command.

How to spend less

In Claude Code, leave tool search on, which it is unless you've set ENABLE_TOOL_SEARCH=false.

Turn the server off when you aren't researching ads, with your AI app's own switch.

Or install the CLI and connect the server later, on the days it earns its place. Every tool stays in reach, and the standing cost drops to nothing.

Every number here was measured on September 27, 2026 in Claude Code 2.1.257 with Claude Opus 5. It's the same one-line prompt with and without the server connected, once with tool search off so every tool loads, and once with Claude Code's default. The skill was measured the same way, and other apps and models count tokens a little differently.

What you get for every ad

The Ad Library is a web app, and Meta hands it every ad as structured data. The server reads that data rather than the page's text, so nothing is lost on the way.

What the Ad Library can't tell you

No performance data exists. Conversions, revenue, cost per acquisition and return on ad spend aren't public for another advertiser, from any source.

What you can read is how long an ad has run. An ad live for 6 months is probably working, because advertisers turn off ads that lose money, but that's a guess worth testing, not a measurement.

Spend and reach are usually empty. Meta publishes them only for ads delivered in the EU and for political ads, so an empty value on a US store's ad is the right answer.

Creative links expire, because Meta's media links are short-lived. Download what you want to keep when you find it.

Every Facebook Ad Library tool

All 9 tools, grouped the way the repo groups them. Every one only reads: the server can't post, can't spend and can't reach an ad account.

Searching ads

Seeing an ad

Tracking changes

EU spend and reach

Status

Is the Facebook Ad Library MCP server safe?

There's nothing to undo, because nothing here writes. Every tool reads Meta's public archive, so there's no read-only setting to turn on.

The one thing it stores is the snapshot diff_advertiser compares against, on your own computer.

Your data

There's no server of ours in between. The free backend reads the Ad Library from your own computer, the same page anyone can open without signing in.

diff_advertiser keeps its snapshots in your app data folder, or wherever FBADS_STORE_DIR points. If you set a provider backend, your searches go to that provider instead, and whatever your AI reads goes to its own model provider, like anything you paste into a chat.

Facebook Ad Library MCP server settings

Every setting is optional, as an environment variable in your app's config. The free backend needs none of them.

Troubleshooting

Run the doctor first. It names the step that failed and the fix.

If the server doesn't show up in your app at all, run the command your app runs, in a terminal, and read the error.