STARWARCLOUD STARWAR.AI
返回市场
脸书广告库-MCP

脸书广告库-MCP

作者：talknerdytome-labs162 星标更新：2025-10-26
安装使用来源：spider==github.com

项目介绍

Facebook 广告库 MCP 服务器

这是一个用于 Facebook 广告库的模型上下文协议（MCP）服务器。

通过这个服务器，你可以搜索 Facebook 的公共广告库中的任何公司或品牌，查看他们当前正在运行的广告并进行分析。你可以分析广告图片/文本，全面分析视频广告，并比较不同公司的策略，了解他们的广告活动中的哪些内容是有效的。

✨ 新功能

  • 🚀 批量处理：同时查询多个品牌和平台ID以减少API调用次数并提高效率
  • 🎬 视频批量分析：在单次Gemini API调用中分析多个视频，节省约88%的令牌
  • 💳 智能信用管理：自动检测API信用耗尽，并提供直接链接以充值你的ScrapeCreators账户
  • ⚡ 性能增强：智能缓存和请求去重以加快结果速度
  • 🔄 向后兼容：所有现有查询无需更改即可使用新的批处理功能

这是连接到Claude时你可以做的事情的一个示例。

https://github.com/user-attachments/assets/a47aa689-e89d-4d4b-9df7-6eb3a81937ee

要获取此项目和其他我们正在工作的项目的更新，请订阅这里

附言：加入我们的Twitter社区，了解有关MCP的所有信息

示例提示

单个品牌分析

AnthropicAI正在运行多少条广告？它们在视频和图像上的分布情况如何？

AnthropicAI当前在其广告中使用了什么信息？

分析来自Nike的视频广告，提取其视觉叙事策略、节奏和品牌信息技巧。

批量分析（新！）

比较Nike、Adidas和Under Armour的当前广告策略。展示他们的广告数量、信息主题和创意方法。

对AnthropicAI、Perplexity AI和OpenAI的信息进行深入比较。给出一个简洁可转发的总结。

分析Coca-Cola、Pepsi、Dr Pepper和Sprite的假日活动策略。他们在使用哪些主题？

获取所有主要流媒体服务的当前广告：Netflix、Disney+、Hulu、HBO Max、Amazon Prime Video和Apple TV+。比较他们的定位策略。

安装

先决条件

  • Python 3.12+
  • Anthropic Claude桌面应用（或Cursor）
  • Pip（Python包管理器），安装命令为python -m pip install
  • 一个访问令牌，从Scrape Creators获取
  • 一个Google Gemini API密钥，用于视频分析（可选，仅需用于视频广告）

快速安装（推荐）

  1. 克隆并运行安装脚本

    git clone http://github.com/talknerdytome-labs/facebook-ads-library-mcp.git
cd facebook-ads-library-mcp

# 对于macOS/Linux:
./install.sh

# 对于Windows:
install.bat

    安装脚本会：

    • 创建一个虚拟环境以隔离依赖项
    • 安装所有必需的依赖项
    • 设置配置文件

  2. 配置你的API密钥

    编辑创建的.env文件并添加你的API密钥：

  3. 遵循显示的MCP配置

    安装脚本会显示你需要添加到Claude Desktop或Cursor的确切配置。

手动安装

如果你更喜欢手动安装：

  1. 克隆此仓库

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

  2. 创建虚拟环境并安装依赖项

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

  3. 配置API密钥

    复制模板并配置你的API密钥：

    cp .env.template .env
# 然后编辑.env文件，填入实际的API密钥

    要获取API密钥：

    • 在此处注册Scrape Creators
    • 在此处获取Google Gemini API密钥（可选，用于视频分析）

  4. 连接到MCP服务器

    将MCP服务器配置添加到你的Claude Desktop或Cursor配置中：

    {
  "mcpServers": {
    "fb_ad_library": {
      "command": "{{PATH_TO_PROJECT}}/facebook-ads-library-mcp/venv/bin/python",
      "args": [
        "{{PATH_TO_PROJECT}}/facebook-ads-library-mcp/mcp_server.py"
      ]
    }
  }
}

    替换{{PATH_TO_PROJECT}}为你克隆此仓库的完整路径。

    注意： 配置使用虚拟环境的Python解释器（venv/bin/python）以实现更好的依赖隔离和可靠性。

    注意： API密钥现在会自动从.env文件加载，因此你不需要作为命令行参数传递它们。

    对于Claude Desktop：

    将此保存为claude_desktop_config.json在你的Claude Desktop配置目录中：

    ~/Library/Application Support/Claude/claude_desktop_config.json

    对于Cursor：

    将此保存为mcp.json在你的Cursor配置目录中：

    ~/.cursor/mcp.json

  5. 重启Claude Desktop / Cursor

    打开Claude Desktop，你应该能看到Facebook广告库作为一个可用集成。

    或者重启Cursor。

