meta-ads-search

Meta Ads Search

ローカルの Frevana デーモンと Chrome 拡張機能のセッションを通じて、Meta Ads Library を検索します。

目的

このスキルは、Chrome 拡張機能と連携した Frevana MCP ツール frevana_meta_ads_search を使って、キーワードまたは広告主のテキストで Meta／Facebook 広告を検索するためのものです。

入力：

• keyword（必須） - Meta Ads Library で検索するキーワード、広告主、またはブランドのテキスト
• country（任意） - ALL または US、CN、GB などの ISO 3166-1 alpha-2 国コード。デフォルトは ALL です
• active_status（任意） - active、inactive、または all。デフォルトは active です
• date_from（任意） - YYYY-MM-DD 形式の開始日（指定日を含む）
• date_to（任意） - YYYY-MM-DD 形式の終了日（指定日を含む）
• maxResults（任意） - 返す広告の最大数。デフォルトは 20、上限は 500 です
• timeout（任意） - タイムアウト（ミリ秒）

出力：

• 構造化された Meta 広告レコードを含む、Frevana の生 JSON テキスト

ユーザーが生の出力を求めていない場合は、結果を要約します。

このスキルに必要なもの

• ユーザーが指定する keyword
• 同梱の scripts/setup.sh ラッパー。最新の公式 Frevana セットアップスクリプトをダウンロードして実行します
• セットアップ後に実行される Frevana ローカルデーモン。デフォルトポートは 12306 です
• Frevana Chrome 拡張機能を通じて接続された Chrome
• 接続中の Chrome セッションからアクセス可能な Meta Ads Library
• curl
• bash
• python3

これは Chrome 拡張機能のスキルです。ローカルデーモンと Chrome 拡張機能のセッションを使用します。

実行順序

次の手順に従います。

1. ユーザーが keyword、またはそれに相当する広告主／ブランドのテキストを指定していることを確認します。
2. アドホックな frevana call コマンドより、スクリプトを優先します。
3. country のデフォルトを ALL、active_status のデフォルトを active、maxResults のデフォルトを 20 にします。任意の日付範囲やタイムアウトの値を勝手に指定しないでください。
4. Frevana ツールを呼び出すたびに、スクリプトで同梱の scripts/setup.sh を実行します。
5. セットアップで Chrome が未接続と報告された場合は中止し、Chrome を開いて Frevana 拡張機能を接続してから再試行するようユーザーに伝えます。
6. セットアップが成功した後にのみ、Meta Ads を検索します。
7. 結果がログイン／認証に関する内容に見える場合、または Meta Ads Library を利用できない場合は、利用可能な Chrome セッションが必要となる可能性があることを伝え、再試行を案内します。
8. 広告の簡潔な要約、またはユーザーが求めた場合は生の JSON を返します。
9. 必要に応じて、出力をファイルに保存します。

コマンド

基本的なキーワード検索

bash <skill-path>/scripts/search_meta_ads.sh \
  --keyword "nike"

--query、--q、--text は --keyword のエイリアスとして使用できます。 追加のオプションを指定しない場合、すべての国の有効な広告を検索し、最大 20 件の広告を返します。

国と有効ステータスで絞り込む

bash <skill-path>/scripts/search_meta_ads.sh \
  --keyword "nike" \
  --country US \
  --active-status active

--active_status は --active-status のエイリアスとして使用できます。

日付範囲と結果数を指定する

bash <skill-path>/scripts/search_meta_ads.sh \
  --keyword "nike" \
  --date-from 2026-01-01 \
  --date-to 2026-06-22 \
  --max-results 50

--date_from、--date_to、--maxResults はエイリアスとして使用できます。

出力をファイルに保存する

bash <skill-path>/scripts/search_meta_ads.sh \
  --keyword "nike" \
  --output ./out/meta-ads-search-result.json

固定ツール呼び出し形式

スクリプトは次を呼び出します。

frevana call frevana_meta_ads_search '<json_args>'

JSON 引数には常にデフォルトの国、有効ステータス、結果数の上限が含まれます。その他の任意のフィールドは、指定されていない場合は省略されます。

{
  "keyword": "nike",
  "country": "ALL",
  "active_status": "active",
  "maxResults": 20
}

ユーザーが国と結果数の上限を指定した場合は、デフォルト値より優先されます。

{
  "keyword": "nike",
  "country": "US",
  "active_status": "active",
  "date_from": "2026-01-01",
  "date_to": "2026-06-22",
  "maxResults": 50,
  "timeout": 120000
}

frevana_meta_ads_search にサポートされていないフィールドを渡さないでください。

出力

• 成功時：スクリプトは Frevana ツールの結果を標準出力に出力します
• --output を指定した場合：同じ結果が指定されたファイルパスにも書き込まれます
• 失敗時：スクリプトは Frevana のエラーまたは事前チェックの失敗を標準エラー出力に出力し、ゼロ以外の終了コードで終了します

注意事項

• --keyword、--query、--q、--text のいずれかが必要です。
• --country のデフォルト値は ALL です。結果を1か国に絞り込むには、2文字の大文字の国コードを指定してください。
• --active-status のデフォルト値は active です。ユーザーから明示的に要求された場合にのみ、inactive または all を使用してください。
• --date-from と --date-to は YYYY-MM-DD 形式で指定してください。
• --max-results のデフォルト値は 20 で、1～500の整数を指定する必要があります。
• --timeout を指定する場合は、正の整数を指定してください。
• このスクリプトは、元の Frevana スキルのフローに合わせ、検索のたびに同梱の scripts/setup.sh を実行します。
• scripts/setup.sh は、https://raw.githubusercontent.com/FinpeakInc/frevana-cli-releases/refs/heads/main/skills/frevana/scripts/setup.sh から最新の公式セットアップスクリプトをダウンロードして実行します。
• frevana が見つからない場合、公式セットアップスクリプトはデーモンの起動／確認前に Frevana バイナリをインストールします。

プロンプトの例

中国語

• 「Meta Ads Library で nike の広告を調べて」
• 「Facebook 広告ライブラリで openai に関する広告を検索して。米国、active のみ」
• 「meta ads を調べて。キーワードは shopify、期間は 2026-01-01 から 2026-06-22 まで、元の JSON を保存して」

英語

• 「Meta Ads Library で nike の広告を検索して」
• 「米国の openai に関する active な Meta 広告を検索して」
• 「2026-01-01 から 2026-06-22 までの shopify に関する Meta 広告を検索して、元の JSON を保存して」