ZuckerBot — Meta Ads MCP Server

Upload a NEW image or video file into the connected Meta ad account

Show the current ZuckerBot authentication mode (demo vs authenticated), the Free/Pro/Scale and Lifetime billing tiers, setup instructions if not yet configured, and the recommended tool flow from audit → campaign → launch → performance. Returns status, recommended_flow steps, pricing info, and setup guide for unauthenticated users. Call this first in any new session to orient the agent.

Check your current ZuckerBot billing tier, API call usage this month, remaining quota, and overage costs. Use this when a user asks about their plan or usage limits.

Generate a brand-aware 1080×1080 static ad image. Automatically injects brand context (logo, colors, brand name, value props, social proof) from the business profile when business_id is provided — no need to pass brand data manually. Templates: stat_hook (statistic + supporting copy), pain_headline (bold headline + benefit bullets), testimonial (customer quote + portrait), feature_showcase (product + benefits). Returns a public image URL and QA scores. Present the image to the customer for approval; to generate more variants, call again with different parameters.

Generate a video ad through ZuckerBot

Check the status of an async video ad generation job. Returns current status and, when complete, the final video URL. Also surfaces Meta ad review status and rejection reasons if the ad has been submitted to Meta. Poll every 30 seconds until status is

Dispatch a creative production request for an approved intelligence campaign. If a creative-production webhook is configured on the business, ZuckerBot generates full video scripts and fires the production payload. Use this when you want ZuckerBot to handle creative production end-to-end rather than uploading your own assets.

Generate standalone ad creative variants (images or video) using AI image and video models. Works independently of campaign creation — useful for quick mockups, creative testing, or building assets before attaching them to a campaign. If the description mentions video, reels, UGC, or TikTok, the tool auto-routes to the video model.

Run a full audit of the connected Meta ad account: spend flagged for review against each campaign

Redeem a ZuckerBot lifetime licence code (format ZB-XXXXX-XXXXX-XXXXX) purchased on Dealify or AppSumo. Each code activates the plan it was purchased for: Tier 1 (1 ad account, 2,500 calls/mo), Tier 2 (3 accounts, 10K calls/mo) or Tier 3 (10 accounts, 30K calls/mo). Codes also stack additively on one account up to Tier 3 — e.g. two Tier 1 codes = Tier 2. Redeeming upgrades ALL of the account

Analyse the historical ad performance for a business. For accounts WITH history: returns aggregated metrics by audience type, top performing creatives, and comparable CPL ranges. For NEW accounts with NO history: returns is_cold_start=true with industry benchmarks. Use this as the FIRST step in campaign planning — feed the result into zuckerbot_recommend_campaign_structure.

Generate a campaign structure recommendation: audience tiers, budget allocation, creative mix. For accounts WITH history: uses Claude to generate data-driven recommendations. For NEW accounts (cold start): generates conservative defaults from industry benchmarks + safe 2-tier structure (broad 60% / interest 40%). Always returns comparable_historical_cpl with source (account_history or industry_benchmarks) and a disclaimer — NEVER a CPL projection. Lead campaigns default to Meta Instant Form; for leads driving to a website landing page rather than Meta Instant Form, set lead_destination=

Check Meta

Generate a detailed creative brief from an approved campaign structure. SAFE — pure function, no Meta API calls, no money spent. Automatically pulls brand context and historical creative patterns (or uses brand context alone for cold-start accounts). Returns per-slot creative directions: for static ads, specific ad template + headline/body/CTA + hero image prompt; for video ads, hook concept + voiceover direction + visual style. After brief is generated, present it to the customer, then call zuckerbot_generate_static_ad / zuckerbot_generate_video_ad for each slot.

Build a complete PAUSED Meta campaign from an approved Campaign Architect session. IMPORTANT: dry_run defaults to TRUE. When dry_run=true, returns the exact campaign structure that WOULD be created without calling Meta — safe, free, no side effects. Present this to the customer first. Only set dry_run=false after explicit customer approval. When dry_run=false, creates Meta objects in PAUSED state for review; Architect auto-activation is temporarily disabled. Generated videos get linked for rejection tracking automatically.

