# Meta Ads Engine

A clean-room Meta Ads MCP server plus a battle-tested media-buying playbook. It runs the front end of a Meta ads operation inside Claude Code: read the account, build campaigns, upload video creatives, launch a paused three-ad-set structure, and read performance. One Meta system-user token, no third-party auth broker.

**New here? Read [START-HERE.md](START-HERE.md) first** for setup. The method lives in [PLAYBOOK.md](PLAYBOOK.md).

## What it is

- **Our own MCP.** The server is written from scratch against the Meta Graph API (Python, FastMCP + httpx). No forked code, no vendored package, MIT licensed. It talks straight to Graph with your system-user token.
- **Our own playbook.** [PLAYBOOK.md](PLAYBOOK.md) is the Jeremy Haynes post-Andromeda method plus the exact creative-upload flow that works around Meta's DCO block. The tool code encodes the hard-won gotchas so you do not have to remember them.

## What it does

- **Read.** List ad accounts and pages, pull campaigns and ad sets and ads, read insights (spend, reach, ctr, cpc, cpm, actions).
- **Build.** Create a paused campaign, three ABO ad sets (broad, interest stack, lookalike stack), multi-variant creatives, and ads.
- **Video creatives.** Upload a local video to the ad account and build a creative from it, thumbnail handled.
- **Launch.** The `/launch` skill drives the whole build to a paused, live-ready campaign. It never sets anything live without your yes.

## What it does not do (honest)

- It does not optimise live campaigns for you. The scaling loop (duplicate, keep the no-reach ads, pull the winners) is a plan you follow, not an automation.
- It does not generate creative. It uploads and structures what you give it.
- It does not set campaigns live on its own. Everything ships PAUSED.

## Tools

| Tool | What |
|---|---|
| `get_ad_accounts` | List accessible ad accounts |
| `get_account_pages` | List promotable Pages on an account |
| `get_campaigns` / `create_campaign` / `update_campaign` | Campaign CRUD (PAUSED by default, ABO) |
| `get_adsets` / `create_adset` / `update_adset` | Ad set CRUD (budget in cents, Advantage+ audience off) |
| `create_ad_creative` / `get_ad_creatives` | Multi-variant (asset_feed_spec) or single-variant (placeholder) creatives |
| `create_ad` / `update_ad` / `get_ads` | Ad CRUD, including the DCO-bypass swap |
| `upload_video` / `get_video_thumbnail` | Ad-account video upload + fresh thumbnail |
| `get_insights` | Performance read at account/campaign/adset/ad level |
| `search_interests` | Interest search for the interest-stack ad set |

## The launch flow (how a build runs)

1. `create_campaign` (PAUSED, an OUTCOME_* objective).
2. `create_adset` x3: broad, interest stack (`search_interests` to fill it), lookalike stack. ABO budgets in cents.
3. `upload_video` per creative, `get_video_thumbnail` for a fresh thumbnail.
4. Creative upload uses the **DCO bypass**: build a single-variant placeholder creative, `create_ad` against it, then `update_ad` to swap in the real multi-variant creative. See [PLAYBOOK.md](PLAYBOOK.md) for why.
5. Review in Ads Manager. Set live only on an explicit yes (`update_campaign` status ACTIVE).

## Stack

Python 3.11+, [FastMCP](https://github.com/jlowin/fastmcp), httpx. Runs over stdio as an MCP server. MIT licensed.