Audit your ad account in one message. 50+ tools for account auditing, campaign management, creative analysis, audience building, and conversion tracking. One npx command. Works with Claude, ChatGPT, OpenClaw, Cursor, and any MCP-compatible agent.
60+ Meta Ads tools for AI agents: audits, campaign management, audiences and CAPI tracking.
Your agent already writes code, manages files, and searches the web. It should manage your ads too.
ZuckerBot gives any AI agent full Meta Ads capabilities through MCP. No dashboard, no UI to learn, no platform to log into. Your agent installs it, connects your ad account, and gets to work.
What agents can do with ZuckerBot:
Audit your ad account in one message — spend flagged for review, creative fatigue, opportunity score, prioritised action items (free tier included)
Pull campaign performance and spot what's working
Analyse ad creatives and recommend what to test next
Build and launch campaigns with targeting and budget
Create custom and lookalike audiences
Set up server-side conversion tracking (CAPI)
Research competitors, reviews, and market benchmarks
Generate ad creative briefs and copy
How it works
You ↔ Your Agent (Claude, ChatGPT, OpenClaw, Cursor, etc.)
↕
ZuckerBot MCP
↕
Meta Marketing API
ZuckerBot handles the Meta API complexity. Your agent handles the conversation. You make the decisions.
Same config pattern. ZuckerBot works with any client that supports the Model Context Protocol.
Remote MCP (no install)
Don't want to run anything locally? https://zuckerbot.ai/api/mcp is a hosted Streamable HTTP endpoint serving the same tools.
claude.ai — add it as a custom connector (Settings → Connectors → Add custom connector) and authenticate via OAuth, or pass an Authorization: Bearer zb_live_... header.
Any Streamable HTTP client — point it at https://zuckerbot.ai/api/mcp with your API key as a bearer token.
CLI (for humans)
npm install -g zuckerbot-mcp
zuckerbot preview https://your-business.com
zuckerbot meta status
zuckerbot create https://your-business.com --budget 5000 --objective leads
Tools (50+)
Audit & Licensing (2)
Tool
What it does
audit_account
Full read-only account audit: spend flagged for review against each campaign's objective, creative fatigue, opportunity score (0-100), projected CPL improvement, prioritised action items. Available on every tier — the recommended first call
redeem_license
Redeem a lifetime licence code (Dealify/AppSumo) and upgrade all API keys on the account
Setup & Account (7)
Tool
What it does
quickstart
Guided setup: check auth, show next steps, recommended tool flow
meta_status
Check Meta connection status for your API key
list_ad_accounts
List available Meta ad accounts and current selection
select_ad_account
Connect a specific ad account
list_meta_pages
List Facebook pages and current selection
select_meta_page
Set active page for ad delivery
get_launch_credentials
Verify all required credentials are set before launching
Campaigns (9)
Tool
What it does
preview_campaign
Generate ad preview from a URL (no Meta account needed)
create_campaign
Create a campaign draft with strategy, targeting, and creatives
get_campaign
Get campaign detail, workflow state, and linked creatives
approve_campaign_strategy
Approve tiers and creative angles for an intelligence campaign
suggest_angles
Get proposed creative angles and audience tiers for a draft
Refresh an audience or sync latest state from Meta
get_audience_status
Check audience size, status, and readiness
delete_audience
Remove an audience from Meta and ZuckerBot
Creatives (8)
Tool
What it does
upload_creative
Upload finished assets and provision paused Meta ads
get_creative_status
Check creative generation progress
creative_analysis
AI analysis of ad creative performance with recommendations
creative_qa
Quality check creatives against Meta ad policies
generate_briefs
Generate creative briefs based on performance data
generate_creatives*
Generate ad copy and images (or AI video)
request_creative*
Create a creative handoff package for production
* Creative image/video generation tools (generate_static_ad, generate_video_ad, get_video_ad_status, generate_creatives, request_creative) are disabled by default — enable them with ZUCKERBOT_ENABLE_CREATIVE_TOOLS=1 in your MCP config env (paid add-on coming). All creative analysis tools stay available.
Conversion Tracking / CAPI (5)
Tool
What it does
capi_config
Get or update server-side conversion tracking config
capi_status
7-day and 30-day CAPI delivery and attribution stats
capi_test
Send a test event through the CAPI pipeline
sync_conversion
Send lead quality feedback to Meta's algorithm
list_pixels
List and select Meta pixels for conversion tracking
Reporting (2)
Tool
What it does
get_campaign_insights
Campaign / ad set / ad-level Meta performance for any campaign in the account (including non-ZuckerBot ones), with deduped lead metrics
get_account_insights
Account-wide spend, impressions, CTR, CPM, CPC, and frequency aggregated daily or monthly
get_campaign_insights surfaces three distinct lead figures rather than one collapsed number, each verified against Ads Manager:
Field
Meaning
meta_result / cost_per_meta_result
Meta's authoritative deduped "Results" for any objective (Ads Manager "Results" column), with meta_result_type naming the underlying result (conversion_lead for lead campaigns, offsite_conversion.fb_pixel_complete_registration / purchase for sales). Supersedes the now-deprecated results / cost_per_result
Full labelled arrays of { action_type, value } (counts) and { action_type, value } (cost in dollars) for every Meta action type
results / cost_per_result
Deprecated. Objective-resolved result that mis-ranks mixed campaigns. Kept for back-compat — prefer meta_result / cost_per_meta_result
leads / cpl
Deprecated. Inflated surface count (action_type: lead) that double-counts the instant-form lead and its CAPI echo. Kept for back-compat — prefer meta_leads / conversion_leads
Costs are derived as spend / count; Meta's cost_per_action_type is non-additive and is never summed. The same fields roll up in summary as total_meta_result / blended_cost_per_meta_result (with meta_result_type), total_meta_leads / blended_cost_per_meta_lead, and total_conversion_leads / blended_cost_per_conversion_lead (with total_leads / blended_cpl deprecated alongside their per-row counterparts).
Crawl a website and cache structured business context
upload_business_context
Upload text content and extract business insights
list_business_context
List uploaded context files and summaries
select_lead_form
Select a lead form for campaign targeting
Typical Agent Flow
0. Audit → audit_account (how is this account doing today?)
1. Research → research_reviews + research_competitors (parallel)
2. Preview → preview_campaign (show user what ads look like)
3. Create → create_campaign with mode=legacy (launch-ready draft)
4. Review → confirm targeting, creative, Meta connection, and budget
5. Launch → launch_campaign after explicit approval
6. Monitor → get_performance + creative_analysis
7. Pause → pause_campaign whenever delivery must stop
8. Optimise → sync_conversion + audience tools
Every tool returns a _hint field suggesting the logical next step, so your agent always knows what to do next.
Shorthand: legacy create -> review -> launch -> monitor. Intelligence activation and portfolio launch are temporarily unavailable; existing Meta objects use the reviewed resume workflow below for spec-built and external campaigns.
MCP names include zuckerbot_enrich_business, zuckerbot_upload_business_context, zuckerbot_get_campaign, zuckerbot_activate_campaign, and zuckerbot_create_seed_audience.
zuckerbot_duplicate_ad duplicates one supported ad into an existing ad set in the same ad account — dry-run by default, always created PAUSED, and executes only with an explicit idempotency_key so a retry can never create the ad twice.
zuckerbot_upload_ad_asset uploads a brand-new image or video file into the connected ad account's library from a hosted https URL (Meta downloads it directly), returning the image_hash or video_id; poll zuckerbot_get_ad_asset_status until a video is processed.
zuckerbot_create_ad then builds one new creative + one new PAUSED ad from that asset in any EXISTING ad set — including live campaigns built outside ZuckerBot — with the same dry-run-first, idempotency_key-gated contract as duplication.
Grabbed a ZuckerBot lifetime licence on Dealify? Codes look like ZB-XXXXX-XXXXX-XXXXX and stack on one account:
Codes
Tier
Ad accounts
API calls
1
Lifetime Tier 1
1
2,500/mo
2
Lifetime Tier 2
3
10,000/mo
3
Lifetime Tier 3
10
30,000/mo
Redeem straight from your agent with the zuckerbot_redeem_license tool ("redeem my ZuckerBot code ZB-...") or in the browser at zuckerbot.ai/start.html. Redeeming upgrades every API key on your account — and if you don't have a key yet, one is minted for you (shown once, so save it).
Agent: You spent $2,340 across 4 campaigns this week. Your LAL campaign is crushing it at $28 CPL — that's 40% below your account average. But your broad targeting campaign is at $95 CPL and burning budget. The "customer testimonial" creative has a 3.2% CTR vs 1.1% for your product shots. I'd recommend pausing the broad campaign and shifting that budget to the LAL.
You: Do it.
Agent calls pause_campaign + (budget adjustment)
Development
git clone https://github.com/DatalisHQ/zuckerbot.git
cd zuckerbot
npm install
npm run build
npm start
License
MIT
Activate a PAUSED spec-built campaign
Use zuckerbot_resume_campaign (POST /v1/meta/resume) with the real Meta
campaign_id (spec-built or external campaigns, not managed ZuckerBot drafts), optional business_id, and entity_level (ad, adset, or
campaign). For an ad or ad set, include its entity_id.
Call with dry_run: true (default). Review the returned hierarchy, account
currency, budgets, campaign spend cap and ad-set end dates with the user.
Amounts are minor currency units; a daily budget is not a total spend cap.
After explicit approval, send the same target with dry_run: false,
confirm_spend: true, the returned preview_hash and a unique
idempotency_key (8–128 letters, digits, dots, underscores, colons or hyphens).
For a new spec build, repeat for each intended ad, then ad set, then
the campaign last. Obtain a fresh preview for each operation. Activation
never cascades to other paused objects and preserves all spend controls.
Use zuckerbot_pause_campaign to stop any of these objects. Campaign-level
pause accepts the real Meta campaign ID; pass business_id if needed.
Retry the exact request/key after a transport failure. An uncertain outcome
requires live status inspection (or pausing) before further activation. A stored
successful response describes that operation; replay does not reactivate an
object paused afterwards. ACTIVE is configured status; Meta review, schedules,
and parent/child status can still prevent delivery. Campaigns with more than
100 ad sets or 100 ads require Ads Manager for this preview workflow.
The hosted MCP receives this tool when its API deployment ships. Installed local
MCP clients require a package release containing the tool. The legacy draft launch
tool is not used for activating objects created by the spec builder.
Local ad asset uploads
Run the stdio MCP or CLI on the machine containing the files.
zuckerbot_upload_ad_asset accepts exactly one of asset_url, an absolute
file_path, or files: [{ file_path, label? }] (up to 20). Local files may be
JPG/JPEG/PNG (30 MB maximum) or MP4/MOV (4 GB maximum). The client validates all
files before a batch starts, transfers them privately in bounded chunks, and
returns per-file results in order. No manual public hosting step is needed.
Images include image_hash, original width, height, and name; videos retain
the existing processing status/polling flow. A failed batch entry does not undo
previous library uploads. Hosted MCP cannot access local paths: use a local client
or asset_url. Library uploads do not create ads or enable delivery.