Facebook Ad Library MCP Server & CLI
A free, open source Facebook Ad Library MCP server and CLI that lets Claude Code, Codex, Cursor and other AI agents research the ads any brand runs on Facebook and Instagram.
0.0(0 ratings)- 1
Add it with a single command in a terminal.
claude mcp add facebook-ad-library \
-- npx -y @thenavidm/facebook-ad-library-mcp-cli@latest - 2
In Claude Code, type /mcp. Facebook Ad Library should show as connected.
/mcp
- 1
Add it with a single command in a terminal.
claude mcp add facebook-ad-library -- npx -y @thenavidm/facebook-ad-library-mcp-cli@latest - 2
In Claude Code, type /mcp. Facebook Ad Library should show as connected.
/mcp
- 1
Add it with a single command in a terminal.
claude mcp add facebook-ad-library \
-- npx -y @thenavidm/facebook-ad-library-mcp-cli@latest - 2
In Claude Code, type /mcp. Facebook Ad Library should show as connected.
/mcp
- 1Download the extension
Download the Claude Desktop extension.
- 2
Double-click it, and Claude Desktop installs it.
- 1
Add it with a single command in a terminal.
codex mcp add facebook-ad-library \
-- npx -y @thenavidm/facebook-ad-library-mcp-cli@latest - 2
Check that Codex lists it.
codex mcp list
- 1
Add it with a single command in a terminal.
codex mcp add facebook-ad-library -- npx -y @thenavidm/facebook-ad-library-mcp-cli@latest - 2
Check that Codex lists it.
codex mcp list
- 1
Add it with a single command in a terminal.
codex mcp add facebook-ad-library \
-- npx -y @thenavidm/facebook-ad-library-mcp-cli@latest - 2
Check that Codex lists it.
codex mcp list
- 1
Open Cursor's settings, go to the MCP tab, and click Add new global MCP server.
- 2
Add the server.
{
"mcpServers": {
"facebook-ad-library": {
"command": "npx",
"args": ["-y", "@thenavidm/facebook-ad-library-mcp-cli@latest"]
}
}
} - 3
Open the MCP tab again. It should show 9 tools.
- 1
Open the Command Palette and run MCP: Open User Configuration.
- 2
Add the server to that mcp.json.
If the file already has servers, add only this one inside servers.
{
"servers": {
"facebook-ad-library": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@thenavidm/facebook-ad-library-mcp-cli@latest"]
}
}
}
- 1
Add it with a single command in a terminal.
copilot mcp add facebook-ad-library \
-- npx -y @thenavidm/facebook-ad-library-mcp-cli@latest - 2
Check that Copilot CLI has it.
copilot mcp get facebook-ad-library
- 1
Add it with a single command in a terminal.
copilot mcp add facebook-ad-library -- npx -y @thenavidm/facebook-ad-library-mcp-cli@latest - 2
Check that Copilot CLI has it.
copilot mcp get facebook-ad-library
- 1
Add it with a single command in a terminal.
copilot mcp add facebook-ad-library \
-- npx -y @thenavidm/facebook-ad-library-mcp-cli@latest - 2
Check that Copilot CLI has it.
copilot mcp get facebook-ad-library
- 1
Open your Gemini CLI settings.
~/.gemini/settings.json - 2
Add the server to settings.json.
If the file already has servers, add only this one inside mcpServers.
{
"mcpServers": {
"facebook-ad-library": {
"command": "npx",
"args": ["-y", "@thenavidm/facebook-ad-library-mcp-cli@latest"]
}
}
} - 3
Restart Gemini CLI and type /mcp to check it.
/mcp
- 1
Open your Gemini CLI settings.
%USERPROFILE%\.gemini\settings.json - 2
Add the server to settings.json.
If the file already has servers, add only this one inside mcpServers.
{
"mcpServers": {
"facebook-ad-library": {
"command": "npx",
"args": ["-y", "@thenavidm/facebook-ad-library-mcp-cli@latest"]
}
}
} - 3
Restart Gemini CLI and type /mcp to check it.
/mcp
- 1
Open your Gemini CLI settings.
~/.gemini/settings.json - 2
Add the server to settings.json.
If the file already has servers, add only this one inside mcpServers.
{
"mcpServers": {
"facebook-ad-library": {
"command": "npx",
"args": ["-y", "@thenavidm/facebook-ad-library-mcp-cli@latest"]
}
}
} - 3
Restart Gemini CLI and type /mcp to check it.
/mcp
- 1
Open your OpenCode config.
~/.config/opencode/opencode.json - 2
Add the server under mcp.
If the file already has servers, add only this one inside mcp.
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"facebook-ad-library": {
"type": "local",
"command": ["npx", "-y", "@thenavidm/facebook-ad-library-mcp-cli@latest"],
"enabled": true
}
}
} - 3
Restart OpenCode.
- 1
Open your OpenCode config.
%USERPROFILE%\.config\opencode\opencode.json - 2
Add the server under mcp.
If the file already has servers, add only this one inside mcp.
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"facebook-ad-library": {
"type": "local",
"command": ["npx", "-y", "@thenavidm/facebook-ad-library-mcp-cli@latest"],
"enabled": true
}
}
} - 3
Restart OpenCode.
- 1
Open your OpenCode config.
~/.config/opencode/opencode.json - 2
Add the server under mcp.
If the file already has servers, add only this one inside mcp.
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"facebook-ad-library": {
"type": "local",
"command": ["npx", "-y", "@thenavidm/facebook-ad-library-mcp-cli@latest"],
"enabled": true
}
}
} - 3
Restart OpenCode.
- 1
Add it with a single command in a terminal.
openclaw mcp add facebook-ad-library \
--command npx \
--arg -y \
--arg @thenavidm/facebook-ad-library-mcp-cli@latest - 2
Check that it starts and lists its tools.
openclaw mcp doctor facebook-ad-library --probe
- 1
Add it with a single command in a terminal.
openclaw mcp add facebook-ad-library --command npx --arg -y --arg @thenavidm/facebook-ad-library-mcp-cli@latest - 2
Check that it starts and lists its tools.
openclaw mcp doctor facebook-ad-library --probe
- 1
Add it with a single command in a terminal.
openclaw mcp add facebook-ad-library \
--command npx \
--arg -y \
--arg @thenavidm/facebook-ad-library-mcp-cli@latest - 2
Check that it starts and lists its tools.
openclaw mcp doctor facebook-ad-library --probe
- 1
In the agent panel, click the … menu, then MCP Servers, Manage MCP Servers and View raw config.
- 2
Add the server to mcp_config.json.
If the file already has servers, add only this one inside mcpServers.
{
"mcpServers": {
"facebook-ad-library": {
"command": "npx",
"args": ["-y", "@thenavidm/facebook-ad-library-mcp-cli@latest"]
}
}
}
- 1
Open your Hermes config.
~/.hermes/config.yaml - 2
Add the server under mcp_servers.
If the file already has mcp_servers, add only this one under it.
mcp_servers:
facebook-ad-library:
command: "npx"
args: ["-y", "@thenavidm/facebook-ad-library-mcp-cli@latest"]
- 1
Open your Hermes config.
%USERPROFILE%\.hermes\config.yaml - 2
Add the server under mcp_servers.
If the file already has mcp_servers, add only this one under it.
mcp_servers:
facebook-ad-library:
command: "npx"
args: ["-y", "@thenavidm/facebook-ad-library-mcp-cli@latest"]
- 1
Open your Hermes config.
~/.hermes/config.yaml - 2
Add the server under mcp_servers.
If the file already has mcp_servers, add only this one under it.
mcp_servers:
facebook-ad-library:
command: "npx"
args: ["-y", "@thenavidm/facebook-ad-library-mcp-cli@latest"]
- 1
Install the CLI. It needs Node 22 or newer.
npm install -g @thenavidm/facebook-ad-library-mcp-cli@latest - 2
Give Claude Code the skill, so it knows every command.
The skill is the SKILL.md in the package. It tells Claude Code what each command does and which ones ask first.
mkdir -p ~/.claude/skills/facebook-ad-library
cp "$(npm root -g)/@thenavidm/facebook-ad-library-mcp-cli/SKILL.md" ~/.claude/skills/facebook-ad-library/ - 3
Check your setup.
It names anything that's wrong and the fix.
facebook-ad-library-cli doctor - 4
Ask Claude Code to use facebook-ad-library-cli.
Running facebook-ad-library-cli on its own lists every command, so Claude Code finds the one it needs.
- 1
Install the CLI. It needs Node 22 or newer.
npm install -g @thenavidm/facebook-ad-library-mcp-cli@latest - 2
Give Claude Code the skill, so it knows every command.
The skill is the SKILL.md in the package. It tells Claude Code what each command does and which ones ask first.
New-Item -ItemType Directory -Force "$HOME\.claude\skills\facebook-ad-library" | Out-Null
Copy-Item "$(npm root -g)\@thenavidm\facebook-ad-library-mcp-cli\SKILL.md" "$HOME\.claude\skills\facebook-ad-library\" - 3
Check your setup.
It names anything that's wrong and the fix.
facebook-ad-library-cli doctor - 4
Ask Claude Code to use facebook-ad-library-cli.
Running facebook-ad-library-cli on its own lists every command, so Claude Code finds the one it needs.
- 1
Install the CLI. It needs Node 22 or newer.
npm install -g @thenavidm/facebook-ad-library-mcp-cli@latest - 2
Give Claude Code the skill, so it knows every command.
The skill is the SKILL.md in the package. It tells Claude Code what each command does and which ones ask first.
mkdir -p ~/.claude/skills/facebook-ad-library
cp "$(npm root -g)/@thenavidm/facebook-ad-library-mcp-cli/SKILL.md" ~/.claude/skills/facebook-ad-library/ - 3
Check your setup.
It names anything that's wrong and the fix.
facebook-ad-library-cli doctor - 4
Ask Claude Code to use facebook-ad-library-cli.
Running facebook-ad-library-cli on its own lists every command, so Claude Code finds the one it needs.
- 1
Install the CLI. It needs Node 22 or newer.
npm install -g @thenavidm/facebook-ad-library-mcp-cli@latest - 2
Give Codex the skill, so it knows every command.
The skill is the SKILL.md in the package. It tells Codex what each command does and which ones ask first.
mkdir -p ~/.agents/skills/facebook-ad-library
cp "$(npm root -g)/@thenavidm/facebook-ad-library-mcp-cli/SKILL.md" ~/.agents/skills/facebook-ad-library/ - 3
Check your setup.
It names anything that's wrong and the fix.
facebook-ad-library-cli doctor - 4
Ask Codex to use facebook-ad-library-cli.
Running facebook-ad-library-cli on its own lists every command, so Codex finds the one it needs.
- 1
Install the CLI. It needs Node 22 or newer.
npm install -g @thenavidm/facebook-ad-library-mcp-cli@latest - 2
Give Codex the skill, so it knows every command.
The skill is the SKILL.md in the package. It tells Codex what each command does and which ones ask first.
New-Item -ItemType Directory -Force "$HOME\.agents\skills\facebook-ad-library" | Out-Null
Copy-Item "$(npm root -g)\@thenavidm\facebook-ad-library-mcp-cli\SKILL.md" "$HOME\.agents\skills\facebook-ad-library\" - 3
Check your setup.
It names anything that's wrong and the fix.
facebook-ad-library-cli doctor - 4
Ask Codex to use facebook-ad-library-cli.
Running facebook-ad-library-cli on its own lists every command, so Codex finds the one it needs.
- 1
Install the CLI. It needs Node 22 or newer.
npm install -g @thenavidm/facebook-ad-library-mcp-cli@latest - 2
Give Codex the skill, so it knows every command.
The skill is the SKILL.md in the package. It tells Codex what each command does and which ones ask first.
mkdir -p ~/.agents/skills/facebook-ad-library
cp "$(npm root -g)/@thenavidm/facebook-ad-library-mcp-cli/SKILL.md" ~/.agents/skills/facebook-ad-library/ - 3
Check your setup.
It names anything that's wrong and the fix.
facebook-ad-library-cli doctor - 4
Ask Codex to use facebook-ad-library-cli.
Running facebook-ad-library-cli on its own lists every command, so Codex finds the one it needs.
- 1
Install the CLI. It needs Node 22 or newer.
npm install -g @thenavidm/facebook-ad-library-mcp-cli@latest - 2
Check your setup.
It names anything that's wrong and the fix.
facebook-ad-library-cli doctor - 3
Ask Cursor to use facebook-ad-library-cli.
Running facebook-ad-library-cli on its own lists every command, so Cursor finds the one it needs.
- 1
Install the CLI. It needs Node 22 or newer.
npm install -g @thenavidm/facebook-ad-library-mcp-cli@latest - 2
Check your setup.
It names anything that's wrong and the fix.
facebook-ad-library-cli doctor - 3
Ask VS Code to use facebook-ad-library-cli.
Running facebook-ad-library-cli on its own lists every command, so VS Code finds the one it needs.
- 1
Install the CLI. It needs Node 22 or newer.
npm install -g @thenavidm/facebook-ad-library-mcp-cli@latest - 2
Give Copilot CLI the skill, so it knows every command.
The skill is the SKILL.md in the package. It tells Copilot CLI what each command does and which ones ask first.
mkdir -p ~/.copilot/skills/facebook-ad-library
cp "$(npm root -g)/@thenavidm/facebook-ad-library-mcp-cli/SKILL.md" ~/.copilot/skills/facebook-ad-library/ - 3
Check your setup.
It names anything that's wrong and the fix.
facebook-ad-library-cli doctor - 4
Ask Copilot CLI to use facebook-ad-library-cli.
Running facebook-ad-library-cli on its own lists every command, so Copilot CLI finds the one it needs.
- 1
Install the CLI. It needs Node 22 or newer.
npm install -g @thenavidm/facebook-ad-library-mcp-cli@latest - 2
Give Copilot CLI the skill, so it knows every command.
The skill is the SKILL.md in the package. It tells Copilot CLI what each command does and which ones ask first.
New-Item -ItemType Directory -Force "$HOME\.copilot\skills\facebook-ad-library" | Out-Null
Copy-Item "$(npm root -g)\@thenavidm\facebook-ad-library-mcp-cli\SKILL.md" "$HOME\.copilot\skills\facebook-ad-library\" - 3
Check your setup.
It names anything that's wrong and the fix.
facebook-ad-library-cli doctor - 4
Ask Copilot CLI to use facebook-ad-library-cli.
Running facebook-ad-library-cli on its own lists every command, so Copilot CLI finds the one it needs.
- 1
Install the CLI. It needs Node 22 or newer.
npm install -g @thenavidm/facebook-ad-library-mcp-cli@latest - 2
Give Copilot CLI the skill, so it knows every command.
The skill is the SKILL.md in the package. It tells Copilot CLI what each command does and which ones ask first.
mkdir -p ~/.copilot/skills/facebook-ad-library
cp "$(npm root -g)/@thenavidm/facebook-ad-library-mcp-cli/SKILL.md" ~/.copilot/skills/facebook-ad-library/ - 3
Check your setup.
It names anything that's wrong and the fix.
facebook-ad-library-cli doctor - 4
Ask Copilot CLI to use facebook-ad-library-cli.
Running facebook-ad-library-cli on its own lists every command, so Copilot CLI finds the one it needs.
- 1
Install the CLI. It needs Node 22 or newer.
npm install -g @thenavidm/facebook-ad-library-mcp-cli@latest - 2
Check your setup.
It names anything that's wrong and the fix.
facebook-ad-library-cli doctor - 3
Ask Gemini CLI to use facebook-ad-library-cli.
Running facebook-ad-library-cli on its own lists every command, so Gemini CLI finds the one it needs.
- 1
Install the CLI. It needs Node 22 or newer.
npm install -g @thenavidm/facebook-ad-library-mcp-cli@latest - 2
Give OpenCode the skill, so it knows every command.
The skill is the SKILL.md in the package. It tells OpenCode what each command does and which ones ask first.
mkdir -p ~/.config/opencode/skills/facebook-ad-library
cp "$(npm root -g)/@thenavidm/facebook-ad-library-mcp-cli/SKILL.md" ~/.config/opencode/skills/facebook-ad-library/ - 3
Check your setup.
It names anything that's wrong and the fix.
facebook-ad-library-cli doctor - 4
Ask OpenCode to use facebook-ad-library-cli.
Running facebook-ad-library-cli on its own lists every command, so OpenCode finds the one it needs.
- 1
Install the CLI. It needs Node 22 or newer.
npm install -g @thenavidm/facebook-ad-library-mcp-cli@latest - 2
Give OpenCode the skill, so it knows every command.
The skill is the SKILL.md in the package. It tells OpenCode what each command does and which ones ask first.
New-Item -ItemType Directory -Force "$HOME\.config\opencode\skills\facebook-ad-library" | Out-Null
Copy-Item "$(npm root -g)\@thenavidm\facebook-ad-library-mcp-cli\SKILL.md" "$HOME\.config\opencode\skills\facebook-ad-library\" - 3
Check your setup.
It names anything that's wrong and the fix.
facebook-ad-library-cli doctor - 4
Ask OpenCode to use facebook-ad-library-cli.
Running facebook-ad-library-cli on its own lists every command, so OpenCode finds the one it needs.
- 1
Install the CLI. It needs Node 22 or newer.
npm install -g @thenavidm/facebook-ad-library-mcp-cli@latest - 2
Give OpenCode the skill, so it knows every command.
The skill is the SKILL.md in the package. It tells OpenCode what each command does and which ones ask first.
mkdir -p ~/.config/opencode/skills/facebook-ad-library
cp "$(npm root -g)/@thenavidm/facebook-ad-library-mcp-cli/SKILL.md" ~/.config/opencode/skills/facebook-ad-library/ - 3
Check your setup.
It names anything that's wrong and the fix.
facebook-ad-library-cli doctor - 4
Ask OpenCode to use facebook-ad-library-cli.
Running facebook-ad-library-cli on its own lists every command, so OpenCode finds the one it needs.
- 1
Install the CLI. It needs Node 22 or newer.
npm install -g @thenavidm/facebook-ad-library-mcp-cli@latest - 2
Give OpenClaw the skill, so it knows every command.
The skill is the SKILL.md in the package. It tells OpenClaw what each command does and which ones ask first.
mkdir -p ~/.openclaw/skills/facebook-ad-library
cp "$(npm root -g)/@thenavidm/facebook-ad-library-mcp-cli/SKILL.md" ~/.openclaw/skills/facebook-ad-library/ - 3
Check your setup.
It names anything that's wrong and the fix.
facebook-ad-library-cli doctor - 4
Ask OpenClaw to use facebook-ad-library-cli.
Running facebook-ad-library-cli on its own lists every command, so OpenClaw finds the one it needs.
- 1
Install the CLI. It needs Node 22 or newer.
npm install -g @thenavidm/facebook-ad-library-mcp-cli@latest - 2
Give OpenClaw the skill, so it knows every command.
The skill is the SKILL.md in the package. It tells OpenClaw what each command does and which ones ask first.
New-Item -ItemType Directory -Force "$HOME\.openclaw\skills\facebook-ad-library" | Out-Null
Copy-Item "$(npm root -g)\@thenavidm\facebook-ad-library-mcp-cli\SKILL.md" "$HOME\.openclaw\skills\facebook-ad-library\" - 3
Check your setup.
It names anything that's wrong and the fix.
facebook-ad-library-cli doctor - 4
Ask OpenClaw to use facebook-ad-library-cli.
Running facebook-ad-library-cli on its own lists every command, so OpenClaw finds the one it needs.
- 1
Install the CLI. It needs Node 22 or newer.
npm install -g @thenavidm/facebook-ad-library-mcp-cli@latest - 2
Give OpenClaw the skill, so it knows every command.
The skill is the SKILL.md in the package. It tells OpenClaw what each command does and which ones ask first.
mkdir -p ~/.openclaw/skills/facebook-ad-library
cp "$(npm root -g)/@thenavidm/facebook-ad-library-mcp-cli/SKILL.md" ~/.openclaw/skills/facebook-ad-library/ - 3
Check your setup.
It names anything that's wrong and the fix.
facebook-ad-library-cli doctor - 4
Ask OpenClaw to use facebook-ad-library-cli.
Running facebook-ad-library-cli on its own lists every command, so OpenClaw finds the one it needs.
- 1
Install the CLI. It needs Node 22 or newer.
npm install -g @thenavidm/facebook-ad-library-mcp-cli@latest - 2
Check your setup.
It names anything that's wrong and the fix.
facebook-ad-library-cli doctor - 3
Ask Antigravity to use facebook-ad-library-cli.
Running facebook-ad-library-cli on its own lists every command, so Antigravity finds the one it needs.
- 1
Install the CLI. It needs Node 22 or newer.
npm install -g @thenavidm/facebook-ad-library-mcp-cli@latest - 2
Check your setup.
It names anything that's wrong and the fix.
facebook-ad-library-cli doctor - 3
Ask Hermes to use facebook-ad-library-cli.
Running facebook-ad-library-cli on its own lists every command, so Hermes finds the one it needs.
- 1
Install the CLI. It needs Node 22 or newer.
npm install -g @thenavidm/facebook-ad-library-mcp-cli@latest - 2
Check your setup.
It names anything that's wrong and the fix.
facebook-ad-library-cli doctor - 3
List every command, then try one.
facebook-ad-library-cli
facebook-ad-library-cli search-ads --query "cold plunge" --country US --limit 5
Needs Node 22 or newer. The free backend also needs Chromium once: `npx playwright install chromium`. Set it up.
It's free and open source. If it saves you time, star it on GitHub, so more people find it.
This free Facebook Ad Library MCP server and CLI gives your AI real access to Meta's Ad Library: every ad running on Facebook, Instagram, Messenger, Threads and Audience Network, for any advertiser in any country. It searches by keyword or advertiser, pulls every creative and copy variant of an ad, and remembers what a brand ran last time, so it can tell you what changed.
It's one install with two ways in. Claude, Codex, Cursor or any other MCP app calls its nine tools for you, and the same tools work as a CLI that agents like Claude Code, Codex and OpenCode run, or that you type yourself.
In this guide, I'll show you:
- What the Facebook Ad Library MCP server & CLI is, and what you can ask it
- How to install it and check that it works
- When to use the MCP server, and when the CLI
- Every tool, and how to keep your account safe
Every tool on this page comes from the server itself, and every cost was measured in Claude Code.
Key takeaways
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 two 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.
In an AI OS, the layer that connects your AI to your context, your data and your tools, a server like this is how your AI reaches Facebook Ad Library. My guide to building an AI operating system names Facebook Ad Library among the tools it reaches, and here's how I use AI myself.
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 askingWhat 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.
It works well next to my Facebook MCP server and ScrapeCreators MCP server, so your AI can post to your own Facebook Page and read public posts across networks in the same chat. Every server I've made is on my MCP servers page.
For your own ads, my free headline analyzer and viral hook generator help too.
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.
Windsurf, Zed and Cline take the same server, though they don't have a tab in the box yet. Follow the box's Cursor tab, and put its block here instead:
| App | Where the block goes |
|---|---|
| Windsurf | In the Cascade panel, open the Actions menu (…) and choose Open MCP config file, then paste the block. |
| Cline | Click the MCP Servers icon in the Cline panel, open the Configure tab, click Configure MCP Servers, and paste the block. |
| Zed | Go to Settings, then AI, then MCP Servers, and choose Add Server, then Add Local Server. Enter the block's command, arguments and variables, and Zed saves them under context_servers. |
Pro tip: The Ad Library is public, so there's nothing to sign in to. The free backend reads it the way your browser does, on your own computer.
Set up the Facebook Ad Library
There's no account and no key. The only setup is the browser the free backend drives.
npx playwright install chromium.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 doctorIf Chromium won't launch, run npx playwright install chromium. If Meta served a captcha, wait a few minutes and try again.
In Claude Code, /mcp also shows whether the Facebook Ad Library server is connected. It's one of the Claude Code commands worth knowing.
Use the Facebook Ad Library CLI
The CLI is the same nine 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 112577918783959The bare facebook-ad-library-cli lists every command, facebook-ad-library-cli which <words> finds the command for a task, and facebook-ad-library-cli <command> --help shows what a command takes. Nothing asks first, because nothing here writes.
facebook-ad-library-cli install <app> adds the server to Claude Code, Codex, Claude Desktop, Cursor, VS Code or Gemini CLI, in each app's own format.
These are the flags you'll use most:
| Flag | What it does |
|---|---|
--json | Prints JSON |
--compact | Prints the JSON on one line |
--select a,b.c | Keeps only those fields, and a dotted path goes deeper |
--agent | Machine mode: compact JSON, no prompts, and it never confirms anything |
--confirm | Lets a write that asks first go ahead |
--dry-run | Shows what a write would do, without doing it |
A script can branch on the exit code:
| Exit code | What it means |
|---|---|
| 0 | It worked |
| 2 | The command was typed wrong |
| 3 | There's no ad with that ID |
| 4 | A provider rejected its key |
| 5 | The Ad Library or a provider failed |
| 7 | You hit a rate limit, or a provider ran out of credits |
| 10 | A backend isn't set up, like a missing key or Chromium |
MCP server or CLI: which one?
Both are the same program with the same nine tools. The difference is when your AI pays for them, in the tokens it reads.
- MCP server
- 3,900 tokens
- CLI
- Nothing
- MCP server
- 730 tokens
- CLI
- Nothing
- MCP server
- Nothing more, or in Claude Code the tools it picks
- CLI
- 3,400 tokens, once
- MCP server
- 78,000 tokens
- CLI
- 3,400 tokens
- MCP server
- Yes
- CLI
- No, there's no terminal there
- MCP server
- No
- CLI
- Yes
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 October 5, 2026 in Claude Code 2.1.286 with Claude Opus 5.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.
| Field | What you get |
|---|---|
| Creatives | All of them, with HD and SD video links |
| Platforms | Facebook, Instagram, Messenger, Threads and Audience Network |
| Destination | The real landing page, query string included |
| Call to action | The button, like Shop now, straight from the data |
| Pagination | A real cursor, plus Meta's own count of matching ads |
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
The tables below list all nine 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
search_ads- What it does
- Search Meta's public Ad Library by keyword, or list every ad from one advertiser by passing page_id.
- Kind
- Reads
list_advertisers- What it does
- Resolve a brand name to the advertiser Pages actually running ads for it, ranked by how many ads each is running.
- Kind
- Reads
get_ad- What it does
- Fetch a single ad by its Ad Library ID, with every creative, all copy variants, the full destination URL and any transparency data.
- Kind
- Reads
transcribe_ad- What it does
- Speech to text for a video ad, so its spoken script becomes readable.
- Kind
- Reads
ad_library_url- What it does
- Turn a set of filters into the public Ad Library URL, so a person can open the same search in a browser and check the results independently.
- Kind
- Reads
Seeing an ad
view_ad_creative- What it does
- Return the actual images from one ad so you can see them, rather than only reading its copy.
- Kind
- Reads
Tracking changes
diff_advertiser- What it does
- Compare an advertiser's ads now against the last time this server looked, and report what they started and stopped running.
- Kind
- Reads
EU spend and reach
get_eu_transparency- What it does
- Spend, impressions, reach and demographic breakdown from Meta's official Ad Library API.
- Kind
- Reads
Status
backend_status- What it does
- Which backend is serving requests, whether it costs money per call, and which optional features are available in this configuration.
- Kind
- Reads
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.
Watch out: Ad copy is written by advertisers, and some of it is written to persuade. The server hands it to your AI as data to study, so treat any instruction inside an ad as part of the ad.
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.
FBADS_BACKEND- Default
browser- What it does
browserdrives Chromium on your computer.scrapecreatorsandapifyuse those providers, billed per ad
SCRAPECREATORS_API_KEY- Default
- none
- What it does
- Holds the key for the
scrapecreatorsbackend, which also enablestranscribe_ad
APIFY_TOKEN- Default
- none
- What it does
- Holds the token for the
apifybackend
META_ADS_ARCHIVE_TOKEN- Default
- none
- What it does
- Unlocks EU spend, reach and demographics, free from Meta
FBADS_HEADED- Default
- off
- What it does
1shows the browser, to see why a search came back empty
FBADS_RETRIES- Default
1- What it does
- Retries when the browser comes back empty
FBADS_STORE_DIR- Default
- your app data folder
- What it does
- Sets where
diff_advertiserkeeps its snapshots
FBADS_HTTP_TOKEN- Default
- none
- What it does
- Sets the bearer token for
--http
APIFY_ACTOR- Default
- none
- What it does
- Lite, the default, or full for enrichment
FBADS_HYDRATE_MS- Default
9000- What it does
- How long to let the page load
FBADS_SCROLL_WAIT_MS- Default
4000- What it does
- Pause between scrolls
FBADS_CACHE_DAYS- Default
1- What it does
- How old a ScrapeCreators cached answer may be
FBADS_SURFACE- Default
full- What it does
- Full tool list, or search for very large catalogs
FBADS_TOOL_TIMEOUT_MS- Default
- none
- What it does
- Deadline for any tool
FBADS_HTTP_PORT- Default
8787- What it does
- Port for --http, 8787 when unset
FBADS_HTTP_HOST- Default
- none
- What it does
- Address for --http, 127.0.0.1 when unset; any other needs a token
FBADS_HTTP_ALLOWED_ORIGINS- Default
- none
- What it does
- Browser origins beyond localhost that may call --http, comma-separated
FBADS_DEBUG- Default
- none
- What it does
- Print debug lines on stderr
Troubleshooting
Run the doctor first. It names the step that failed and the fix.
| What you see | What to do |
|---|---|
| "Chromium will not launch" | Run npx playwright install chromium |
| "Meta served a captcha" | Wait a few minutes, then search again |
| Empty results on every search | Meta is slowing this computer down. Wait, and search less often |
| Spend and reach are empty | That's expected outside the EU and political ads |
transcribe_ad says it needs a backend | Transcription runs only on the scrapecreators backend |
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.
More free tools for studying what works
Download the ads and videos you want to keep, or pull a transcript to read a video's script.
Free tools
FAQs about the Facebook Ad Library MCP server & CLI
Here are the questions people ask most about the Facebook Ad Library MCP server and CLI.
The Facebook Ad Library MCP server & CLI is a free, open source program that lets an AI app like Claude, Codex or Cursor research the ads any brand is running on Facebook and Instagram.
It has nine tools for searching ads, reading one in full, tracking what changed and EU spend, and the same tools run as a CLI that agents like Claude Code and Codex use, or that you type yourself.
An MCP server is a standard way to give an AI app real access to a tool, so it can act instead of guessing.
MCP stands for Model Context Protocol, and Claude, Codex, Cursor and many other AI apps speak it.
Every server I've made is on my MCP servers page.
The Facebook Ad Library CLI is the same program as the Facebook Ad Library MCP server, run as commands.
AI agents like Claude Code, Codex and OpenCode run them for you, and you can type them in a terminal or a script.
One npm package installs both.
Use the Facebook Ad Library MCP server in an AI app with no terminal, like Claude Desktop's chat, and the CLI in a terminal, a script or a cron job.
In an AI app that can run commands, like Claude Code, Codex or Cursor, the CLI is the lighter choice, because it costs nothing until it runs.
Yes, the Facebook Ad Library MCP server is free and open source under the MIT license, and its default backend needs no account and no key.
The Ad Library itself is free for anyone to read.
No, the Ad Library is public, and the server reads it without signing in to anything.
The free backend opens the Ad Library in a real browser and scrolls it, which takes 30 to 60 seconds a search.
A provider backend answers in seconds, billed per ad.
Only for ads delivered in the EU and for political ads, through get_eu_transparency.
For other advertisers, Meta doesn't publish spend anywhere.
No, and nothing can, because performance data isn't public.
You can see which ads have run longest, which is a reasonable signal but not the same thing.
The Facebook Ad Library MCP server works with any app that speaks MCP.
That includes Claude Code, Claude Desktop, Codex, Cursor, VS Code, Windsurf, Zed, Cline, GitHub Copilot CLI, Gemini CLI, OpenCode, OpenClaw, Antigravity and Hermes.
I did.
I'm Navid Moazzez, and I made the Facebook Ad Library MCP server & CLI as one of my free tools on navid.me.
You can read more about me.
The code is on GitHub under the MIT license, and the package is on npm.
More MCP servers & CLIs
Related free tools
Navid.me is reader-supported. When you buy through links on this site, I may earn an affiliate commission. Read the affiliate disclaimer.
On this page
The most actionable AI newsletter for founders
Every week, get proven AI strategies, curated tools, and step-by-step systems to grow your audience, create better content, and build a profitable creator business.
No fluff, no filler, no BS. Just five minutes each week that might level up your online business and life.
P.S. Sign up now to get free access to my ultimate AI tools guide for creators.
