FbAdLibraryMCPServer

Facebook Ad Library MCP サーバー

Web スクレイピングを通じて Facebook の Ad Library にアクセスする、Model Context Protocol（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）：中核となるビジネスロジック
• Web スクレイパー（src/scraper/scrapeFacebookAds.ts）：Playwright ベースの Facebook スクレイパー
• フィルター（src/utils/filters.ts）：日付の解析およびフィルタリング用ユーティリティ

パフォーマンスに関する考慮事項

• レート制限：ブロックを避けるため、リクエスト間に組み込みの待機時間を設けています
• ページネーション：適切な終了条件を備えた自動スクロール
• ブラウザー管理：Playwright のブラウザーインスタンスを適切にクリーンアップします
• メモリー効率：可能な場合はストリーミングでデータを処理します

ボット検出への対策

このサーバーは、以下の方法で Facebook のボット検出を回避します：

• 仮想ディスプレイ（Xvfb）：クラウド環境でヘッドレスではないブラウザーを実行します
• 自然なナビゲーション：人間の閲覧パターン（ホームページ → Ad Library）を模倣します
• シンプルなブラウザー設定：検出を招く複雑な「ステルス」手法を避けます
• スマートなタイムアウト処理：フォールバック機構を備えた 30 秒のブラウザー起動タイムアウト
• 本番環境向けに最適化：本番環境と開発環境で動作を切り替えます

既知の制限事項

• 検出を避けるため、ヘッドレスではないモードで実行します
• タイムアウトを防ぐため、検索ごとに最大 100 件の広告に制限されています
• 日付形式は Facebook の表示形式に依存します
• Facebook のボット対策の影響を受けます

法的・倫理的な注意事項

• 組み込みの待機時間により、Facebook のレート制限を尊重します
• 個人ユーザーデータは保存しません
• 調査および分析を目的としています
• ユーザーは Facebook の利用規約を遵守する必要があります

依存関係

• @modelcontextprotocol/sdk：MCP プロトコルの実装
• playwright：Web スクレイピングの自動化
• 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