Generate a zero-cost campaign preview from any business URL. Scrapes the site and writes AI-generated headlines and body copy, using the site

Create a new campaign draft for a business. Defaults to legacy mode, which is the only launch-ready path. Intelligence mode remains available for planning only and cannot be activated. This tool does not spend money or create anything on Meta; review the draft, then use zuckerbot_launch_campaign.

Crawl a business website and extract structured intelligence used by campaign planning: company description, services, pricing signals, testimonials, location data, and brand tone. Run this before creating a campaign when the business has not been enriched yet, or use force_refresh after a website update to refresh stale context.

Upload a text document (ad performance data, brand guidelines, customer data, sales data, or competitor analysis) so ZuckerBot can extract structured planning insights from it. Accepts raw text content — not binary files. Use this when the business has existing performance data or brand docs that should inform campaign strategy.

List all uploaded business-context files for a business along with their extracted summaries. Use this to confirm what planning documents are loaded before creating a campaign, or to check whether a previous upload was processed successfully.

Fetch the full details of a ZuckerBot campaign by ID: intelligence workflow state, approved strategy, stored creatives, audience tier executions, and performance status. Use this to inspect a campaign at any stage of the lifecycle.

Approve the AI-generated intelligence strategy for a campaign, optionally narrowing to specific audience tiers and creative angles. This locks in the plan before creative production starts. Required before calling zuckerbot_request_creative or zuckerbot_upload_creative.

Upload finished creative assets (images or videos) to an approved intelligence campaign. ZuckerBot queues the Meta upload and ad-creation jobs asynchronously, then polls until they complete or the polling window expires. Use this when you have your own creative assets ready. INTELLIGENCE CAMPAIGNS ONLY — to add a new creative file to any other EXISTING campaign (including live ones built outside ZuckerBot), use zuckerbot_upload_ad_asset + zuckerbot_create_ad instead.

Check the asynchronous upload queue for an intelligence campaign to see if Meta ad-creation jobs are complete. Poll this after zuckerbot_upload_creative when the initial response shows creative_status=

Not currently available. Intelligence campaigns are planning-only; create a legacy-mode draft and use zuckerbot_launch_campaign for the supported live path.

Return only the creative angles and audience tiers for a campaign draft — a lightweight alternative to zuckerbot_get_campaign when you need just the strategy summary without the full campaign payload, stored creatives, or tier execution details.

Launch a draft campaign on Meta (Facebook/Instagram). THIS IS THE MONEY ENDPOINT — it creates real ads on the user

Activate ONE existing PAUSED Meta campaign, ad set or ad in a spec-built or external campaign in the selected business ad account. Managed ZuckerBot draft/intelligence campaigns retain their separate launch workflow. This can spend money. Default dry_run=true returns current hierarchy, budgets in account-currency minor units, spend cap, schedules and preview_hash. Review these with the user; execute only with their explicit approval using dry_run=false, confirm_spend=true, that preview_hash and a unique idempotency_key. For a spec-built campaign, activate intended ads first, then ad sets, then the campaign LAST, obtaining a fresh preview for each object. No cascade: other paused objects stay paused. Does not change budgets, dates, targeting or create replacements. A changed preview requires a fresh review. Retry the SAME request/key after a transport failure; unknown outcomes require live status inspection or pausing before further activation. Use zuckerbot_pause_campaign to stop delivery.

Pause delivery at any level: a whole campaign (default), one ad set, or one ad — set entity_level and pass the matching id. Pausing stops delivery and spend immediately while leaving the object in Meta, and the response reports the prior status. Use adset/ad level to stop an underperformer WITHOUT killing the winners in the same campaign. To resume a reviewed Meta object, use zuckerbot_resume_campaign with its real Meta IDs and a fresh preview.

