# ZuckerBot — Meta Ads MCP Server (npm · zuckerbot-mcp)

60+ Meta Ads tools for AI agents: audits, campaign management, audiences and CAPI tracking.

- Trust score: 64/100 (medium)
- Change this week: +58
- Registry status: active
- Liveness: live
- Owner verified: no
- Last scored: 2026-08-03

## Components

- remote · `zuckerbot.ai`: 38/100, [markdown](https://verifymcp.io/servers/crumbedsausage-zuckerbot/api-mcp.md), [page](https://verifymcp.io/servers/crumbedsausage-zuckerbot/api-mcp)
- npm · `zuckerbot-mcp`: 64/100 (this document), [markdown](https://verifymcp.io/servers/crumbedsausage-zuckerbot/zuckerbot-mcp.md), [page](https://verifymcp.io/servers/crumbedsausage-zuckerbot/zuckerbot-mcp)

## Channel facts

- Registry: `npm`
- Package: `zuckerbot-mcp`
- Version: `0.4.4`
- Transport: `stdio`

## Trust breakdown

How this component scores in each security and reliability category. Every signal is checked automatically from public evidence about the published package, including repeated runs of it in an isolated sandbox, and we only credit what we can confirm. Scores are 0–100 per category. Scoring method: https://verifymcp.io/docs/scoring (what has changed: https://verifymcp.io/docs/scoring/changelog)

Scored 2026-08-03.

- **Supply Chain Security**: 83/100
  - No malware found by supply-chain analysis.
  - CVE check failed: a known medium-severity CVE affects @hono/node-server 1.19.17, reached via @modelcontextprotocol/sdk > @hono/node-server. A fixed version is available.
  - No install/post-install scripts declared.
  - Only part of the dependency tree could be resolved (113 of 117), so this covers what we could see, not the whole tree.
- **Provenance & Transparency**: 45/100
  - Source repository is publicly reachable at the declared URL.
  - Provenance check failed: no build-provenance attestation is published.
  - Clear OSI-approved license (MIT).
  - Actively maintained (last published 7 days ago).
  - Disclosure check failed: no security disclosure policy was found in the source repository.
- **Schema Quality & AI Usability**: 56/100
  - AI-judged instruction clarity (good).
  - Context-footprint check failed: tool/resource definitions use about 9145 tokens (~152/item across 60 items; 60 tools + 0 resources), over budget; trim descriptions and params.
  - Usage-examples check failed: none of the tools include examples.
- **Stability & Change Management**: 27/100
  - Stability observed for 8 of 30 days with no destabilising changes; credit accrues until the full window elapses.
- **Tool Coverage**: 100/100
  - 100% of tools have a non-trivial description (not blank, and not just the tool's name).
  - 100% of tool parameters carry a description.
- **Capabilities**: 100/100
  - Implements a supported MCP spec version (2025-11-25); the latest is 2026-07-28.

## Install

### Claude

```bash
claude mcp add crumbedsausage-zuckerbot -- npx -y zuckerbot-mcp
```

### Codex

```bash
codex mcp add crumbedsausage-zuckerbot -- npx -y zuckerbot-mcp
```

### opencode

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "crumbedsausage-zuckerbot": {
      "type": "local",
      "command": [
        "npx",
        "-y",
        "zuckerbot-mcp"
      ],
      "enabled": true
    }
  }
}
```

### OpenClaw

```bash
openclaw mcp add crumbedsausage-zuckerbot --command npx --arg -y --arg zuckerbot-mcp
```

### Hermes

```yaml
mcp_servers:
  crumbedsausage-zuckerbot:
    command: "npx"
    args: ["-y", "zuckerbot-mcp"]
```

### Other

```json
{
  "mcpServers": {
    "crumbedsausage-zuckerbot": {
      "command": "npx",
      "args": [
        "-y",
        "zuckerbot-mcp"
      ]
    }
  }
}
```

## Changelog

Every change recorded for this component, newest first. Days that predate change tracking, or that we cannot explain, say so: "we were watching and nothing happened" and "we were not watching" are different claims.

### 2026-08-03 (score 64, −3)

No change was recorded against any check on this day. Supply Chain Security went from 93 to 83. Other categories moved too: Stability & Change Management rose 4.

### 2026-08-02 (score 67, +25)

- [security regression] Known CVEs: unverified → fail
- [security improvement] Malware scan: unverified → pass
- [functional improvement] Dependency health: unverified → partial

### 2026-08-01 (score 42, −9)

- [security regression] Known CVEs: fail → unverified
- [functional regression] Dependency health: partial → unverified

### 2026-07-31 (score 51, +45)

- [functional] We updated how we score, so this day's move reflects our rubric, not a change to the server

### 2026-07-30 (score 6, −40)

- [security regression] Provenance: fail → unverified
- [security regression] Known CVEs: fail → unverified
- [security regression] Install scripts: pass → unverified
- [security improvement] GHSA-frvp-7c67-39w9 no longer affects this package
- [functional regression] Dependency health: partial → unverified
- [functional regression] Maintenance: pass → unverified
- [functional regression] Security disclosure: fail → unverified
- [functional regression] Tool coverage: 100 → unverified
- [functional regression] License: pass → unverified
- [functional] Licence: MIT

### 2026-07-29 (score 46, +20)

- [security regression] GHSA-frvp-7c67-39w9 affects this package: medium
- [security regression] Known CVEs: unverified → fail
- [security regression] Provenance: unverified → fail
- [security improvement] Install scripts: unverified → pass
- [functional improvement] License: unverified → pass
- [functional improvement] Dependency health: unverified → partial
- [functional improvement] Maintenance: unverified → pass
- [functional] Licence: MIT

### 2026-07-28 (score 26, +20)

- [functional improvement] Tool coverage: unverified → 100
- [functional] First check of Schema quality: fail
- [functional] First check of Tool coverage: 100
- [functional] First check of Schema quality: fail
- [functional] First check of Schema quality: unverified

### 2026-07-27 (score 6)

First indexed and scored.

## MCP tools (60)

### `zuckerbot_quickstart` (~87 tokens)

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.

### `zuckerbot_billing_status` (~47 tokens)

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.

### `zuckerbot_audit_account` (~145 tokens)

Run a full audit of the connected Meta ad account: wasted spend detection, creative fatigue, a complete-account opportunity score (0-100 when all inputs return), and prioritised action items. Saves a shareable web report when the API key resolves to one saved business. Read-only and available on every tier — the recommended FIRST call for any new account or when a user asks 'how are my ads doing?'.

Input parameters:

- `company_name` (string): Company name used in the audit narrative. Defaults to the connected business name.
- `meta_ad_account_id` (string): Meta ad account ID to audit (format: act_XXXXX). Defaults to the connected account.

### `zuckerbot_redeem_license` (~158 tokens)

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's API keys to the new tier immediately.

Input parameters:

- `code` (string, required): Lifetime licence code in the format ZB-XXXXX-XXXXX-XXXXX

### `zuckerbot_analyse_account_history` (~168 tokens)

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.

Input parameters:

- `business_id` (string): Business ID (auto-resolved from API key if omitted)
- `include_audience_history` (boolean): Include analysis of which audiences have been targeted before
- `lookback_days` (integer): Number of days of history to analyse (default: 90)
- `target_audience` (string): Optional audience keyword to check if it has been targeted before (e.g., 'pool builders')

### `zuckerbot_recommend_campaign_structure` (~357 tokens)

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='website'. Present the recommendation to the customer for approval before proceeding.

Input parameters:

- `business_id` (string): Business ID (auto-resolved from API key if omitted)
- `constraints` (object): Optional constraints on the recommendation
- `daily_budget_aud` (number): Daily budget in AUD. If omitted, defaults to $50/day.
- `destination_url` (string): Optional landing-page URL for this campaign. Required/recommended for lead_destination='website'; overrides the business website for ad links.
- `history_digest` (string): Optional JSON string of a prior zuckerbot_analyse_account_history result. If omitted, history is pulled automatically.
- `lead_destination` (string): For objective='leads': 'meta_form' uses a Meta Instant Form (default), 'website' optimizes for the Pixel Lead event on a landing page.
- `objective` (string): Campaign objective. If omitted, defaults to 'leads' for most SMB use cases. Leads default to Meta Instant Form unless lead_destination is 'website'.
- `target_audience` (string, required): Target audience description (e.g., 'pool builders in Texas', 'plumbers in Brisbane')

### `zuckerbot_generate_campaign_brief` (~208 tokens)

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.

Input parameters:

- `additional_creative_direction` (string): Optional extra direction from the customer (e.g., 'lean into fear of missing calls')
- `approved_structure` (string): JSON string of approved campaign structure (if no session_id)
- `business_id` (string): Business ID (auto-resolved from API key if omitted)
- `session_id` (string): Architect session ID from zuckerbot_recommend_campaign_structure

### `zuckerbot_create_full_campaign` (~236 tokens)

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.

Input parameters:

- `activate` (boolean): Must remain false. Architect auto-activation is temporarily disabled; live mode creates PAUSED Meta objects only.
- `dry_run` (boolean): DEFAULT TRUE. Set to false ONLY after customer has approved the dry-run preview. Live mode creates real Meta objects.
- `meta_access_token` (string): Meta access token override (live mode only)
- `meta_ad_account_id` (string): Meta ad account ID override (live mode only)
- `meta_page_id` (string): Facebook Page ID override (live mode only)
- `session_id` (string, required): Campaign Architect session ID with approved strategy and creatives

### `zuckerbot_preview_campaign` (~104 tokens)

Generate a zero-cost campaign preview from any business URL. Scrapes the site, writes AI-generated headlines and body copy, and generates ad images — all without a Meta account or live budget. Use this as the first step to show a user what their ads could look like before committing to a full campaign.

Input parameters:

- `ad_count` (integer): Number of ad variants to generate (1-3)
- `url` (string, required): Business website URL to generate ads for

### `zuckerbot_create_campaign` (~389 tokens)

Create a new campaign draft for a business. Defaults to legacy mode, the only launch-ready path during Dealify hardening. 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.

Input parameters:

- `architect_session_id` (string): Optional Campaign Architect session ID. When provided, the intelligence strategy is loaded from the session instead of generating fresh.
- `budget_daily_cents` (integer): Daily budget in cents (e.g., 2000 = $20/day)
- `business_id` (string): Existing ZuckerBot business ID to anchor intelligence mode
- `business_name` (string): Business name (auto-detected from URL if omitted)
- `business_type` (string): Business category (e.g., 'restaurant', 'fitness', 'roofing')
- `creative_handoff` (object): Optional creative-production handoff settings
- `destination_url` (string): Optional landing-page URL override for ad links, e.g. a campaign-specific LP instead of the business homepage.
- `goals` (object): Optional business goals to guide planning
- `lead_destination` (string): For objective='leads': 'meta_form' uses a Meta Instant Form (default), 'website' uses a Meta Pixel Lead event and links ads to destination_url.
- `location` (object): Business location for geo-targeting
- `mode` (string): Campaign planning mode. Default legacy is the only launch-ready path. auto/intelligence are planning-only while multi-tier activation is disabled.
- `objective` (string): Campaign objective. 'leads' defaults to Meta Instant Form unless lead_destination is 'website', 'traffic' for website visits, 'conversions' for website actions, 'awareness' for reach. Default: traffic
- `url` (string, required): Business website URL

### `zuckerbot_enrich_business` (~118 tokens)

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.

Input parameters:

- `business_id` (string): Optional business ID override
- `force_refresh` (boolean): Re-scrape even when cached context exists
- `url` (string): Optional website URL override. Uses the stored business website when omitted.

### `zuckerbot_upload_business_context` (~125 tokens)

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.

Input parameters:

- `business_id` (string): Optional business ID override
- `content` (string, required): File content as text
- `context_type` (string): Optional hint about the type of uploaded context
- `filename` (string, required): Name of the file or document

### `zuckerbot_list_business_context` (~64 tokens)

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.

Input parameters:

- `business_id` (string): Optional business ID override

### `zuckerbot_get_campaign` (~66 tokens)

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.

Input parameters:

- `campaign_id` (string, required): ZuckerBot campaign ID

### `zuckerbot_approve_campaign_strategy` (~104 tokens)

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.

Input parameters:

- `angle_names` (array): Optional subset of creative angle names to approve
- `campaign_id` (string, required): Intelligence campaign ID
- `tier_names` (array): Optional subset of audience tier names to approve

### `zuckerbot_upload_creative` (~139 tokens)

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.

Input parameters:

- `campaign_id` (string, required): Intelligence campaign ID
- `creatives` (array, required): Creative assets to attach to the campaign
- `meta_access_token` (string): Optional Meta/Facebook access token override
- `meta_ad_account_id` (string): Optional Meta ad account ID override (format: act_XXXXX)
- `meta_page_id` (string): Optional Facebook Page ID override

### `zuckerbot_get_creative_status` (~83 tokens)

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='uploading'. Returns all_complete=true when every queued job has finished for review; intelligence activation is temporarily disabled.

Input parameters:

- `campaign_id` (string, required): Intelligence campaign ID

### `zuckerbot_activate_campaign` (~123 tokens)

Temporarily unavailable during Dealify launch hardening. Intelligence campaigns are planning-only; create a legacy-mode draft and use zuckerbot_launch_campaign for the supported live path.

Input parameters:

- `campaign_id` (string, required): Intelligence campaign ID
- `meta_access_token` (string): Optional Meta/Facebook access token override
- `meta_ad_account_id` (string): Optional Meta ad account ID override (format: act_XXXXX)
- `meta_page_id` (string): Optional Facebook Page ID override
- `tier_names` (array): Optional subset of approved tiers to activate

### `zuckerbot_suggest_angles` (~65 tokens)

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.

Input parameters:

- `campaign_id` (string, required): Campaign ID

### `zuckerbot_launch_campaign` (~278 tokens)

Launch a draft campaign on Meta (Facebook/Instagram). THIS IS THE MONEY ENDPOINT — it creates real ads on the user's Meta ad account and immediately begins spending their budget. Stored Meta credentials are auto-resolved when available. Set launch_all_variants=true to launch every creative variant as separate ads for A/B testing (Meta auto-optimizes for the winner). Always confirm the user has budget available and Meta is connected (zuckerbot_meta_status) before calling.

Input parameters:

- `campaign_id` (string, required): ZuckerBot campaign ID from the create step
- `daily_budget_cents` (integer): Override daily budget in cents
- `launch_all_variants` (boolean): Launch all creative variants as separate ads for A/B testing. Meta will auto-optimize for the winner.
- `meta_access_token` (string): User's Meta/Facebook access token. Optional if Facebook is connected on zuckerbot.ai
- `meta_ad_account_id` (string): Meta ad account ID (format: act_XXXXX). Optional if Facebook is connected on zuckerbot.ai
- `meta_page_id` (string): Facebook Page ID. Optional if Facebook is connected on zuckerbot.ai
- `radius_km` (integer): Override targeting radius in km
- `variant_index` (integer): Which creative variant to launch (0-indexed)

### `zuckerbot_pause_campaign` (~173 tokens)

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. Resume is temporarily disabled during Dealify launch hardening.

Input parameters:

- `action` (string): Pause the campaign
- `campaign_id` (string): ZuckerBot campaign ID (required when entity_level is campaign — the default)
- `entity_id` (string): Numeric Meta ad set or ad ID (required when entity_level is adset or ad)
- `entity_level` (string): What to pause: the whole campaign, one ad set, or one ad

### `zuckerbot_get_performance` (~99 tokens)

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.

Input parameters:

- `campaign_id` (string, required): ZuckerBot campaign ID

### `zuckerbot_creative_analysis` (~249 tokens)

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.

Input parameters:

- `business_id` (string): Optional business ID override
- `date_from` (string): Optional start date in YYYY-MM-DD
- `date_to` (string): Optional end date in YYYY-MM-DD
- `group_by` (string, required): Creative attribute to group by
- `include_ads` (boolean): When true, include the top 5 and bottom 5 ads by the selected metric.
- `metric` (string): Metric to rank by. Defaults to cpl.
- `min_impressions` (integer): Optional minimum impression threshold per ad
- `min_spend` (number): Optional minimum spend threshold per ad
- `summary_mode` (boolean): When true, returns a condensed narrative summary optimised for feeding into recommend_campaign_structure. Default: false.

### `zuckerbot_creative_cross_analysis` (~156 tokens)

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.

Input parameters:

- `business_id` (string): Optional business ID override
- `cross_by` (string, required): Secondary dimension to cross with
- `date_from` (string): Optional start date in YYYY-MM-DD
- `date_to` (string): Optional end date in YYYY-MM-DD
- `group_by` (string, required): Primary dimension
- `metric` (string): Metric to rank by. Defaults to cpl.
- `min_spend` (number): Optional minimum spend threshold per ad

### `zuckerbot_generate_briefs` (~174 tokens)

Generate creative production briefs based on the business's tagged ad-performance patterns. Each brief specifies hook type, visual style, copy tone, CTA, and script guidance weighted toward the top-performing creative attributes. Use after running zuckerbot_creative_analysis to know which patterns to bias toward.

Input parameters:

- `bias` (string): Optional generation bias, for example performance or exploration
- `business_id` (string): Optional business ID override
- `count` (integer): How many briefs to generate. Defaults to 5.
- `exclude_angles` (array): Optional angles or product focuses to avoid
- `font_preset` (string): Optional font preset override
- `metric` (string): Optional ranking metric. Defaults to cpl.
- `target_market` (string): Optional target market override, for example AU or US

### `zuckerbot_creative_qa` (~96 tokens)

Score proposed creative variants against the business's historical top-performing patterns. Accepts raw creative specs (copy, headline, CTA, asset URLs, frame URLs for video) and returns a pattern-match score for each. Use this before producing expensive creative assets to pre-validate concepts against what has historically worked.

Input parameters:

- `business_id` (string): Optional business ID override
- `creatives` (array, required): Creative variants to score

### `zuckerbot_create_seed_audience` (~138 tokens)

Build a Meta custom audience from hashed CAPI user data stored for a business, filtered by CRM lifecycle stage (e.g., 'lead', 'customer'). Use this as the first step to create retargeting or reactivation audiences from your own first-party CRM data.

Input parameters:

- `business_id` (string): Optional business ID override
- `lookback_days` (integer): How many days of CAPI events to include
- `min_contacts` (integer): Minimum matched contacts required before creation
- `name` (string): Optional audience name override
- `source_stage` (string, required): CRM lifecycle or source stage to seed from

### `zuckerbot_create_lookalike_audience` (~145 tokens)

Create a Meta lookalike audience from a stored seed audience. Expands a first-party seed (e.g., 'customer' stage) into a 1%, 3%, or 5% prospecting audience that Meta will target based on similarity. Typically used for the prospecting tier of an intelligence campaign.

Input parameters:

- `country` (string): Lookalike country code, such as US or AU
- `name` (string): Optional audience name override
- `percentage` (number): Lookalike percentage, typically 1, 3, or 5
- `seed_audience_id` (string, required): Stored seed audience row ID

### `zuckerbot_list_audiences` (~77 tokens)

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.

Input parameters:

- `business_id` (string): Optional business ID override

### `zuckerbot_refresh_audience` (~89 tokens)

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.

Input parameters:

- `audience_id` (string, required): Stored audience row ID

### `zuckerbot_get_audience_status` (~66 tokens)

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.

Input parameters:

- `audience_id` (string, required): Stored audience row ID

### `zuckerbot_delete_audience` (~67 tokens)

Permanently delete a stored audience from both Meta and ZuckerBot's local registry. This cannot be undone. Use when an audience is stale, was created in error, or you need to free up Meta audience slots.

Input parameters:

- `audience_id` (string, required): Stored audience row ID

### `zuckerbot_get_account_insights` (~206 tokens)

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.

Input parameters:

- `business_id` (string): Optional business ID override linked to the connected Meta ad account
- `date_from` (string, required): Start date in YYYY-MM-DD format
- `date_to` (string, required): End date in YYYY-MM-DD format
- `time_increment` (string): Whether to break the results down daily or monthly

### `zuckerbot_get_campaign_insights` (~492 tokens)

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's Ads Manager "Results" for any objective) or conversion_leads / meta_leads — not the inflated, deprecated leads / cpl (the response's metric_semantics object labels every lead field). meta_result and conversion_leads are most reliable on campaign-level, non-time-incremented queries. Adset/ad rows report their OWN status — status_scope says which entity a row's status belongs to, statuses are as of status_synced_at, and refresh=true re-syncs them; spend-by-date is authoritative for whether delivery actually happened.

Input parameters:

- `business_id` (string): Optional business ID override linked to the connected Meta ad account
- `campaign_ids` (string): Optional comma-separated Meta campaign IDs
- `date_from` (string): Optional start date in YYYY-MM-DD format. Defaults to 7 days ago.
- `date_to` (string): Optional end date in YYYY-MM-DD format. Defaults to today.
- `level` (string): Return campaign totals, ad set breakdowns, or ad breakdowns
- `limit` (integer): Maximum campaigns to return after sorting
- `refresh` (boolean): Bypass the short-lived performance cache
- `search` (string): Optional case-insensitive campaign name substring filter
- `sort` (string): Optional sort field. Plain values sort descending; prefix with '+' for ascending. One of: spend, leads, cpl, meta_leads, conversion_leads, cpcl, meta_result, cpmr, results, cpr, ctr, impressions. Pre…
- `status` (string): Optional status filter. Use active, paused, or all for the simple path, or pass legacy comma-separated values such as ACTIVE,PAUSED.
- `time_increment` (string): Optional daily or monthly time-series breakdown

### `zuckerbot_sync_conversion` (~238 tokens)

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's algorithm to find more (or fewer) people like them — improving lead quality over time. Call this from your CRM when a lead status changes.

Input parameters:

- `campaign_id` (string, required): ZuckerBot campaign ID
- `fbc` (string): Optional pre-formatted fbc cookie, forwarded raw — never hashed
- `fbclid` (string): Optional Facebook click ID; the server builds a well-formed fbc cookie from it
- `fbp` (string): Optional _fbp browser cookie, forwarded raw — never hashed. Improves match quality
- `lead_id` (string, required): Lead ID to report conversion for
- `meta_access_token` (string, required): User's Meta access token for CAPI
- `quality` (string, required): Lead quality: 'good' = converted/contacted, 'bad' = lost/unresponsive
- `user_data` (object): Optional user data to improve match rate

### `zuckerbot_research_reviews` (~126 tokens)

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.

Input parameters:

- `business_name` (string, required): Business name to research reviews for (e.g., 'Rosebud Dental Austin')
- `location` (string): Optional city/region to narrow review search (e.g., 'Austin, TX')
- `platform` (string): Review platform to search. Defaults to all.

### `zuckerbot_research_competitors` (~152 tokens)

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.

Input parameters:

- `country` (string): Optional 2-letter country code to refine Meta Ad Library results (e.g., 'US', 'AU'). Defaults to US.
- `industry` (string, required): Business industry or category (e.g., 'dental', 'online party games', 'roofing')
- `location` (string, required): City, region, or country to scope the competitor search (e.g., 'Austin, TX', 'United States')

### `zuckerbot_research_market` (~104 tokens)

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.

Input parameters:

- `industry` (string, required): Industry/business category (e.g., 'fitness', 'dental')
- `location` (string, required): City/region (e.g., 'United States')

### `zuckerbot_meta_status` (~58 tokens)

Check whether the user's Facebook/Meta account is connected to ZuckerBot. Returns connection status, connected ad accounts, and a connect URL if not yet linked. Always call this before attempting to launch a campaign to confirm Meta credentials are available.

### `zuckerbot_ad_accounts` (~102 tokens)

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.

Input parameters:

- `select_id` (string): If provided, selects this Meta ad account ID for future operations (format: act_XXXXX). If omitted, lists all available accounts.

### `zuckerbot_pixels` (~82 tokens)

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.

Input parameters:

- `select_id` (string): If provided, selects this Meta Pixel ID for conversion tracking. If omitted, lists all available pixels.

### `zuckerbot_meta_pages` (~82 tokens)

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.

Input parameters:

- `select_id` (string): If provided, selects this Facebook Page ID for future ad launches. If omitted, lists all available pages.

### `zuckerbot_lead_forms` (~109 tokens)

List Meta lead forms (Instant Forms) available on the selected Facebook Page and show which is currently selected. 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's CRM-connected form rather than creating a new one.

Input parameters:

- `select_id` (string): If provided, selects this Meta lead form ID for future lead generation launches. If omitted, lists all available forms.

### `zuckerbot_get_launch_credentials` (~69 tokens)

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.

### `zuckerbot_get_capi_config` (~123 tokens)

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.

Input parameters:

- `business_id` (string): Optional business ID override for the authenticated API key

### `zuckerbot_set_capi_config` (~297 tokens)

Update the Conversions API configuration for a business. Set stage-to-event mappings (e.g., 'lead' → Meta Lead event), enable/disable delivery, change the CRM source, currency, optimisation target, or action source. Changes take effect immediately for new CAPI events. Use zuckerbot_capi_test to verify the updated config works.

Input parameters:

- `action_source` (string): Meta Conversions API action_source. Defaults to website for CRM events
- `business_id` (string): Optional business ID override for the authenticated API key
- `crm_source` (string): CRM source label, such as hubspot
- `currency` (string): Business currency used for CAPI event values, such as USD or AUD
- `event_mapping` (object): CRM stage mapping object keyed by source stage. Stage keys are normalised (lower-cased, non-alphanumerics stripped: signup_completed → signupcompleted); inbound webhook source_stage values are normal…
- `is_enabled` (boolean): Enable or disable CAPI delivery for the business
- `optimise_for` (string): Downstream optimisation target for autonomous evaluation
- `rotate_webhook_secret` (boolean): Rotate the webhook secret on update. The new secret is returned exactly once in the response; prefer zuckerbot_rotate_webhook_secret for a dedicated rotation

### `zuckerbot_rotate_webhook_secret` (~101 tokens)

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's stored secret) in the same sitting.

Input parameters:

- `business_id` (string): Optional business ID override for the authenticated API key

### `zuckerbot_capi_status` (~79 tokens)

Get 7-day and 30-day CAPI delivery statistics for the business: total events sent, events by type (Lead/Contact/Purchase), match quality breakdown, and attribution counts. Use this to confirm CAPI is functioning and that events are being matched by Meta.

Input parameters:

- `business_id` (string): Optional business ID override

### `zuckerbot_capi_test` (~197 tokens)

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.

Input parameters:

- `business_id` (string): Optional business ID override
- `crm_source` (string): Optional CRM source label override
- `fbc` (string): Optional pre-formatted fbc cookie to verify raw passthrough
- `fbclid` (string): Optional Facebook click ID to verify fbc construction/passthrough
- `fbp` (string): Optional _fbp cookie to verify raw passthrough
- `source_stage` (string): CRM stage key to test against the mapping
- `user_data` (object): Optional user data to hash into the test payload
- `value` (number): Optional event value override

### `zuckerbot_create_portfolio` (~181 tokens)

Create a planning and monitoring-only multi-tier audience portfolio for a business from a shared template (e.g., 'Local Services', 'eCommerce') or a custom tier array. Portfolios split a proposed total budget across prospecting, retargeting, and reactivation tiers with per-tier CPA targets. Portfolio launch is temporarily disabled during Dealify hardening.

Input parameters:

- `business_id` (string): Optional business ID override
- `is_active` (boolean): Whether the portfolio should be active immediately
- `name` (string): Optional portfolio name
- `template_id` (string): Optional portfolio template ID
- `template_name` (string): Optional portfolio template name, such as 'Local Services'
- `tiers` (array): Optional custom tier array to override the template
- `total_daily_budget_cents` (integer): Total daily budget in cents

### `zuckerbot_get_portfolio` (~73 tokens)

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.

Input parameters:

- `portfolio_id` (string, required): Audience portfolio ID

### `zuckerbot_update_portfolio` (~136 tokens)

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.

Input parameters:

- `is_active` (boolean): Enable or disable the portfolio for autonomous evaluation
- `name` (string): New portfolio name
- `portfolio_id` (string, required): Audience portfolio ID to update
- `tiers` (array): Updated tier configuration. Replaces the existing tiers array.
- `total_daily_budget_cents` (integer): New total daily budget in cents (minimum 500)

### `zuckerbot_portfolio_performance` (~76 tokens)

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.

Input parameters:

- `portfolio_id` (string, required): Audience portfolio ID

### `zuckerbot_rebalance_portfolio` (~116 tokens)

Dry-run or execute a budget rebalance across portfolio tiers based on each tier's actual vs. target CPA. With dry_run=true (default) returns recommendations without making changes — useful for review before committing. With dry_run=false updates Meta ad set budgets and local records in one operation.

Input parameters:

- `dry_run` (boolean): When true, returns recommendations without applying changes
- `meta_access_token` (string): Optional Meta access token override for ad set budget updates
- `portfolio_id` (string, required): Audience portfolio ID

### `zuckerbot_launch_portfolio` (~123 tokens)

Temporarily unavailable during Dealify launch hardening. Portfolio planning and monitoring remain available, but new multi-tier launches must not create Meta objects. Create a legacy-mode draft and use zuckerbot_launch_campaign for the supported live path.

Input parameters:

- `meta_access_token` (string): Optional Meta/Facebook access token override
- `meta_ad_account_id` (string): Optional Meta ad account ID override (format: act_XXXXX)
- `meta_page_id` (string): Optional Facebook Page ID override
- `portfolio_id` (string, required): Audience portfolio ID to launch

### `zuckerbot_tag_creative` (~114 tokens)

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.

Input parameters:

- `ads` (array, required): One or more Meta ads to tag with creative attributes
- `business_id` (string): Optional business ID override

### `zuckerbot_send_capi_event` (~365 tokens)

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.

Input parameters:

- `business_id` (string): Optional business ID override (resolved from API key when omitted)
- `crm_source` (string): Optional CRM source label override (e.g., 'hubspot', 'salesforce')
- `email` (string): Optional contact email for identity matching
- `event_time` (string): Optional ISO 8601 event timestamp. Defaults to now.
- `fbc` (string): Optional pre-formatted Facebook click cookie (fb.1.<ms>.<fbclid>), forwarded raw — never hashed
- `fbclid` (string): Optional Facebook click ID; the server builds a well-formed fbc cookie from it
- `fbp` (string): Optional Facebook browser ID cookie (_fbp), forwarded raw — never hashed. Improves match quality for every event
- `first_name` (string): Optional first name for identity matching
- `last_name` (string): Optional last name for identity matching
- `lead_id` (string): Optional ZuckerBot lead ID for attribution matching
- `meta_lead_id` (string): Optional Meta Lead Gen Ads lead ID for attribution matching
- `phone` (string): Optional contact phone for identity matching
- `source_stage` (string, required): CRM stage key to map to a Meta event (e.g., 'lead', 'salesqualifiedlead', 'customer')
- `value` (number): Optional event value override in major currency units

### `zuckerbot_create_campaign_from_spec` (~533 tokens)

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: campaign {name, objective OUTCOME_LEADS|OUTCOME_SALES, budget {type CBO_DAILY, amount, bid_strategy HIGHEST_VOLUME|LOWEST_COST_WITHOUT_CAP|COST_CAP}, special_ad_categories}, ad_sets [{name, conversion_location WEBSITE|INSTANT_FORM, attribution {click_days 1|7, view_days 0|1}, targeting {geo — ARRAY of 2-letter country codes e.g. ["AU"], age_min, advantage_audience, excluded_custom_audiences}, placements {mode MANUAL|ADVANTAGE_PLUS, exclude}; WEBSITE additionally: pixel_id, optimisation_event {type CUSTOM_CONVERSION, id}|{type STANDARD, event e.g. Lead}, performance_goal MAXIMISE_CONVERSIONS (the Ads Manager label, not the Graph enum); INSTANT_FORM instead: lead_form_id — the Meta instant form on the connected Page (no pixel_id, no optimisation_event, and its ads take NO final_url — the form is the destination; single-image creative, no multi-ratio placement customisation)}], ads [{name, asset {type IMAGE_SET, refs {1x1,4x5,9x16 — https URLs or uploaded image hashes}}|{type VIDEO, ref — pre-uploaded Meta video id}|{type EXISTING_AD, ad_id — clones that ad's image/video asset from the SAME ad account; copy, CTA and destination come from THIS spec}, primary_text, headline, description, cta, final_url (WEBSITE ad sets only), ad_set_name?}]. EXISTING_AD specs need Meta credentials even for dry_run (the source asset is read from Meta). Use zuckerbot_list_custom_conversions to find custom conversion ids.

Input parameters:

- `business_id` (string): Optional business ID override for the authenticated API key
- `dry_run` (boolean): true = return the resolved Graph payloads without creating anything. Strongly recommended before a real build
- `spec` (object, required): The declarative campaign spec (see tool description for the shape)

### `zuckerbot_list_custom_conversions` (~68 tokens)

List the custom conversions on the connected ad account: id, name, rule, source event and pixel. Use this to find the custom conversion id a campaign spec's optimisation_event should reference.

Input parameters:

- `business_id` (string): Optional business ID override for the authenticated API key

### `zuckerbot_create_custom_conversion` (~150 tokens)

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.

Input parameters:

- `business_id` (string): Optional business ID override for the authenticated API key
- `custom_event_type` (string): Source event type, defaults to OTHER
- `name` (string, required): Display name for the custom conversion
- `pixel_id` (string, required): Pixel (event source) the conversion is based on
- `rule` (object): Optional Meta rule object, e.g. {"url":{"i_contains":"/thank-you"}}

## Diagnostics

Captured diagnostic sections: Provenance, Vulnerabilities, Dependencies. The full working is on the page: https://verifymcp.io/servers/crumbedsausage-zuckerbot/zuckerbot-mcp#diagnostics

## Score history

- 2026-08-03: 64
- 2026-08-02: 67
- 2026-08-01: 42
- 2026-07-31: 51
- 2026-07-30: 6
- 2026-07-29: 46
- 2026-07-28: 26
- 2026-07-27: 6

## Links

- npm package: https://www.npmjs.com/package/zuckerbot-mcp
- Socket report: https://socket.dev/npm/package/zuckerbot-mcp
- Repository: https://github.com/DatalisHQ/zuckerbot
- Website: https://zuckerbot.ai/
- Changelog RSS feed: https://verifymcp.io/servers/crumbedsausage-zuckerbot/zuckerbot-mcp/changelog.xml
- Changelog JSON feed: https://verifymcp.io/servers/crumbedsausage-zuckerbot/zuckerbot-mcp/changelog.json
- HTML version of this page: https://verifymcp.io/servers/crumbedsausage-zuckerbot/zuckerbot-mcp