STARWARCLOUD STARWAR.AI
返回市场
Facebook广告库MCP服务器

Facebook广告库MCP服务器

作者：StinCodes2 星标更新：2025-06-09
安装使用来源：spider==github.com

项目介绍

Facebook 广告库 MCP 服务器

这是一个通过网络爬虫提供访问 Facebook 广告库的 Model Context Protocol (MCP) 服务器。该服务器公开了一个 MCP 工具，用于搜索广告并提供了全面的过滤选项。

特性

  • 符合 MCP 标准：使用官方 MCP SDK 构建
  • 全面的广告数据：提取广告商、内容、日期、展示次数、花费等信息
  • 高级过滤：按公司、日期范围和关键词进行过滤
  • 智能分页：自动滚动以检索最多 100 条广告
  • 灵活排序：按日期（升序/降序）或相关性排序

安装

  1. 克隆仓库：
git clone <repository-url>
cd FbAdLibraryMCPServer
  1. 安装依赖：
npm install
  1. 安装 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": "公司名称",
      "content": "广告文本内容",
      "start_date": "2024年1月15日",
      "end_date": "2024年2月15日",
      "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：运行时类型验证

部署 (Fly.io)

  1. 安装 flyctl：
curl -L https://fly.io/install.sh | sh
export FLYCTL_INSTALL="/root/.fly"
export PATH="$FLYCTL_INSTALL/bin:$PATH"
  1. 部署到 Fly.io：
flyctl auth signup
flyctl launch --no-deploy
flyctl secrets set NODE_ENV=production
flyctl deploy
  1. 实时部署：
    • 应用 URL：https://fbadlibrarymcpserver.fly.dev
    • 健康检查：https://fbadlibrarymcpserver.fly.dev/healthz
    • MCP 端点：https://fbadlibrarym_服务器.fly.dev/mcp（仅限 POST）
    • 测试端点：https://fbadlibrarymcpserver.fly.dev/test-search（GET/POST）

连接详情

公共 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"
  }
}

认证：无需认证

许可证

ISC