---
name: gentic-meta
description: "Give your AI agent control of your Meta ads. Browse accounts, analyze performance, create campaigns, upload creatives, and export reports — all through the Model Context Protocol."
license: MIT
metadata:
  author: gentic
  version: "1.0.0"
---

# Gentic Meta

Connect any AI agent to manage Meta advertising campaigns, ad sets, creatives, and performance reporting through the Meta Graph API — create campaigns, upload media, launch ads, and export reports — all through the Model Context Protocol.

## When to apply

- User wants to view, analyze, or compare Meta ad performance (spend, clicks, conversions, CTR, CPA).
- User wants to create Meta campaigns, ad sets, or ads — including video ads, image ads, and creative uploads.
- User wants to upload images or videos to an ad account from a public URL.
- User wants to export ad performance reports as CSV.
- User wants to browse their Meta ad account hierarchy (accounts → campaigns → ad sets → ads → creatives).
- User asks about their Facebook or Instagram ads, or needs their Facebook Page ID for ad creation.

## Tools

| Tool | Description | Cost |
|------|-------------|------|
| `create_meta_ad` | Create a new Meta video ad. All Advantage+ creative enhancements are automatically disabled. IMPORTANT: All IDs (adset_id, page_id, video_id) MUST be quoted strings, NEVER bare numbers. | 100¢ / call |
| `create_meta_adset` | Create a new Meta ad set within a campaign. Define targeting, budget, optimization, and scheduling. IMPORTANT: All IDs (campaign_id, ad_account_id, bid_amount, daily_budget) MUST be quoted strings, NEVER bare numbers. | Free |
| `create_meta_campaign` | Create a new Meta advertising campaign. Defaults to PAUSED status and OUTCOME_SALES objective. IMPORTANT: All IDs (ad_account_id, daily_budget) MUST be quoted strings, NEVER bare numbers. | Free |
| `create_meta_image_ad` | Create a new Meta static image ad. Provide image_hash (from upload_meta_image) or image_url. All Advantage+ enhancements are disabled. IMPORTANT: All IDs (adset_id, page_id) MUST be quoted strings, NEVER bare numbers. | 100¢ / call |
| `export_meta_report` | Export Meta ad performance data as a downloadable CSV. Uses Meta's Async Report API to handle large datasets. Supports campaign, adset, and ad level reports. Returns a download link (expires in 1 hour). IMPORTANT: campaign_id MUST be a quoted string. | 100¢ / call |
| `fetch_meta_ad_creatives` | Get ad creative details including copy, images, videos, and call-to-action from the Meta Graph API. IMPORTANT: All IDs MUST be quoted strings, NEVER bare numbers. | 5¢ / call |
| `fetch_meta_insights` | Get Meta ad performance insights for campaigns, ad sets, or ads. Supports date filtering, custom fields, and breakdowns. IMPORTANT: All IDs MUST be quoted strings (e.g. ids: "120239005302490769"), NEVER bare numbers — JavaScript rounds large integers. | 10¢ / call |
| `get_ad_history` | Read the org's ad mutation log. Returns one row per past ad-platform mutation (campaigns/ad sets/ads/keywords created, or status/bid/budget changed, or images/videos uploaded) across Google Ads and Meta. Use this to learn what's already been built for the brand before proposing new ads. Filters by platform, entity_type, account_id, tool_name, and timestamp range. Newest first; default limit 50, max 500. | Free |
| `get_ad_performance_trends` | Read the org's accumulated ad performance snapshots across Google Ads and Meta. Each row is a (campaign\|ad_group\|adset\|ad\|keyword\|search_term) × date_range fact: impressions, clicks, spend (micros), conversions, ctr, cpc, cpm, plus platform-specific extras. Use this to see how ads have performed over time and surface patterns the live API view alone can't (week-over-week deltas, multi-platform comparisons). Spend/cpc/cpm are in MICROS — divide by 1,000,000 for dollars. Filters by platform, account, entity, and date range. Default limit 200, max 2000. | Free |
| `get_meta_ids` | Get Meta Ad IDs hierarchically. Start with level="adaccounts" to discover accounts, then drill down: campaigns → adsets → ads → adcreatives. IMPORTANT: All IDs MUST be passed as quoted strings (e.g. "120239005302490769"), NEVER as bare numbers — JavaScript rounds large integers and the call will fail silently with a wrong ID. | Free |
| `get_meta_pages` | Get list of Facebook Pages associated with the authenticated user. Returns page IDs needed for creating ads. | Free |
| `upload_meta_image` | Upload an image to a Meta ad account for use in static image ads. Provide a public URL — we download the bytes and upload them to Meta as multipart form data. | Free |
| `upload_meta_video` | Upload a video to a Meta ad account for use in ads. | Free |

## Workflow

### 1. Start at the top of the hierarchy with `get_meta_ids`

