# Meta Ads

> Use when creating, launching, monitoring, or troubleshooting Meta (Facebook/Instagram) ad campaigns through the Meta Ads MCP server (mcp.facebook.com/ads) or Meta's Ads CLI — campaigns, ad sets, creatives, ads, budgets, insights queries, Georgia/Tbilisi targeting, Georgian-language ads, and errors like "socket connection was closed", INTERNAL create failures, "app that is in development mode", "N…

- **Type:** Skill
- **Install:** `agentstack add skill-sepivip-meta-ads-skill-meta-ads-skill`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [sepivip](https://agentstack.voostack.com/s/sepivip)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [sepivip](https://github.com/sepivip)
- **Source:** https://github.com/sepivip/meta-ads-skill

## Install

```sh
agentstack add skill-sepivip-meta-ads-skill-meta-ads-skill
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Meta Ads (MCP-first)

## Overview

Core principle: **the Meta Ads MCP's tool contracts are NOT the Graph API you remember.** Parameter names, shapes, and field lists differ exactly where it breaks calls. Never write a call from memory — check [references/tool-contracts.md](references/tool-contracts.md) first, and when a VALIDATION error returns a "Supported fields are:" list, treat that list as the source of truth over anything you believed.

## When to use

- Launching a campaign end-to-end via MCP tools (`ads_create_campaign` → `ads_create_ad_set` → `ads_create_creative` → `ads_create_ad` → `ads_activate_entity`)
- Querying performance (`ads_get_ad_entities`, reports)
- Recovering from MCP/API errors mid-flight
- Setting up auth: official MCP (preferred, no developer app) vs Ads CLI / system-user token (headless fallback)
- NOT for: organic page posting, Instagram content management

## The launch pipeline (each step's landmine)

| Step | Tool | Landmine |
|---|---|---|
| 1. Account | `ads_get_ad_accounts` | Check `is_ads_mcp_enabled`, `is_queryable`, AND `has_payment_method` — creation without a payment method fails at delivery |
| 2. Page | `ads_get_ad_account_pages` | A Facebook Page is mandatory ad identity |
| 3. Images | `ads_creative_upload_image` | **URL-only** — cannot read local files. Local file? See troubleshooting §Images |
| 4. Campaign | `ads_create_campaign` | `buying_type` is REQUIRED (`AUCTION`). Budgets in **cents** of account currency. CBO = budget here; lifetime budget needs `campaign_stop_time` |
| 5. Ad set | `ads_create_ad_set` | `targeting` is a **JSON string**, required. NO budget fields under a CBO parent (pre-validated rejection). Hard age caps need `targeting_automation.advantage_audience: 0` |
| 6. Creative | `ads_create_creative` | **Flat params** (`page_id`, `image_hash`, `link_url`, `message`, `headline`, `call_to_action_type`) — NOT `object_story_spec` |
| 7. Ad | `ads_create_ad` | `creative` is a **JSON string** `"{\"creative_id\":\"...\"}"`; name param is `ad_name` |
| 8. Preview | `ads_get_ad_preview` | Include the returned `preview_url` as a link for the user |
| 9. Activate | `ads_activate_entity` | ONLY after explicit user confirmation. Top-down: campaign → ad set → every ad. `entity_type` is `ad_set` (underscore), not `adset` |

Everything creates PAUSED by default — that's the safety model. Build the whole structure, show previews, get the user's explicit go, then activate.

## Insights in one line

Metrics require `date_preset` (or `time_range`). Field names: `name` (not `ad_name`), `amount_spent` (not `spend`), link clicks = `actions:link_click`, cost = `cost_per_link_click` — bare `actions` is invalid. Sort = `_descending`. Full list: [references/tool-contracts.md](references/tool-contracts.md).

## Georgia quick recipes

Tbilisi radius (no city-key lookup needed):
```json
{"geo_locations":{"custom_locations":[{"latitude":41.7151,"longitude":44.8271,"radius":25,"distance_unit":"kilometer"}]},"age_min":18,"age_max":55}
```
All of Georgia: `{"geo_locations":{"countries":["GE"]}}`. Georgian text in `message`/`headline` is plain UTF-8 — works as-is. Budget is in the ad account's fixed currency (check `currency` on step 1; "$100" in a GEL account is a conversion conversation, not a relabel).

## Errors — first aid

| Symptom | Do |
|---|---|
| "socket connection was closed unexpectedly" | Retry once — transient, common on first call after idle |
| INTERNAL error on a create, `is_retryable: false` | **List entities first** to check it wasn't created server-side, then retry once. Never blind-retry a create |
| VALIDATION "Unsupported field(s)" | The error's "Supported fields are:" list is authoritative — fix and retry |
| "This tool is new and is being gradually rolled out" | Feature-gate per account (e.g. `ads_get_ig_accounts`). Work without it; note the limitation |
| "app that is in development mode" / token permission walls / "prohibited from advertising" | [references/troubleshooting.md](references/troubleshooting.md) |

Full playbook with the worked end-to-end example: [references/launch-playbook.md](references/launch-playbook.md).

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [sepivip](https://github.com/sepivip)
- **Source:** [sepivip/meta-ads-skill](https://github.com/sepivip/meta-ads-skill)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-sepivip-meta-ads-skill-meta-ads-skill
- Seller: https://agentstack.voostack.com/s/sepivip
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.