Fetch real-time performance metrics for a ZuckerBot campaign. Legacy campaigns return a flat metrics summary (impressions, clicks, leads, spend, CPL, CTR). Intelligence campaigns additionally return tier-by-tier and ad-by-ad Meta insights, daily breakdowns, CAPI attribution totals, and AI-recommended next actions. Use this to monitor an active campaign or to diagnose underperformance.

Analyse creative performance patterns for a business by grouping ads by hook type, visual style, product focus, setting, CTA type, copy tone, or opening element. Returns average CPL/CTR/CPC/frequency per group, per-group trend direction, a structured insight object with recommendations, and can optionally include the top and bottom individual ads for the selected metric. Use this before generating new briefs to inform the creative strategy.

Cross two creative dimensions to find winning combinations. Example: hook_type × visual_style can reveal that curiosity + ugc outperforms pain_point + stock. Returns a performance matrix, best and worst combinations, and an actionable insight string.

Generate creative production briefs based on the business

Score proposed creative variants against the business

Build a Meta custom audience from hashed CAPI user data stored for a business, filtered by CRM lifecycle stage (e.g.,

Create a Meta lookalike audience from a stored seed audience. Expands a first-party seed (e.g.,

List all stored Meta audiences for a business: seed audiences, lookalike audiences, sizes, delivery statuses, and CAPI source details. Use this to see what audiences are available before launching a campaign, or to find audience IDs for refresh and delete operations.

Rebuild a stored audience from fresh data. For seed audiences: re-hashes the latest CAPI events for the source CRM stage. For lookalike audiences: syncs the current size and delivery status from Meta after the seed refreshes. Use this when CAPI has received new events since the audience was last built.

Fetch the current Meta delivery status, size, and readiness for a stored audience. Updates the local audience registry row. Use this to check if an audience is large enough to use in a campaign before launch.

Permanently delete a stored audience from both Meta and ZuckerBot

Fetch historical Meta ad account performance for a connected business over a date range. Returns spend, clicks, impressions, CTR, CPM, CPC, and frequency aggregated daily or monthly. AUTO-PAGINATES the full requested range; the response includes row_count, covered {date_from, date_to} (the range actually returned) and truncated — truncated=true means the fetch stopped early: narrow the date range and re-request rather than trusting totals. Note zero-delivery days are legitimately absent from data, so also compare covered against the range you asked for. Useful for top-level budget reporting and month-over-month trend analysis without opening Ads Manager.

Query campaign, ad set, or ad-level performance for any campaign in the connected Meta ad account — including campaigns not created by ZuckerBot. Tags each row with is_zuckerbot so you can benchmark ZuckerBot campaigns against manually managed ones. Supports date range filtering, campaign name search, status filters, time-series breakdowns, and multi-column sorting. For deduped truth use meta_result / cost_per_meta_result (Meta

Send downstream conversion quality feedback to Meta via CAPI. When a ZuckerBot-sourced lead converts (sale, appointment, qualified call) or bounces (uncontactable, bad fit), reporting it here teaches Meta

Fetch review intelligence for a business by name. Searches Google and Yelp to surface star rating, review count, recurring sentiment themes, and standout customer quotes that can be used directly in ad copy. Use before creating a campaign to identify proof points and objection-handling angles.

Scrape Meta Ad Library and search the web to analyse competitor ads in a given industry and location. Returns competitor positioning, common creative hooks, and exploitable gaps. Use before creating a campaign to benchmark against the competitive landscape and find differentiation opportunities.

Get market size, addressable audience estimates, and Meta ad benchmarks (CPL, CTR, CPM) for an industry and location. Use before creating a campaign to set realistic budget expectations and understand how large the targetable audience is. Also useful for proposals and client presentations.

Check whether the user

List Meta ad accounts available to the connected user and show which is currently selected for launches and reporting. Optionally select an ad account by providing select_id — this clears the stored page selection so you can pick a matching page. Call this during setup or when switching between multiple ad accounts.

List Meta Pixels available on the currently selected ad account and show which is currently selected for conversion tracking. Optionally select a pixel by providing select_id. The selected pixel is used for all future conversion tracking and CAPI attribution.

List Facebook Pages available to the connected Meta account and show which is currently selected for ad delivery. Optionally select a page by providing select_id. The selected page is used as the ad identity for all future launches.

Create ONE new ad (a new creative built from a declared asset) in an EXISTING ad set of the connected ad account — the way to add a brand-new image or video into a campaign that is already running, including ZuckerBot-external campaigns. Dry-run by default: returns the exact object plan (1 new creative + 1 new ad) without creating anything; pass execute: true plus an idempotency_key to build it. The ad is ALWAYS created PAUSED — activating it is a separate deliberate action. Optionally pass images (1–10 labeled image_hash/image_url/file_path entries); multiple images use placement customisation with a dry-run placement_table. Local file_path works only in local stdio/CLI and uploads automatically on execute. Omitted placements are inferred from original 1:1, 4:5 or 9:16 dimensions; remaining ad-set placements use square or the first image. Explicit placements use platform.position or platform.position.device (e.g. facebook.feed.mobile). Every target placement/device is assigned once, including newer placements returned by Meta. No ad-set settings are changed. Multiple images currently require final_url and cta. Asset: IMAGE (image_hash from zuckerbot_upload_ad_asset, or image_url — uploaded to the library automatically) or VIDEO (video_id from zuckerbot_upload_ad_asset, which must be processed/ready; thumbnail auto-derived, thumbnail_url overridable). Destination: exactly one of final_url (website) or lead_form_id (instant form — requires cta). VIDEO ads carry their link in the call_to_action, so VIDEO + final_url also requires cta. To clone an ad that already exists in the account instead, use zuckerbot_duplicate_ad.

List Meta lead forms (Instant Forms) available on the selected Facebook Page and show which is currently selected. Listing is a pure read scoped to the selected Page (page_scope: selected_page) and never changes the selection. If the list is truncated, re-call with the returned next_cursor as after. Optionally select a form by providing select_id to persist it for future lead generation campaign launches. Use this before launching a leads-objective campaign so ZuckerBot reuses the business

Export lead submissions from a Meta instant form (lead form) for a date range: each lead

Resolve and validate all stored Meta launch credentials for the authenticated user: access token, ad account, page, and pixel. Reports whether autonomous launch (no credential params needed at launch time) is possible. Call this after completing the setup sequence to confirm everything is ready before launching a campaign.

Fetch the current Conversions API configuration for a business: whether CAPI delivery is enabled, CRM source, currency, stage-to-event mappings, action source, and webhook URL. Use this before configuring CAPI to see what is already set, or to audit the current event mapping. The webhook secret is write-only: reads return webhook_secret_set and webhook_secret_last4, never the full value — use zuckerbot_rotate_webhook_secret to mint a new one.

Update the Conversions API configuration for a business. Set stage-to-event mappings (e.g.,

Rotate the Conversions API webhook secret for a business. The new secret is returned exactly once, in this response only — every other read shows just webhook_secret_set and webhook_secret_last4. The old secret stops authenticating immediately, so update the system that signs your inbound webhooks (for example your CRM workflow

Get 7-day and 30-day CAPI delivery statistics for the business: total events sent, events by type (Lead/Contact/Purchase), match quality and identifier-coverage breakdowns, meta_events_received (Meta

Send a synthetic CAPI test event through the business configuration to verify the full pipeline: stage mapping, hashing, and Meta Graph API delivery. Logs as a test event (does not affect real attribution). Use after setting up or updating CAPI config to confirm events are flowing.

Create a planning and monitoring-only multi-tier audience portfolio for a business from a shared template (e.g.,

Fetch the configuration and current performance snapshot for an audience portfolio by ID. Returns tier definitions, budget allocations, CPA targets, and any existing performance data. Use this to inspect a portfolio for planning, monitoring, or rebalancing an already-active portfolio.

Update the name, total daily budget, active status, or tier configuration of an existing audience portfolio. Changes to budget and tiers take effect on the next autonomous evaluation cycle. Use this to adjust a portfolio without relaunching all tiers.

Fetch live Meta performance and downstream CAPI attribution for a launched audience portfolio. Returns enriched tier rows with ad breakdowns, daily metrics, CPA vs. target comparisons, and autonomous evaluation outputs. Use this to monitor a running portfolio and decide whether to rebalance.

Dry-run or execute a budget rebalance across portfolio tiers based on each tier

Not currently available. Portfolio planning and monitoring remain available, but new multi-tier launches do not create Meta objects. Create a legacy-mode draft and use zuckerbot_launch_campaign for the supported live path.

Tag Meta ads with creative attributes (hook type, visual style, product focus, CTA type, copy tone, setting) by providing ad metadata and optional asset URLs. ZuckerBot uses Claude vision to analyze the creative and store structured tags. These tags feed the zuckerbot_creative_analysis pipeline. Run this after launching new ads to keep the creative intelligence database current.

Manually send a Conversions API event for a business contact/lead. Useful for debugging CAPI pipelines, testing stage mappings with real user data, or sending events from custom integrations not covered by the webhook. Authenticates with the business API key OR with an x-zuckerbot-webhook-secret header if using the webhook path.

Build a complete Meta campaign VERBATIM from a declarative JSON spec — no strategy generation, no copy authoring. Everything is created PAUSED, always; launching remains a separate deliberate call. Recommended flow: send with dry_run=true first to get the fully resolved Graph API payloads without creating anything, review them, then re-send without dry_run to build. Validation failures return an errors array of per-field {path, message, kind: schema|semantic} entries — fix each path and retry. Spec shape: OPTIONAL identity {instagram_actor_id — the Instagram account

List the custom conversions on the connected ad account: id, name, rule, source event, pixel and availability (is_unavailable). A pure read of the already-bound ad account — it never binds or consumes an ad-account slot. If the list is truncated, re-call with the returned next_cursor as after. Use this to find the custom conversion id a campaign spec

Create a custom conversion on the connected ad account (requires sufficient Graph permissions on the Meta token — returns insufficient_permission if Meta refuses). Provide the pixel, a name, optionally a rule (e.g. URL contains ...) and the source event type.

Read one Meta lead form (Instant Form) in full: questions, privacy policy URL and legal content (disclaimer), locale, context card, thank-you page, follow-up action URL, status, created time and lead counts. A pure read — it never changes or persists the selected form. The form must belong to the selected Facebook Page. Find form ids with zuckerbot_lead_forms.

Read one custom conversion in full: rule, source event (event_source_id/event_source_type), category (custom_event_type), default conversion value, availability (is_unavailable) and creation time, plus mutable_fields — the only fields Meta permits updating (name, description, default_conversion_value; rule/category/source are immutable). Optionally include stats via include_stats with an explicit bounded window (default: last 30 days, capped at 90). A pure read of the already-bound ad account — it never binds or consumes an ad-account slot.

Duplicate ONE supported ad into an existing ad set in the SAME ad account. Dry-run by default: it returns the exact object plan (1 new creative + 1 new ad) without creating anything; pass execute: true plus an idempotency_key to perform it. The duplicated ad is ALWAYS created PAUSED — activating it is a separate deliberate action. Supported source shapes: static single-image creatives with an accessible image hash, and single pre-uploaded video creatives. Carousel, dynamic/catalogue, existing-post and multi-asset creatives are rejected with the unsupported feature named. A new creative is always built — creative IDs are never reused. To introduce a brand-NEW image or video file instead of reusing an existing ad

Read the stored creative attribute tags for up to 50 Meta ads in the canonical creative_attributes.v1 shape: the 17 extracted attributes (hook type, visual style, CTA type, copy tone, booleans and more), the extraction lifecycle (tag_status, error class, attempt metadata, legacy_row flag), taxonomy/prompt/model versions, asset/input fingerprints and the campaign objective family. A pure read of already-stored rows — it never triggers extraction and never spends anything. Use after zuckerbot_audit_account reports creative analysis complete, or before zuckerbot_creative_analysis to inspect individual ads.