Skip to content
Back to search

facebook-ads-library-mcp

MCP Server for Facebook ADs Library - Get instant answers from FB's ad library

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/proxy-intell--facebook-ads-library-mcp/badge.svg)](/listings/proxy-intell--facebook-ads-library-mcp)

HTML

<a href="/listings/proxy-intell--facebook-ads-library-mcp"><img src="/api/listings/proxy-intell--facebook-ads-library-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Prerequisites

- Python 3.12+ - Anthropic Claude Desktop app (or Cursor) - Pip (Python package manager), install with `python -m pip install` - An API key for an ads data provider, set as `SCRAPECREATORS_API_KEY` (see configuration below) - A Google Gemini API key for video analysis (optional, only needed for video ads)

> Prefer not to deal with API keys? See the [Hosted Version](#hosted-version-recommended) above to skip setup entirely.

Quick Install (Recommended)

1. **Clone and run the install script**

   git clone https://github.com/proxy-intell/facebook-ads-library-mcp.git
   cd facebook-ads-library-mcp

   # For macOS/Linux:
   ./install.sh

   # For Windows:
   install.bat

The install script will: - Create a virtual environment for dependency isolation - Install all required dependencies - Set up your configuration files 2. **Configure your API keys** Edit the `.env` file that was created and add your API keys: - Set your ads data API key as `SCRAPECREATORS_API_KEY` - Get your Gemini API key at [Google AI Studio](https://aistudio.google.com/app/apikey) (optional, for video analysis) 3. **Follow the displayed MCP configuration** The install script will show you the exact configuration to add to Claude Desktop or Cursor.

Manual Install

If you prefer to install manually:

1. **Clone this repository**

   git clone https://github.com/proxy-intell/facebook-ads-library-mcp.git
   cd facebook-ads-library-mcp

2. **Create a virtual environment and install dependencies**

   python3 -m venv venv
   ./venv/bin/pip install -r requirements.txt

3. **Configure API keys** Copy the template and configure your API keys: **To obtain API keys:** - Set your ads data API key as `SCRAPECREATORS_API_KEY` in the `.env` file - Get a Google Gemini API key [here](https://aistudio.google.com/app/apikey) (optional, for video analysis) 4. **Connect to the MCP server** Add the MCP server configuration to your Claude Desktop or Cursor config: Replace `{{PATH_TO_PROJECT}}` with the full path to where you cloned this repository. **Note:** The configuration uses the virtual environment's Python interpreter (`venv/bin/python`) for better dependency isolation and reliability. **Note:** API keys are now automatically loaded from the `.env` file, so you don't need to pass them as command line arguments. **For Claude Desktop:** Save this as `claude_desktop_config.json` in your Claude Desktop configuration directory at: **For Cursor:** Save this as `mcp.json` in your Cursor configuration directory at: 5. **Restart Claude Desktop / Cursor** Open Claude Desktop and you should now see the Facebook Ads Library as an available integration. Or restart Cursor.

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

readme.md · README · 298 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. [![Proxy — Facebook Ads Library Hosted MCP](assets/banner.png)](https://useproxy.dev/)
  2. # Facebook Ads Library MCP Server
  3. > [!TIP]
  4. > **[Proxy](https://useproxy.dev/?utm_source=github&utm_medium=readme&utm_campaign=facebook-ads-library-mcp) (useproxy.dev) is the free hosted version of this server.** One connection gives ChatGPT, Claude, Cursor and any MCP client live ads from the Meta, Google, LinkedIn and TikTok (EU) ad libraries, with no API keys and 20 free credits a day. **[Use it in 2 minutes →](https://useproxy.dev/me/selfhost-facebook?utm_source=github&utm_medium=readme&utm_campaign=facebook-ads-library-mcp)**
  5. > [!WARNING]
  6. > This repo is the open-source, self-hosted Facebook server, for personal use and tinkering. It covers one platform, you pay ScrapeCreators for every call (about $1.88 per 1,000 after 100 free credits), and it doesn't get every feature hosted Proxy has. For client work or a team, [use hosted Proxy](https://useproxy.dev/?utm_source=github&utm_medium=readme&utm_campaign=facebook-ads-library-mcp).
  7. [![smithery badge](https://smithery.ai/badge/useproxy/proxy)](https://smithery.ai/servers/useproxy/proxy)
  8. This is a Model Context Protocol (MCP) server for the Facebook Ads Library.
  9. With this you can search Facebook's public ads library for any company or brand, see what they're currently running and analyze their advertising. You can analyze ad images/text, analyze video ads with comprehensive insights, compare companies' strategies, and get insights into what's working in their campaigns.
  10. Here's an example of what you can do when it's connected to Claude.
  11. [https://github.com/user-attachments/assets/a47aa689-e89d-4d4b-9df7-6eb3a81937ee](https://github.com/user-attachments/assets/a47aa689-e89d-4d4b-9df7-6eb3a81937ee)
  12. ---
  13. ## Hosted Version (Recommended)
  14. **The easiest way to use the Facebook Ads Library MCP is the hosted version from [Proxy (useproxy.dev)](https://useproxy.dev/).** No API keys, no Gemini key, no Python, no server to run — just connect and start querying.
  15. - ⚡ **Zero setup** — nothing to install, configure, or maintain
  16. - 🔑 **No API keys** — skip the ScrapeCreators and Gemini keys entirely
  17. - 🔌 **Works everywhere** — ChatGPT, Claude, Cursor, Manus, and anywhere else that supports MCP
  18. - 🚀 **Always up to date** — new tools and fixes ship automatically
  19. 👉 **[Get started for free at useproxy.dev →](https://useproxy.dev/me/selfhost-facebook?utm_source=github&utm_medium=readme&utm_campaign=facebook-ads-library-mcp)**
  20. Prefer to run it yourself? The full self-host setup is documented below.
  21. ### Hosted vs. Self-Host
  22. | | **Hosted: [Proxy (useproxy.dev)](https://useproxy.dev/?utm_source=github&utm_medium=readme&utm_campaign=facebook-ads-library-mcp)** | **Self-host (this repo)** |
  23. | --- | --- | --- |
  24. | Ad libraries | Meta, Google, LinkedIn and TikTok (EU) in one server | Meta (Facebook, Instagram) only |
  25. | Cost | Free for 20 credits a day; paid plans for more | ScrapeCreators credits (about $1.88 per 1,000 calls) plus Gemini usage for video |
  26. | API keys | None, sign in with OAuth | ScrapeCreators, plus Gemini for video |
  27. | Competitor discovery and competitive brief | ✅ | ❌ |
  28. | Inline ad carousel | ✅ | ❌ |
  29. | ChatGPT and claude.ai | ✅ (ChatGPT app and Claude connector) | ❌ (they need a public OAuth server) |
  30. | Claude Desktop, Claude Code, Cursor | ✅ | ✅ |
  31. | Setup and updates | None, managed for you | Python or Docker; `git pull` for updates |
  32. | Best for | Marketers, agencies, teams | Developers who want to change the code |
  33. Need another platform? The other self-hosted servers: [Google](https://github.com/proxy-intell/google-ads-library-mcp) · [LinkedIn](https://github.com/proxy-intell/linkedin-ads-library-mcp) · [TikTok](https://github.com/proxy-intell/tiktok-ads-library-mcp). Or get all four in one connection with [hosted Proxy](https://useproxy.dev/welcome?utm_source=github&utm_medium=readme&utm_campaign=facebook-ads-library-mcp). Comparison and setup for all four: [useproxy.dev/self-host](https://useproxy.dev/self-host?utm_source=github&utm_medium=readme&utm_campaign=facebook-ads-library-mcp).
  34. ---
  35. ## Example Prompts
  36. ### Single Brand Analysis
  37. ```plaintext
  38. How many ads is 'AnthropicAI' running? What's their split across video and image?
  39. ```
  40. ```plaintext
  41. What messaging is 'AnthropicAI' running right now in their ads?
  42. ```
  43. ```plaintext
  44. Analyze the video ads from 'Nike' and extract their visual storytelling strategy, pacing, and brand messaging techniques.
  45. ```
  46. ### Batch Analysis (New!)
  47. ```plaintext
  48. Compare the current advertising strategies across Nike, Adidas, and Under Armour. Show me their ad volumes, messaging themes, and creative approaches.
  49. ```
  50. ```plaintext
  51. Do a deep comparison to the messaging between 'AnthropicAI', 'Perplexity AI' and 'OpenAI'. Give it a nice forwardable summary.
  52. ```
  53. ```plaintext
  54. Analyze the holiday campaign strategies for Coca-Cola, Pepsi, Dr Pepper, and Sprite. What themes are they using?
  55. ```
  56. ```plaintext
  57. Get the current ads for all major streaming services: Netflix, Disney+, Hulu, HBO Max, Amazon Prime Video, and Apple TV+. Compare their positioning strategies.
  58. ```
  59. ---
  60. ## Installation
  61. ### Prerequisites
  62. - Python 3.12+
  63. - Anthropic Claude Desktop app (or Cursor)
  64. - Pip (Python package manager), install with `python -m pip install`
  65. - An API key for an ads data provider, set as `SCRAPECREATORS_API_KEY` (see configuration below)
  66. - A Google Gemini API key for video analysis (optional, only needed for video ads)
  67. > Prefer not to deal with API keys? See the [Hosted Version](#hosted-version-recommended) above to skip setup entirely.
  68. ### Quick Install (Recommended)
  69. 1. **Clone and run the install script**
  70. ```bash
  71. git clone https://github.com/proxy-intell/facebook-ads-library-mcp.git
  72. cd facebook-ads-library-mcp
  73. # For macOS/Linux:
  74. ./install.sh
  75. # For Windows:
  76. install.bat
  77. ```
  78. The install script will:
  79. - Create a virtual environment for dependency isolation
  80. - Install all required dependencies
  81. - Set up your configuration files
  82. 2. **Configure your API keys**
  83. Edit the `.env` file that was created and add your API keys:
  84. - Set your ads data API key as `SCRAPECREATORS_API_KEY`
  85. - Get your Gemini API key at [Google AI Studio](https://aistudio.google.com/app/apikey) (optional, for video analysis)
  86. 3. **Follow the displayed MCP configuration**
  87. The install script will show you the exact configuration to add to Claude Desktop or Cursor.
  88. ### Manual Install
  89. If you prefer to install manually:
  90. 1. **Clone this repository**
  91. ```bash
  92. git clone https://github.com/proxy-intell/facebook-ads-library-mcp.git
  93. cd facebook-ads-library-mcp
  94. ```
  95. 2. **Create a virtual environment and install dependencies**
  96. ```bash
  97. python3 -m venv venv
  98. ./venv/bin/pip install -r requirements.txt
  99. ```
  100. 3. **Configure API keys**
  101. Copy the template and configure your API keys:
  102. **To obtain API keys:**
  103. - Set your ads data API key as `SCRAPECREATORS_API_KEY` in the `.env` file
  104. - Get a Google Gemini API key [here](https://aistudio.google.com/app/apikey) (optional, for video analysis)
  105. 4. **Connect to the MCP server**
  106. Add the MCP server configuration to your Claude Desktop or Cursor config:
  107. Replace `{{PATH_TO_PROJECT}}` with the full path to where you cloned this repository.
  108. **Note:** The configuration uses the virtual environment's Python interpreter (`venv/bin/python`) for better dependency isolation and reliability.
  109. **Note:** API keys are now automatically loaded from the `.env` file, so you don't need to pass them as command line arguments.
  110. **For Claude Desktop:**
  111. Save this as `claude_desktop_config.json` in your Claude Desktop configuration directory at:
  112. **For Cursor:**
  113. Save this as `mcp.json` in your Cursor configuration directory at:
  114. 5. **Restart Claude Desktop / Cursor**
  115. Open Claude Desktop and you should now see the Facebook Ads Library as an available integration.
  116. Or restart Cursor.
  117. ---
  118. ## Deploy to the cloud
  119. Run it as a remote MCP server so Cursor, Claude Code or Claude Desktop can reach it from anywhere.
  120. [![Deploy to Render](https://render.com/images/deploy-to-render-button.svg)](https://render.com/deploy?repo=https://github.com/proxy-intell/facebook-ads-library-mcp)
  121. 1. Click the button and enter your `SCRAPECREATORS_API_KEY` (and `GEMINI_API_KEY` for video). Render generates `MCP_AUTH_TOKEN` for you.
  122. 2. Your endpoint is `https://<your-service>.onrender.com/mcp/`. Every request needs the header `Authorization: Bearer <MCP_AUTH_TOKEN>`.
  123. 3. Claude Code: `claude mcp add --transport http facebook-ads https://<your-service>.onrender.com/mcp/ --header "Authorization: Bearer <MCP_AUTH_TOKEN>"`
  124. Any Docker host works the same way:
  125. ```bash
  126. docker build -t facebook-ads-library-mcp .
  127. docker run -p 8000:8000 -e MCP_TRANSPORT=http -e MCP_AUTH_TOKEN=<long-random-string> -e SCRAPECREATORS_API_KEY=<key> facebook-ads-library-mcp
  128. ```
  129. The server refuses to start in HTTP mode without an `MCP_AUTH_TOKEN` of 16+ characters, so nobody else can spend your credits. Or skip all of this: [hosted Proxy](https://useproxy.dev/welcome?utm_source=github&utm_medium=readme&utm_campaign=facebook-ads-library-mcp) is already running.
  130. ---
  131. ## Usage data
  132. The server sends an anonymous ping to the maintainers on each tool call: the tool name, this repo's name, a call count and a random install ID stored in `~/.config/proxy-ads-mcp/`. It never sends tool arguments, results, API keys or anything about you. Turn it off with `PROXY_TELEMETRY=0` (or `DO_NOT_TRACK=1`). It tells us which tools people use so we know what to fix. Code: [`src/telemetry.py`](src/telemetry.py).
  133. Every so often (the 25th call, then every 100th) a tool result includes a one-line tip about hosted Proxy.
  134. ---
  135. ## Technical Details
  136. 1. Claude sends requests to the Python MCP server
  137. 2. The MCP server intelligently batches and optimizes queries to the ads data API
  138. 3. Smart caching reduces redundant API calls and improves performance
  139. 4. Credit monitoring prevents workflow interruption with proactive error handling
  140. 5. Data flows back through the chain to Claude with enhanced batch information
  141. ### Available MCP Tools (Enhanced)
  142. This MCP server provides tools for interacting with Facebook Ads library objects:
  143. | Tool Name | Description | Batch Support |
  144. | ------------------------- | -------------------------------------------------------------------------- | ----------------------- |
  145. | `get_meta_platform_id` | Returns platform ID given one or many brand names | ✅ Multiple brands |
  146. | `get_meta_ads` | Retrieves ads for specific page(s) (platform ID) | ✅ Multiple platform IDs |
  147. | `analyze_ad_image` | Analyzes ad images for visual elements, text, colors, and composition | ⚡ Enhanced caching |
  148. | `analyze_ad_video` | Analyzes single ad video using Gemini AI for comprehensive insights | ⚡ Enhanced caching |
  149. | `analyze_ad_videos_batch` | **NEW** - Analyzes multiple videos in single API call for token efficiency | 🎬 ~88% token savings |
  150. | `get_cache_stats` | Gets statistics about cached media (images and videos) and storage usage | - |
  151. | `search_cached_media` | Searches previously analyzed media by brand, colors, people, or media type | - |
  152. | `cleanup_media_cache` | Cleans up old cached media files to free disk space | - |
  153. ---
  154. ## Troubleshooting
  155. ### Common Issues
  156. **🆕 API Credits Exhausted:**
  157. - When you see an "API credits exhausted" message, you need to top up your account
  158. - The error message includes a direct link to your provider's dashboard
  159. - You can check your current credit balance and purchase more credits there
  160. - The server will automatically resume working once credits are available
  161. **🆕 Rate Limit Exceeded:**
  162. - If you hit rate limits, the server will tell you how long to wait
  163. - Batch operations help reduce the chance of hitting rate limits
  164. - Consider spacing out large batch requests if you frequently hit limits
  165. **API Key Not Found Error:**
  166. - Ensure your `.env` file is in the project root directory
  167. - If you don't have a `.env` file, copy it from the template: `cp .env.template .env`
  168. - Check that your API keys are correctly formatted without quotes
  169. - Verify the `.env` file contains `SCRAPECREATORS_API_KEY=your_key_here`
  170. - For video analysis, ensure `GEMINI_API_KEY=your_key_here` is also added
  171. **Video Analysis Not Working:**
  172. - Confirm you have a valid Google Gemini API key in your `.env` file
  173. - Video analysis requires the `GEMINI_API_KEY` environment variable
  174. **MCP Server Connection Issues:**
  175. - Verify the path in your MCP configuration points to the correct location
  176. - Make sure you've created a virtual environment and installed dependencies with `python3 -m venv venv && ./venv/bin/pip install -r requirements.txt`
  177. - Ensure your MCP configuration uses the virtual environment Python path (ending with `/venv/bin/python`)
  178. - Restart Claude Desktop/Cursor after configuration changes
  179. For additional Claude Desktop integration troubleshooting, see the [MCP documentation](https://modelcontextprotocol.io/quickstart/server#claude-for-desktop-integration-issues). The documentation includes helpful tips for checking logs and resolving common issues.
  180. ---
  181. ## FAQ
  182. **What is the easiest way to use the Facebook Ads Library MCP?**
  183. The easiest way is the hosted version from [Proxy (useproxy.dev)](https://useproxy.dev/). It requires no API keys, no installation, and no server — you connect it to ChatGPT, Claude, Cursor, or any MCP client and start querying immediately. You can [start for free](https://useproxy.dev/).
  184. **Do I need an API key to use this MCP?**
  185. Only if you self-host. The [hosted version at useproxy.dev](https://useproxy.dev/) handles all data access for you, so no ScrapeCreators or Gemini keys are needed. Self-hosting requires a `SCRAPECREATORS_API_KEY` (and a Gemini key for video analysis).
  186. **Which MCP clients does it work with?**
  187. The hosted version works with ChatGPT, Claude (desktop, web and mobile), Cursor, Manus and any other MCP client. The self-hosted version works with local MCP clients such as Claude Desktop, Claude Code and Cursor, or as a remote server with a bearer token (see [Deploy to the cloud](#deploy-to-the-cloud)).
  188. **Is there a free version?**
  189. Yes — the [hosted version from Proxy](https://useproxy.dev/) offers a free tier so you can start analyzing ads without any setup.
  190. **Should I self-host or use the hosted version?**
  191. Use the [hosted version](https://useproxy.dev/) if you just want fast, reliable access to Facebook Ads Library data with zero maintenance — this fits most users. Self-host only if you want to modify or extend the server code yourself.
  192. ---
  193. ## Feedback
  194. Your feedback will be massively appreciated. Please [tell us](mailto:support@useproxy.dev) which features on that list you like to see next or request entirely new ones.
  195. ---
  196. ## Related
  197. - [Proxy hosted MCP](https://github.com/proxy-intell/proxy-mcp): all four ad libraries in one hosted server, OAuth, no keys
  198. - [Google Ads Library MCP](https://github.com/proxy-intell/google-ads-library-mcp) (self-hosted)
  199. - [LinkedIn Ads Library MCP](https://github.com/proxy-intell/linkedin-ads-library-mcp) (self-hosted)
  200. - [TikTok Ads Library MCP](https://github.com/proxy-intell/tiktok-ads-library-mcp) (self-hosted)
  201. - [Install guide for every client](https://useproxy.dev/welcome?utm_source=github&utm_medium=readme&utm_campaign=facebook-ads-library-mcp)
  202. ---
  203. ## License
  204. This project is licensed under the MIT License.
  205. ---
  206. Made with ❤️ by the team at [Proxy](https://useproxy.dev/).
  207. [![MseeP.ai Security Assessment Badge](https://mseep.net/pr/proxy-intell-facebook-ads-library-mcp-badge.png)](https://mseep.ai/app/proxy-intell-facebook-ads-library-mcp)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.