Skip to main content
Glama
Meta Ads Engine

Meta Ads Engine

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 first for setup. The method lives in 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 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.

Related MCP server: Meta Ads MCP

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 for why.

  5. Review in Ads Manager. Set live only on an explicit yes (update_campaign status ACTIVE).

Stack

Python 3.11+, FastMCP, httpx. Runs over stdio as an MCP server. MIT licensed.

Available Tools

17 tools
create_adA

Create an ad. For the DCO-bypass flow, pass the PLACEHOLDER creative_id here, then call update_ad to swap in the real multi-variant creative. Defaults PAUSED.

Inputs: name (required), adset_id (required), creative_id (required), status, +1 more. Returns: object

create_ad_creativeA

Create an ad creative from an ad-account-scoped video.

Two modes:

  • Multi-variant (pass messages[], headlines[], descriptions[]): builds an asset_feed_spec creative. Meta shows "Primary text (1 of 5)" in Ads Manager. This is what you attach to ads via update_ad (step 4 of the flow).

  • Single-variant (pass message + headline): builds an object_story_spec creative. Use this once as the placeholder to create ads against (step 2 of the flow).

video_id must be the ad-account-scoped id returned by upload_video (NOT a page-uploaded video id). image_url is a thumbnail - fetch it fresh right before this call (CDN urls expire); get_video_thumbnail gets one.

Inputs: page_id (required), link_url (required), video_id (required), name, +8 more. Returns: object

create_adsetA

Create an ABO ad set. daily_budget_cents is in cents ($50/day = 5000).

advantage_audience is forced OFF (0) inside the targeting spec so the audience is the one you defined. For video views use optimization_goal THRUPLAY + billing_event IMPRESSIONS. For lead gen use LEAD_GENERATION.

targeting is the Meta targeting spec dict, e.g.: {"geo_locations": {"countries": ["AU"]}, "age_min": 28, "age_max": 55, "flexible_spec": [{"interests": [{"id": "...", "name": "..."}]}]} Pass an empty flexible_spec / omit interests for a broad ad set.

Inputs: name (required), targeting (required), campaign_id (required), billing_event (required), +5 more. Returns: object

create_campaignA

Create a campaign. Defaults to PAUSED - never set live without an explicit yes.

We use ABO (ad-set-level budgets), so no campaign budget is set here and is_adset_budget_sharing_enabled is forced false. objective must be one of the OUTCOME_* values. special_ad_categories (e.g. ["HOUSING","EMPLOYMENT","CREDIT"]) only when the account requires it, else pass none / [].

Inputs: name (required), objective (required), status, account_id, +1 more. Returns: object

get_account_pagesA

List the Facebook Pages promotable on this ad account.

Returns page id + name. Use the page id for object_story_spec / asset_feed_spec when building creatives. Falls back to META_AD_ACCOUNT_ID if account_id is omitted.

Inputs: account_id. Returns: object

get_ad_accountsA

List the ad accounts the token can access (id, name, currency, status).

Inputs: no named parameters. Returns: object

get_ad_creativesC

List ad creatives on the account (id, name, status).

Inputs: limit, account_id. Returns: object

get_adsC

List ads on the account, optionally filtered to one ad set.

Inputs: limit, adset_id, account_id. Returns: object

get_adsetsB

List ad sets on the account, optionally filtered to one campaign.

Inputs: limit, account_id, campaign_id. Returns: object

get_campaignsC

List campaigns on the account (id, name, objective, status, budgets).

Inputs: limit, account_id. Returns: object

get_insightsA

Read performance. level is one of account/campaign/adset/ad. date_preset e.g. today, yesterday, last_7d, last_14d, last_30d, maximum. Returns spend, reach, clicks, ctr, cpc, cpm and the actions breakdown.

Inputs: level, limit, fields, account_id, +1 more. Returns: object

get_video_thumbnailA

Fetch fresh thumbnail urls for a video. Meta CDN thumbnail urls expire fast, so call this immediately before create_ad_creative and use the returned uri as image_url. Returns the thumbnails list; the one with is_preferred=true is the pick.

Inputs: video_id (required). Returns: object

search_interestsA

Search targetable interests by name. Returns id + name + audience_size for each, which you load into a flexible_spec interest stack on the interest ad set.

Inputs: query (required), limit, account_id. Returns: object

update_adA

Update an ad. Swapping creative_id to a multi-variant creative here bypasses the DCO check (error 1885998) that blocks direct creation - this is step 4 of the flow.

Inputs: ad_id (required), name, status, creative_id. Returns: object

update_adsetA

Update an ad set (status, daily budget in cents, name).

Inputs: adset_id (required), name, status, daily_budget_cents. Returns: object

update_campaignA

Update a campaign. Pass status ACTIVE to launch (get an explicit yes first), PAUSED to pause, DELETED to remove.

Inputs: campaign_id (required), name, status. Returns: object

upload_videoA

Upload a local video file to the ad account. Returns {"id": "<video_id>"} - the ad-account-scoped video id you pass to create_ad_creative.

file_path is an absolute path to a local .mp4 (or similar). For large files Meta also supports a chunked/resumable flow; this does a straight multipart upload, which is fine for typical ad videos.

Inputs: file_path (required), name, account_id. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 17 tools

    Disambiguation5/5

    Each tool targets a distinct action on a specific resource (campaign, ad set, ad, creative, account, page, video, interest). The descriptions clearly differentiate between creating an ad versus updating it for DCO bypass, and between single-variant and multi-variant creatives.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern in snake_case (e.g., create_campaign, get_insights, upload_video). No mixing of conventions or irregular verbs.

    Tool Count4/5

    With 17 tools, the set is slightly above the typical well-scoped range (3-15) but still reasonable for an ad platform covering campaign, ad set, ad, creative, video, interests, insights, and account management. Each tool serves a clear purpose.

    Completeness4/5

    The tool surface covers the core CRUD lifecycle for campaigns, ad sets, and ads, plus creative creation, video upload, interest search, and insights. Minor gaps include lack of delete operations for ads and ad sets (only campaign supports DELETED) and no tool to retrieve a single resource by ID.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      A Windows-ready MCP server to manage Meta Ads with Claude Code, providing ad creation, targeting checks, diagnostics, and safety gates for supervised ad operations.
      1
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      A Model Context Protocol server that lets AI assistants run your Meta Ads end to end — launch campaigns, upload creatives, update budgets, and dig into performance through natural conversation. Works across Facebook, Instagram, and other Meta surfaces.
      Business Source 1.1
    • F
      license
      Not graded
      quality
      D
      maintenance
      A comprehensive MCP server for managing and analyzing Meta Ads (Facebook/Instagram) with over 80 natural-language tools for AI agents like Claude Desktop.
      -
    • A
      license
      A
      quality
      D
      maintenance
      MCP server to manage Meta Ads (Facebook/Instagram) campaigns, ad sets, insights, and audiences from Claude Code using natural language.
      9
      MIT