meta-ads-search

这段内容是审核时保存的快照。外部来源才是完整且最新的版本。

---
name: meta-ads-search
description: Use when the user wants Meta Ads Library or Facebook ad search results through the local Frevana Chrome Extension-backed tool, including keyword, country, status, and date-range filtering.
---

# Meta Ads Search

Search Meta Ads Library through the local Frevana daemon and Chrome Extension session.

## Purpose

This skill is for **finding Meta/Facebook ads by keyword or advertiser text** using the Chrome Extension-backed Frevana MCP tool `frevana_meta_ads_search`.

Inputs:

- `keyword` (required) - keyword, advertiser, or brand text to search in Meta Ads Library
- `country` (optional) - `ALL` or an ISO 3166-1 alpha-2 country code such as `US`, `CN`, or `GB`; defaults to `ALL`
- `active_status` (optional) - `active`, `inactive`, or `all`; defaults to `active`
- `date_from` (optional) - inclusive start date in `YYYY-MM-DD`
- `date_to` (optional) - inclusive end date in `YYYY-MM-DD`
- `maxResults` (optional) - maximum number of ads to return, defaults to `20`, max 500
- `timeout` (optional) - timeout in milliseconds

Output:

- raw Frevana JSON text containing structured Meta ad records

Summarize the results unless the user asks for the raw output.

## What This Skill Needs

- user-provided `keyword`
- bundled `scripts/setup.sh` wrapper, which downloads and runs the latest official Frevana setup script
- Frevana local daemon running after setup, default port `12306`
- Chrome connected through the Frevana Chrome Extension
- Meta Ads Library reachable in the connected Chrome session
- `curl`
- `bash`
- `python3`

This is a Chrome Extension skill. It uses the local daemon and Chrome Extension session.

## Execution Order

Use this flow:

1. Confirm the user has provided `keyword` or equivalent advertiser / brand text.
2. Prefer the script over ad hoc `frevana call` commands.
3. Default `country` to `ALL`, `active_status` to `active`, and `maxResults` to `20`. Do not invent optional date range or timeout values.
4. Let the script run bundled `scripts/setup.sh` before every Frevana tool call.
5. If setup reports Chrome disconnected, stop and tell the user to open Chrome, connect the Frevana extension, and retry.
6. Run the Meta Ads search only after setup succeeds.
7. If the result looks like login/auth content or Meta Ads Library is unavailable, tell the user they may need an available Chrome session and retry.
8. Return a concise summary of the ads, or the raw JSON if requested.
9. When useful, save the output to a file.

## Commands

### Basic keyword search

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

`--query`, `--q`, and `--text` are accepted as aliases for `--keyword`.
Without extra options, this searches active ads in all countries and returns up to 20 ads.

### Filter by country and active status

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

`--active_status` is accepted as an alias for `--active-status`.

### Limit date range and result count

```bash
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`, and `--maxResults` are accepted as aliases.

### Save output to file

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

## Fixed Tool Call Shape

The script calls:

```bash
frevana call frevana_meta_ads_search '<json_args>'
```

The JSON arguments always include the default country, active status, and result limit; other optional fields are omitted when not provided:

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

When the user specifies country and result limit, they override those defaults:

```json
{
  "keyword": "nike",
  "country": "US",
  "active_status": "active",
  "date_from": "2026-01-01",
  "date_to": "2026-06-22",