Facebook广告库MCP服务器
一种模型上下文协议（MCP）服务器，通过网络抓取提供对Facebook广告库的访问。此服务器提供了一个MCP工具，用于搜索具有全面过滤选项的广告。
特性
- 符合MCP标准：使用官方MCP SDK构建
- 全面的广告数据：提取广告商、内容、日期、印象、支出等
- 高级过滤：按公司、日期范围和关键字筛选
- 智能分页：自动滚动，每次搜索最多可检索100个广告
- 灵活排序：按日期（升序/降序）或相关性排序
安装
- 克隆存储库：
git clone
cd FbAdLibraryMCPServer- 安装依赖项：
npm install- 安装Playwright浏览器：
npx playwright install用法
发展
npm run dev生产
npm run build
npm start服务器将在端口3000上启动（可通过以下方式配置 PORT 环境变量）。
API文档
MCP工具： search_ads
使用可选过滤器搜索Facebook广告。
参数：
company（字符串，可选）：要筛选的公司/广告商名称start_date（字符串，可选）：YYYY-MM-DD格式的开始日期end_date（字符串，可选）：YYYY-MM-DD格式的结束日期keywords（字符串数组，可选）：在广告内容中搜索的关键字limit（整数，可选）：返回的最大广告数（默认值：50，最大值：100）order（字符串，可选）：排序顺序-“date_desc”、“date_asc”或“相关性”（默认值：“date_desc”）
工具调用示例：
{
"tool": "search_ads",
"arguments": {
"company": "Nike",
"start_date": "2024-01-01",
"end_date": "2024-01-31",
"keywords": ["running", "shoes"],
"limit": 10,
"order": "date_desc"
}
}响应格式：
{
"ads": [
{
"id": "unique_ad_identifier",
"advertiser": "Company Name",
"content": "Ad text content",
"start_date": "Jan 15, 2024",
"end_date": "Feb 15, 2024",
"impressions": "1,000-5,000",
"spend": "$100-$500",
"platforms": ["Facebook"],
"creative_url": "https://...",
"demographics": {"targeting": "..."},
"scraped_at": "2024-01-20T10:30:00Z"
}
]
}MCP客户端连接
使用任何兼容MCP的客户端连接到服务器：
HTTP传输：
- 网址：
http://localhost:3000/mcp - 方法：POST
- 标题：
Content-Type: application/json
健康检查：
- 网址：
http://localhost:3000/healthz - 方法：GET
建筑
- MCP服务器 (
src/index.ts)：承载MCP协议的快速HTTP服务器 - 搜索处理程序 (
src/mcp/searchAdsHandler.ts)：核心业务逻辑 - Web剪贴器 (
src/scraper/scrapeFacebookAds.ts)：基于剧作家的Facebook scraper - 过滤器 (
src/utils/filters.ts)：日期解析和筛选实用程序
性能注意事项
- 速率限制：请求之间内置延迟以避免阻塞
- 分页：具有智能停止条件的自动滚动
- 浏览器管理：正确清理Playwright浏览器实例
- 内存效率：尽可能进行流数据处理
反机器人检测对策
该服务器通过以下方式成功绕过了Facebook的反机器人检测：
- 虚拟显示器（Xvfb）：在云环境中运行非无头浏览器
- 自然导航：模仿人类浏览模式（主页→ 广告库）
- 简化浏览器配置：避免触发探测的复杂“隐形”技术
- 智能超时处理：具有回退机制的30秒浏览器启动超时
- 生产优化：生产环境与开发环境中的不同行为
已知限制
- 以非无头模式运行以避免检测
- 每次搜索限制为100个广告，以防止超时
- 日期格式取决于Facebook的显示格式
- 受Facebook反机器人措施的约束
法律和道德说明
- 尊重脸书通过内置延迟进行的限速
- 不存储个人用户数据
- 用于研究和分析目的
- 用户应遵守Facebook的服务条款
依赖项
@modelcontextprotocol/sdk：MCP协议实施playwright：Web抓取自动化date-fns：日期解析和操作express：HTTP服务器框架zod：运行时类型验证
部署（Fly.io）
- 安装flyctl：
curl -L https://fly.io/install.sh | sh
export FLYCTL_INSTALL="/root/.fly"
export PATH="$FLYCTL_INSTALL/bin:$PATH"- 部署到Fly.io：
flyctl auth signup
flyctl launch --no-deploy
flyctl secrets set NODE_ENV=production
flyctl deploy- 实时部署：
- 应用程序URL: https://fbadlibrarymcpserver.fly.dev - 健康检查： https://fbadlibrarymcpserver.fly.dev/healthz - MCP端点： https://fbadlibrarymcpserver.fly.dev/mcp （仅限POST） - 测试终点： https://fbadlibrarymcpserver.fly.dev/test-search （获取/发布）
连接详细信息
公共URL: https://fbadlibrarymcpserver.fly.dev
快速测试： https://fbadlibrarymcpserver.fly.dev/test-search?company=Nike&limit=3
MCP客户端配置：
{
"transport": "http",
"url": "https://fbadlibrarymcpserver.fly.dev/mcp",
"method": "POST",
"headers": {
"Content-Type": "application/json",
"Accept": "application/json, text/event-stream"
}
}身份验证： 无需
许可证
国际协调委员会