FbAdLibraryMCPServer

Facebook 广告资料库 MCP 服务

一个通过网页抓取来访问 Facebook 广告资料库的模型上下文协议（MCP）服务。此服务提供一个 MCP 工具，用于搜索广告，并支持全面的筛选选项。

功能

• 符合 MCP 规范：使用官方 MCP SDK 构建
• 全面的广告数据：提取广告主、内容、日期、展示量、花费等信息
• 高级筛选：按公司、日期范围和关键词筛选
• 智能分页：自动滚动，每次搜索最多可检索 100 条广告
• 灵活排序：按日期（升序或降序）或相关性排序

安装

1. 克隆仓库：

git clone <repository-url>
cd FbAdLibraryMCPServer

2. 安装依赖：

npm install

3. 安装 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" 或 "relevance"（默认值："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 传输：

• URL：http://localhost:3000/mcp
• 方法：POST
• 标头：Content-Type: application/json

运行状况检查：

• URL：http://localhost:3000/healthz
• 方法：GET

架构

• MCP 服务（src/index.ts）：承载 MCP 协议的 Express HTTP 服务
• 搜索处理器（src/mcp/searchAdsHandler.ts）：核心业务逻辑
• 网页抓取器（src/scraper/scrapeFacebookAds.ts）：基于 Playwright 的 Facebook 抓取器
• 筛选器（src/utils/filters.ts）：日期解析和筛选工具

性能注意事项

• 速率限制：请求之间内置延迟，以避免被拦截
• 分页：自动滚动，并根据智能停止条件终止
• 浏览器管理：妥善清理 Playwright 浏览器实例
• 内存效率：尽可能采用流式数据处理

反机器人检测对策

此服务通过以下方式成功绕过 Facebook 的反机器人检测：

• 虚拟显示器（Xvfb）：在云环境中运行非无头浏览器
• 自然导航：模拟人类浏览模式（主页 → 广告资料库）
• 简化的浏览器配置：避免使用会触发检测的复杂“隐身”技术
• 智能超时处理：浏览器启动超时设为 30 秒，并提供回退机制
• 针对生产环境优化：在生产环境和开发环境中采用不同的行为

已知限制

• 以非无头模式运行，以避免被检测
• 每次搜索最多返回 100 条广告，以避免超时
• 日期格式取决于 Facebook 的显示格式
• 可能受到 Facebook 反机器人措施的影响

法律与伦理说明

• 通过内置延迟遵守 Facebook 的速率限制
• 不存储用户个人数据
• 旨在用于研究和分析
• 用户应遵守 Facebook 的服务条款

依赖项

• @modelcontextprotocol/sdk：MCP 协议实现
• playwright：网页抓取自动化
• date-fns：日期解析与处理
• express：HTTP 服务框架
• zod：运行时类型验证

Deployment (Fly.io)

1. Install flyctl:

curl -L https://fly.io/install.sh | sh
export FLYCTL_INSTALL="/root/.fly"
export PATH="$FLYCTL_INSTALL/bin:$PATH"

2. Deploy to Fly.io:

flyctl auth signup
flyctl launch --no-deploy
flyctl secrets set NODE_ENV=production
flyctl deploy

3. Live Deployment:
   • App URL: https://fbadlibrarymcpserver.fly.dev
   • Health check: https://fbadlibrarymcpserver.fly.dev/healthz
   • MCP endpoint: https://fbadlibrarymcpserver.fly.dev/mcp (POST only)
   • Test endpoint: https://fbadlibrarymcpserver.fly.dev/test-search (GET/POST)

Connection Details

Public URL: https://fbadlibrarymcpserver.fly.dev

Quick Test: https://fbadlibrarymcpserver.fly.dev/test-search?company=Nike&limit=3

MCP Client Configuration:

{
  "transport": "http",
  "url": "https://fbadlibrarymcpserver.fly.dev/mcp",
  "method": "POST",
  "headers": {
    "Content-Type": "application/json",
    "Accept": "application/json, text/event-stream"
  }
}

Authentication: None required

License

ISC