Navigate top-down: `level: "adaccounts"` → `"campaigns"` (with `parent_id: "act_XXXXXX"`) → `"adsets"` → `"ads"` → `"adcreatives"`. Pass `date_preset` (e.g. `"last_30d"`) or `time_range` to include spend/performance inline. **Critical**: all IDs must be passed as **quoted strings** — JavaScript rounds large integers and causes silent mis-targeting. Never pass a bare number.

### 2. Pull insights with `fetch_meta_insights` (10¢/call)

Key params: `level` (`campaign`/`adset`/`ad`), `ids` as a comma-separated quoted string, and either `date_preset` OR `time_range` (never both). Add `breakdowns` like `"age,gender"` or `"platform_position"` when the user asks to slice. Default `fields` cover impressions, spend, clicks, CTR, actions, conversions, action_values — only override when the user needs something specific. Mention the 10¢ cost before running many insight calls.

### 3. Create campaigns in PAUSED state

`create_meta_campaign` defaults to `status: PAUSED` and `objective: OUTCOME_SALES`. Never un-pause automatically — always leave that to the user. Key knobs: objective (sales/traffic/awareness/engagement/leads/app), `is_campaign_budget_optimization` + `daily_budget` for CBO, bid strategy (`LOWEST_COST_WITHOUT_CAP` / `LOWEST_COST_WITH_BID_CAP` / `COST_CAP`), and `special_ad_categories` if the vertical requires it (credit, employment, housing, issues). **Budgets are in cents as quoted strings** — `"270000"` = $2,700.

### 4. Ad sets inherit or override budget

`create_meta_adset` is where targeting lives. `targeting` is a JSON object with `geo_locations`, `age_min`, `age_max`, `interests`, etc. If the parent campaign has CBO enabled, don't pass `daily_budget` on the ad set; otherwise it's required. `optimization_goal` drives delivery (`OFFSITE_CONVERSIONS`, `LINK_CLICKS`, `REACH`, etc.). Use `promoted_object` with a pixel_id + `custom_event_type` for conversion optimization. Defaults to PAUSED.

### 5. Upload media before creating ads

`upload_meta_image` returns an `image_hash` — use it with `create_meta_image_ad` (preferred over `image_url`, which re-uploads). `upload_meta_video` returns a `video_id` — use it with `create_meta_ad`. Both upload tools need `ad_account_id` + a **publicly accessible** URL (S3 pre-signed, public CDN). If the URL is private, the upload will fail — ask the user to host it publicly first.

### 6. Create ads carefully — $1/call

`create_meta_ad` (video) and `create_meta_image_ad` (static) both cost **$1 per call**, so confirm inputs before firing. Required: `adset_id`, `page_id` (from `get_meta_pages`), `ad_account_id`, `message` (body copy), `title`, `link_description`, `call_to_action_type` (`SHOP_NOW` / `LEARN_MORE` / `SIGN_UP` / `DOWNLOAD` / `BOOK_NOW` / `CONTACT_US` / `GET_QUOTE` / `APPLY_NOW`), and `call_to_action_link`. Add `url_tags` for UTM tracking. **All Advantage+ creative enhancements are automatically disabled** for full creative control. Ads default to PAUSED.

### 7. Export reports with `export_meta_report` ($1/call)

Returns a CSV download link that expires in **1 hour** — tell the user that up front and remind them if the conversation stretches. Required: `campaign_id` (ad account is auto-resolved). Key params: `level`, `date_preset`/`time_range`, `time_increment` (`"1"` daily, `"7"` weekly, `"monthly"`, `"all_days"` default), and `breakdowns` like `"age,gender,country"`. Use this over `fetch_meta_insights` when the user wants a downloadable file rather than inline results.

### 8. Present results clearly

For insights: lead with the headline (spend, CTR, top performer), show a ranked table by the metric the user cares about, and call out outliers. For campaign/ad creation: echo back the IDs you just created plus the exact objective, budget (in dollars, not cents), targeting summary, and the fact that everything is **PAUSED — needs manual activation**. For exports: show the download URL and the 1-hour expiry clearly.

## Notes

- **All IDs must be quoted strings.** JavaScript rounds large integers and causes silent mis-targeting — never pass a bare number for ad account / campaign / ad set / ad / creative IDs.
- `fetch_meta_insights` is 10¢/call. `fetch_meta_ad_creatives` is 5¢/call. `create_meta_ad`, `create_meta_image_ad`, and `export_meta_report` are **$1/call** — surface the cost before running.
- All campaigns, ad sets, and ads are created in `PAUSED` status by default. The user must manually activate them.
- Budgets are specified in **cents as quoted strings** (`"500000"` = $5,000).
- Advantage+ creative enhancements are automatically disabled when creating ads, for full creative control.
- Export report download links expire in **1 hour**. Meta Graph API v23.0.
- All tools are organization-scoped — users only see their own ad accounts.

