Facebook广告库MCP服务器

Name: Facebook广告库MCP服务器
Author: StinCodes

作者：StinCodes2 星标更新：2025-06-09

安装使用来源：spider==github.com

项目介绍

Facebook 广告库 MCP 服务器

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

特性

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

安装

克隆仓库：

git clone <repository-url>
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"（按日期升序）或 "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)

安装 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://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