{
  "markdown": "<div align=\"center\">\n\n# ZuckerBot\n\n**The Meta Ads toolkit for AI agents.**\n\nAudit 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.\n\n[![npm version](https://img.shields.io/npm/v/zuckerbot-mcp?style=flat-square&color=CB3837)](https://www.npmjs.com/package/zuckerbot-mcp)\n[![License: MIT](https://img.shields.io/badge/license-MIT-green?style=flat-square)](./LICENSE)\n[![MCP Registry](https://img.shields.io/badge/MCP_Registry-io.github.Crumbedsausage/zuckerbot-8A2BE2?style=flat-square)](https://github.com/modelcontextprotocol/servers)\n[![GitHub stars](https://img.shields.io/github/stars/DatalisHQ/zuckerbot?style=flat-square)](https://github.com/DatalisHQ/zuckerbot/stargazers)\n\n```json\n{\n  \"mcpServers\": {\n    \"zuckerbot\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"zuckerbot-mcp\"],\n      \"env\": { \"ZUCKERBOT_API_KEY\": \"zb_live_your_key_here\" }\n    }\n  }\n}\n```\n\n[Get API Key (free)](https://zuckerbot.ai/get-started) · [npm](https://www.npmjs.com/package/zuckerbot-mcp) · [Docs](https://zuckerbot.ai/docs) · [Website](https://zuckerbot.ai)\n\n</div>\n\n---\n\n## Why ZuckerBot?\n\nYour agent already writes code, manages files, and searches the web. It should manage your ads too.\n\nZuckerBot 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.\n\n**What agents can do with ZuckerBot:**\n- **Audit your ad account in one message** — spend flagged for review, creative fatigue, opportunity score, prioritised action items (free tier included)\n- Pull campaign performance and spot what's working\n- Analyse ad creatives and recommend what to test next\n- Build and launch campaigns with targeting and budget\n- Create custom and lookalike audiences\n- Set up server-side conversion tracking (CAPI)\n- Research competitors, reviews, and market benchmarks\n- Generate ad creative briefs and copy\n\n## How it works\n\n```\nYou ↔ Your Agent (Claude, ChatGPT, OpenClaw, Cursor, etc.)\n                  ↕\n            ZuckerBot MCP\n                  ↕\n         Meta Marketing API\n```\n\nZuckerBot handles the Meta API complexity. Your agent handles the conversation. You make the decisions.\n\n## Install\n\n### Claude Desktop\n\nAdd to `claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"zuckerbot\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"zuckerbot-mcp\"],\n      \"env\": { \"ZUCKERBOT_API_KEY\": \"zb_live_your_key_here\" }\n    }\n  }\n}\n```\n\n### OpenClaw\n\nAdd to your MCP config:\n\n```json\n{\n  \"mcpServers\": {\n    \"zuckerbot\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"zuckerbot-mcp\"],\n      \"env\": { \"ZUCKERBOT_API_KEY\": \"zb_live_your_key_here\" }\n    }\n  }\n}\n```\n\n### Cursor / Windsurf / Any MCP Client\n\nSame config pattern. ZuckerBot works with any client that supports the Model Context Protocol.\n\n### Remote MCP (no install)\n\nDon't want to run anything locally? `https://zuckerbot.ai/api/mcp` is a hosted Streamable HTTP endpoint serving the same tools.\n\n- **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.\n- **Claude Code:**\n\n```bash\nclaude mcp add --transport http zuckerbot https://zuckerbot.ai/api/mcp --header \"Authorization: Bearer zb_live_...\"\n```\n\n- **Any Streamable HTTP client** — point it at `https://zuckerbot.ai/api/mcp` with your API key as a bearer token.\n\n### CLI (for humans)\n\n```bash\nnpm install -g zuckerbot-mcp\n\nzuckerbot preview https://your-business.com\nzuckerbot meta status\nzuckerbot create https://your-business.com --budget 5000 --objective leads\n```\n\n## Tools (50+)\n\n### Audit & Licensing (2)\n| Tool | What it does |\n|------|-------------|\n| `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 |\n| `redeem_license` | Redeem a lifetime licence code (Dealify/AppSumo) and upgrade all API keys on the account |\n\n### Setup & Account (7)\n| Tool | What it does |\n|------|-------------|\n| `quickstart` | Guided setup: check auth, show next steps, recommended tool flow |\n| `meta_status` | Check Meta connection status for your API key |\n| `list_ad_accounts` | List available Meta ad accounts and current selection |\n| `select_ad_account` | Connect a specific ad account |\n| `list_meta_pages` | List Facebook pages and current selection |\n| `select_meta_page` | Set active page for ad delivery |\n| `get_launch_credentials` | Verify all required credentials are set before launching |\n\n### Campaigns (9)\n| Tool | What it does |\n|------|-------------|\n| `preview_campaign` | Generate ad preview from a URL (no Meta account needed) |\n| `create_campaign` | Create a campaign draft with strategy, targeting, and creatives |\n| `get_campaign` | Get campaign detail, workflow state, and linked creatives |\n| `approve_campaign_strategy` | Approve tiers and creative angles for an intelligence campaign |\n| `suggest_angles` | Get proposed creative angles and audience tiers for a draft |\n| `activate_campaign` | Temporarily unavailable; intelligence campaigns remain planning-only |\n| `launch_campaign` | Launch one or all variants from a draft on Meta |\n| `pause_campaign` | Pause a campaign, ad set or ad, including spec-built Meta campaigns |\n| `resume_campaign` | Preview and explicitly activate one existing Meta campaign, ad set or ad |\n| `get_performance` | Real-time campaign metrics: spend, leads, CPL, CTR, ROAS |\n\n### Audiences (6)\n| Tool | What it does |\n|------|-------------|\n| `create_seed_audience` | Build a custom audience from hashed CAPI users |\n| `create_lookalike_audience` | Create a lookalike from any seed audience |\n| `list_audiences` | List all custom and lookalike audiences |\n| `refresh_audience` | Refresh an audience or sync latest state from Meta |\n| `get_audience_status` | Check audience size, status, and readiness |\n| `delete_audience` | Remove an audience from Meta and ZuckerBot |\n\n### Creatives (8)\n| Tool | What it does |\n|------|-------------|\n| `upload_creative` | Upload finished assets and provision paused Meta ads |\n| `get_creative_status` | Check creative generation progress |\n| `creative_analysis` | AI analysis of ad creative performance with recommendations |\n| `creative_qa` | Quality check creatives against Meta ad policies |\n| `generate_briefs` | Generate creative briefs based on performance data |\n| `generate_creatives`* | Generate ad copy and images (or AI video) |\n| `request_creative`* | Create a creative handoff package for production |\n\n\\* 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.\n\n### Conversion Tracking / CAPI (5)\n| Tool | What it does |\n|------|-------------|\n| `capi_config` | Get or update server-side conversion tracking config |\n| `capi_status` | 7-day and 30-day CAPI delivery and attribution stats |\n| `capi_test` | Send a test event through the CAPI pipeline |\n| `sync_conversion` | Send lead quality feedback to Meta's algorithm |\n| `list_pixels` | List and select Meta pixels for conversion tracking |\n\n### Reporting (2)\n| Tool | What it does |\n|------|-------------|\n| `get_campaign_insights` | Campaign / ad set / ad-level Meta performance for any campaign in the account (including non-ZuckerBot ones), with deduped lead metrics |\n| `get_account_insights` | Account-wide spend, impressions, CTR, CPM, CPC, and frequency aggregated daily or monthly |\n\n`get_campaign_insights` surfaces three distinct lead figures rather than one collapsed number, each verified against Ads Manager:\n\n| Field | Meaning |\n|-------|---------|\n| `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` |\n| `meta_leads` / `cost_per_meta_lead` | Deduped on-Meta leads (`onsite_conversion.lead_grouped`) — matches Ads Manager \"Meta Leads\" |\n| `conversion_leads` / `cost_per_conversion_lead` | CRM-qualified conversion leads (from Meta's `results` indicator `conversion_leads:conversion_lead`) — matches \"Conversion leads\". Lead-specific (0 for non-lead objectives) |\n| `actions` / `cost_per_action_type` | Full labelled arrays of `{ action_type, value }` (counts) and `{ action_type, value }` (cost in dollars) for every Meta action type |\n| `results` / `cost_per_result` | **Deprecated.** Objective-resolved result that mis-ranks mixed campaigns. Kept for back-compat — prefer `meta_result` / `cost_per_meta_result` |\n| `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` |\n\nCosts 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).\n\n### Portfolios (5)\n| Tool | What it does |\n|------|-------------|\n| `create_portfolio` | Create an audience portfolio from a template |\n| `launch_portfolio` | Temporarily unavailable; portfolios remain planning/monitoring-only |\n| `portfolio_performance` | Tier-by-tier portfolio performance breakdown |\n| `rebalance_portfolio` | Dry-run or apply budget rebalancing across tiers |\n\n### Research (3)\n| Tool | What it does |\n|------|-------------|\n| `research_reviews` | Review intelligence for any business |\n| `research_competitors` | Competitor ad analysis by industry and location |\n| `research_market` | Market intelligence and ad benchmarks |\n\n### Business Context (4)\n| Tool | What it does |\n|------|-------------|\n| `enrich_business` | Crawl a website and cache structured business context |\n| `upload_business_context` | Upload text content and extract business insights |\n| `list_business_context` | List uploaded context files and summaries |\n| `select_lead_form` | Select a lead form for campaign targeting |\n\n## Typical Agent Flow\n\n```\n0. Audit       →  audit_account (how is this account doing today?)\n1. Research    →  research_reviews + research_competitors (parallel)\n2. Preview     →  preview_campaign (show user what ads look like)\n3. Create      →  create_campaign with mode=legacy (launch-ready draft)\n4. Review      →  confirm targeting, creative, Meta connection, and budget\n5. Launch      →  launch_campaign after explicit approval\n6. Monitor     →  get_performance + creative_analysis\n7. Pause       →  pause_campaign whenever delivery must stop\n8. Optimise    →  sync_conversion + audience tools\n```\n\nEvery tool returns a `_hint` field suggesting the logical next step, so your agent always knows what to do next.\nShorthand: 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.\nMCP names include `zuckerbot_enrich_business`, `zuckerbot_upload_business_context`, `zuckerbot_get_campaign`, `zuckerbot_activate_campaign`, and `zuckerbot_create_seed_audience`.\n`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.\n`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.\n`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.\n\n## ZuckerBot vs alternatives\n\n| | ZuckerBot | Pipeboard | AdAmigo.ai | Supermetrics |\n|---|---|---|---|---|\n| **What it is** | Meta Ads toolkit for agents | Basic Meta MCP | Full ad management agent | Data extraction |\n| **Tools** | 50+ | ~20 | N/A (platform) | N/A (connectors) |\n| **Creative analysis** | ✅ AI-powered | ❌ | ✅ Platform-only | ❌ |\n| **CAPI support** | ✅ Full pipeline | ❌ | Partial | ❌ |\n| **Audience builder** | ✅ Seed + LAL | ❌ | ✅ Platform-only | ❌ |\n| **Works with any agent** | ✅ MCP standard | ✅ MCP standard | ❌ Locked to platform | ❌ |\n| **Price** | Free tier available | Free | $349/mo/account | $39-299/mo |\n\n## Pricing\n\n| Tier | Monthly | API Calls | Tools |\n|------|---------|-----------|-------|\n| **Free** | $0 | 1,000/mo | Read-only (performance, analysis, research, **account audit**) |\n| **Pro** | $49 + 0.1% of ad spend | 50,000/mo | All tools including campaign management |\n| **Scale** | $149 + 0.05% of ad spend | 500,000/mo | All tools + multi-account + priority rate limits |\n\nFree tier gets you started. Pro pays for itself with one optimised campaign.\n\n[Get your API key](https://zuckerbot.ai/get-started)\n\n## Lifetime deal\n\nGrabbed a ZuckerBot lifetime licence on Dealify? Codes look like `ZB-XXXXX-XXXXX-XXXXX` and stack on one account:\n\n| Codes | Tier | Ad accounts | API calls |\n|-------|------|-------------|-----------|\n| 1 | Lifetime Tier 1 | 1 | 2,500/mo |\n| 2 | Lifetime Tier 2 | 3 | 10,000/mo |\n| 3 | Lifetime Tier 3 | 10 | 30,000/mo |\n\nRedeem straight from your agent with the `zuckerbot_redeem_license` tool (\"redeem my ZuckerBot code ZB-...\") or in the browser at [zuckerbot.ai/start.html](https://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).\n\n## Example conversation\n\n> **You:** How are my Meta campaigns doing this week?\n>\n> **Agent** calls `get_account_insights` + `creative_analysis`\n>\n> **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.\n>\n> **You:** Do it.\n>\n> **Agent** calls `pause_campaign` + (budget adjustment)\n\n## Development\n\n```bash\ngit clone https://github.com/DatalisHQ/zuckerbot.git\ncd zuckerbot\nnpm install\nnpm run build\nnpm start\n```\n\n## License\n\nMIT\n\n### Activate a PAUSED spec-built campaign\n\nUse `zuckerbot_resume_campaign` (`POST /v1/meta/resume`) with the real Meta\n`campaign_id` (spec-built or external campaigns, not managed ZuckerBot drafts), optional `business_id`, and `entity_level` (`ad`, `adset`, or\n`campaign`). For an ad or ad set, include its `entity_id`.\n\n1. Call with `dry_run: true` (default). Review the returned hierarchy, account\n   currency, budgets, campaign spend cap and ad-set end dates with the user.\n   Amounts are minor currency units; a daily budget is not a total spend cap.\n2. After explicit approval, send the same target with `dry_run: false`,\n   `confirm_spend: true`, the returned `preview_hash` and a unique\n   `idempotency_key` (8–128 letters, digits, dots, underscores, colons or hyphens).\n3. For a new spec build, repeat for each intended **ad**, then **ad set**, then\n   the **campaign last**. Obtain a fresh preview for each operation. Activation\n   never cascades to other paused objects and preserves all spend controls.\n4. Use `zuckerbot_pause_campaign` to stop any of these objects. Campaign-level\n   pause accepts the real Meta campaign ID; pass `business_id` if needed.\n\nRetry the exact request/key after a transport failure. An uncertain outcome\nrequires live status inspection (or pausing) before further activation. A stored\nsuccessful response describes that operation; replay does not reactivate an\nobject paused afterwards. `ACTIVE` is configured status; Meta review, schedules,\nand parent/child status can still prevent delivery. Campaigns with more than\n100 ad sets or 100 ads require Ads Manager for this preview workflow.\n\nThe hosted MCP receives this tool when its API deployment ships. Installed local\nMCP clients require a package release containing the tool. The legacy draft launch\ntool is not used for activating objects created by the spec builder.\n",
  "bytes": 17178,
  "sha": "25452e4c3f30b495289efee4f5e68e8f3ac367d27cc203672a1eb02535284b15",
  "repo_slug": "datalishq/zuckerbot",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_datalishq_zuckerbot_zuckerbot_4743259f/readme"
}