## Tool details

- `create_meta_ad` — Create a new Meta video ad. All Advantage+ creative enhancements are automatically disabled. IMPORTANT: All IDs (adset_id, page_id, video_id) MUST be quoted strings, NEVER bare numbers.
- `create_meta_adset` — Create a new Meta ad set within a campaign. Define targeting, budget, optimization, and scheduling. IMPORTANT: All IDs (campaign_id, ad_account_id, bid_amount, daily_budget) MUST be quoted strings, NEVER bare numbers.
- `create_meta_campaign` — Create a new Meta advertising campaign. Defaults to PAUSED status and OUTCOME_SALES objective. IMPORTANT: All IDs (ad_account_id, daily_budget) MUST be quoted strings, NEVER bare numbers.
- `create_meta_image_ad` — Create a new Meta static image ad. Provide image_hash (from upload_meta_image) or image_url. All Advantage+ enhancements are disabled. IMPORTANT: All IDs (adset_id, page_id) MUST be quoted strings, NEVER bare numbers.
- `export_meta_report` — Export Meta ad performance data as a downloadable CSV. Uses Meta's Async Report API to handle large datasets. Supports campaign, adset, and ad level reports. Returns a download link (expires in 1 hour). IMPORTANT: campaign_id MUST be a quoted string.
- `fetch_meta_ad_creatives` — Get ad creative details including copy, images, videos, and call-to-action from the Meta Graph API. IMPORTANT: All IDs MUST be quoted strings, NEVER bare numbers.
- `fetch_meta_insights` — Get Meta ad performance insights for campaigns, ad sets, or ads. Supports date filtering, custom fields, and breakdowns. IMPORTANT: All IDs MUST be quoted strings (e.g. ids: "120239005302490769"), NEVER bare numbers — JavaScript rounds large integers.
- `get_ad_history` — Read the org's ad mutation log. Returns one row per past ad-platform mutation (campaigns/ad sets/ads/keywords created, or status/bid/budget changed, or images/videos uploaded) across Google Ads and Meta. Use this to learn what's already been built for the brand before proposing new ads. Filters by platform, entity_type, account_id, tool_name, and timestamp range. Newest first; default limit 50, max 500.
  - `platform` (string, enum: `google_ads` | `meta`)
  - `entity_type` (string, enum: `campaign` | `ad_group` | `adset` | `ad` | `keyword` | `negative_keyword` | `budget` | `image` | `video`)
  - `account_id` (string)
  - `tool_name` (string)
  - `since` (string)
  - `until` (string)
  - `limit` (integer)
- `get_ad_performance_trends` — Read the org's accumulated ad performance snapshots across Google Ads and Meta. Each row is a (campaign|ad_group|adset|ad|keyword|search_term) × date_range fact: impressions, clicks, spend (micros), conversions, ctr, cpc, cpm, plus platform-specific extras. Use this to see how ads have performed over time and surface patterns the live API view alone can't (week-over-week deltas, multi-platform comparisons). Spend/cpc/cpm are in MICROS — divide by 1,000,000 for dollars. Filters by platform, account, entity, and date range. Default limit 200, max 2000.
  - `platform` (string, enum: `google_ads` | `meta`)
  - `account_id` (string)
  - `entity_type` (string, enum: `campaign` | `ad_group` | `adset` | `ad` | `keyword` | `search_term`)
  - `entity_id` (string)
  - `since` (string)
  - `until` (string)
  - `limit` (integer)
- `get_meta_ids` — Get Meta Ad IDs hierarchically. Start with level="adaccounts" to discover accounts, then drill down: campaigns → adsets → ads → adcreatives. IMPORTANT: All IDs MUST be passed as quoted strings (e.g. "120239005302490769"), NEVER as bare numbers — JavaScript rounds large integers and the call will fail silently with a wrong ID.
- `get_meta_pages` — Get list of Facebook Pages associated with the authenticated user. Returns page IDs needed for creating ads.
- `upload_meta_image` — Upload an image to a Meta ad account for use in static image ads. Provide a public URL — we download the bytes and upload them to Meta as multipart form data.
  - `ad_account_id` (string, required) — Ad account ID
  - `image_url` (string, required) — Public URL of the image (e.g. AWS S3 pre-signed URL)
  - `name` (string, required) — Name/description for the image
- `upload_meta_video` — Upload a video to a Meta ad account for use in ads.
  - `ad_account_id` (string, required) — Ad account ID
  - `file_url` (string, required) — Public URL of the video file
  - `name` (string, required) — Name/description for the video

---

_This SKILL.md is generated from the live Gentic MCP manifest. Tool names, descriptions, and pricing are always current. Connect Gentic Meta at https://gentic.co/meta._