技术细节

  1. Claude向Python MCP服务器发送请求
  2. MCP服务器智能地批处理和优化对ScrapeCreators API的查询
  3. 智能缓存减少了冗余的API调用并提高了性能
  4. 信用监控通过主动错误处理防止工作流程中断
  5. 数据通过链路返回到Claude，带有增强的批处理信息

可用的MCP工具（增强版）

此MCP服务器提供了与Facebook广告库对象交互的工具：

工具名称描述批处理支持
get_meta_platform_id根据一个或多个品牌名称返回平台ID✅ 多个品牌
get_meta_ads获取特定页面（平台ID）的广告✅ 多个平台ID
analyze_ad_image分析广告图片的视觉元素、文本、颜色和构图⚡ 增强缓存
analyze_ad_video使用Gemini AI分析单个广告视频以获得全面见解⚡ 增强缓存
analyze_ad_videos_batchNEW - 在单次API调用中分析多个视频以节省令牌🎬 约88%令牌节省
get_cache_stats获取关于缓存媒体（图片和视频）和存储使用的统计信息-
search_cached_media按品牌、颜色、人物或媒体类型搜索已分析过的媒体-
cleanup_media_cache清理旧的缓存媒体文件以释放磁盘空间-

🆕 增强功能：

  • 批量处理：get_meta_platform_id和get_meta_ads现在接受单个字符串或数组以实现高效的批量操作
  • 视频批量分析：analyze_ad_videos_batch在单次Gemini API调用中处理多个视频以节省大量令牌
  • 智能信用管理：所有工具都能检测API信用耗尽，并提供直接链接以充值
  • 请求去重：在批量操作中自动移除重复请求
  • 令牌优化：共享提示处理减少了视频分析的Gemini API成本约88%
  • 向后兼容性：所有现有的单个查询工作流程继续不变地工作

故障排除

常见问题

🆕 ScrapeCreators API信用耗尽：

  • 当你看到“ScrapeCreators API信用耗尽”时，你需要充值你的账户
  • 错误消息包含一个直接链接到ScrapeCreators仪表板
  • 你可以在那里检查你的当前信用余额并购买更多信用
  • 一旦有可用信用，服务器将自动恢复工作

🆕 超出速率限制：

  • 如果你达到了速率限制，服务器会告诉你需要等待多久
  • 批量操作有助于减少达到速率限制的机会
  • 如果你经常达到限制，考虑分散大型批量请求

API密钥未找到错误：

  • 确保你的.env文件位于项目根目录
  • 如果没有.env文件，从模板复制：cp .env.template .env
  • 检查你的API密钥是否正确格式化且不带引号
  • 验证.env文件包含SCRAPECREATORS_API_KEY=your_key_here
  • 对于视频分析，确保也添加了GEMINI_API_KEY=your_key_here

视频分析不起作用：

  • 确认你在.env文件中有有效的Google Gemini API密钥
  • 视频分析需要GEMINI_API_KEY环境变量

MCP服务器连接问题：

  • 验证你的MCP配置中的路径指向正确的位置
  • 确保你已经创建了一个虚拟环境并安装了依赖项：python3 -m venv venv && ./venv/bin/pip install -r requirements.txt
  • 确保你的MCP配置使用了虚拟环境的Python路径（以/venv/bin/python结尾）
  • 在配置更改后重启Claude Desktop/Cursor

对于更多的Claude Desktop集成故障排除，请参阅MCP文档。该文档包括检查日志和解决常见问题的有用提示。

反馈

您的反馈将非常宝贵。请告诉我们您希望在列表中看到哪些功能，或者请求全新的功能。

许可

本项目根据MIT许可发布。

许可 Python