Meta Ads

Standardized account-level performance summary for cross-platform comparison. Normalized format identical to google_ads_get_account_summary. Includes conversion_detail breakdown from both Meta actions and conversions arrays. Preferred over get_insights or get_performance_report for quick account-level overviews. Always fetches fresh data.

Retrieve change history (who changed what, and when) for a Meta ad account, or for one campaign, ad set or ad. Hopkin records Meta's activity log continuously and keeps it for 25 months, backfilling up to two years when an account is first synced, so start_date can reach well past the last 7 days. Check coverage.complete_from: if the requested window starts earlier, coverage.note says so — no events before that date does not mean nothing changed. An account synced more than 15 minutes ago is refreshed from Meta first; refresh=true forces it. Dates are UTC and end_date includes the whole day. Paginated: when nextCursor is present, call again with the same parameters plus cursor=<nextCursor>.

List Meta ad accounts with search, status filtering, single/multi-account lookup by ID, and pagination. Cached by default; pass refresh=true for latest data. Entities may optionally include recent activities.

Ad-level performance report with full funnel metrics, including video funnel (ThruPlays, 25/50/75/95/100% completions, avg watch time) for video creatives. All conversion types shown individually. Supports two grouping modes: ad_name (default, aggregates ads sharing the same name with a representative ad_id for preview) and ad_id (one row per ad). The representative ad_id can be passed to meta_ads_preview_ads. Rows come back highest spend first. Rows are compact by default: they leave out the per-type cost arrays (cost_per_action_type, cost_per_conversion, cost_per_thruplay), each of which is spend divided by that type's count. Pass full_detail: true to include them. Creative media (asset_type, asset_url, thumbnail_url) is listed once per ad under assets, keyed by each row's ad_id. Each response is one page of at most 50,000 characters, or limit rows if set. When more rows remain it returns nextCursor: pass it as cursor to get the next page, and repeat until nextCursor is absent to walk every row, compact or full detail. Reads up to 2,000 ad-level rows from Meta. truncated is true whenever a response does not hold every row, and truncation gives the reasons, total_rows, returned_rows, remaining_rows and remaining_spend. The reasons are response_size or limit (more pages remain), row_limit (Meta had more rows than the tool reads; no cursor reaches them, unread_spend gives their approximate spend, and ad_name totals may be low, so narrow by campaign, ad set or ad, shorten time_range, or drop time_increment or breakdowns) and report_changed (live numbers moved rows across a page boundary between calls, so rows may be missing or repeated across pages; call again without cursor for a consistent set). A call without cursor always reads the report fresh from Meta; cursor pages served by the same server instance reuse that read for up to 15 minutes, and a page served elsewhere reads Meta again (report_changed flags any rows that moved).

Full impression-to-conversion funnel report with delivery, engagement, actions, conversions, ROAS, and quality rankings. Supports breakdowns by device (impression_device), demographics (age, gender), geography (country, region, dma), and platform (device_platform, publisher_platform, platform_position). For Sales-objective campaigns (Advantage+ sales), supports \

Search the Meta Ad Library for ads from any advertiser. Returns real creative content — ad copy (primary text, headline, description, CTA), landing URLs, run dates, platforms, and media source/mirrored URLs. Served from Hopkin's scraped ad-library corpus, results under \

Interactive UI for displaying Meta ad previews with creative content and metrics

List ads for a Meta ad account with ad set filtering, status, name search, single/multi-ad lookup by ID, and pagination. Each ad includes a Landing URL when available (extracted from object_story_spec, link_url, or asset_feed_spec depending on ad format) and a URL Tags line exposing the ad's tracking-template string — the URL parameters (UTMs / custom click-tracking) Meta appends to the destination URL at click time, with {{macro}} placeholders preserved verbatim. The URL tags are the creative's url_tags (the Ads Manager "URL parameters"; the Ad node itself has no url_tags field), falling back to the creative's template specs (template_data, template_url_spec query_template) when it is empty. A "Landing Page URLs" summary lists every unique destination URL; a "URL Tags Audit" summary lists the distinct templates in use and names every ad with a destination URL but no tracking template — use these to audit UTM coverage across an account without reading every ad. Set include_assets=true to include resolved creative media URLs (adds latency for cache misses). Entities may optionally include recent activities, and optionally automated rules (set include_rules=true to see which rules affect each ad).

List ad sets for a Meta ad account with campaign filtering, status, name search, single/multi-adset lookup by ID, and pagination. Entities may optionally include recent activities, and optionally automated rules (set include_rules=true to see which rules affect each ad set).

Troubleshoot authentication issues and get user profile info. Only use this tool when another tool fails with a permission or authentication error — do NOT call proactively.

Health check for the Meta Ads MCP server.

List campaigns for a Meta ad account with status filtering, name search, single/multi-campaign lookup by ID, and pagination. Entities may optionally include recent activities, and optionally automated rules (set include_rules=true to see which rules affect each campaign).

Interactive UI for rendering data visualizations (bar, scatter, timeseries, funnel, waterfall, choropleth)

List a competitor's ads from the scraped Meta Ad Library corpus — real creative content (copy, CTA, landing URL, media metadata), not just snapshot links. Filter by active_only (still running), display_format (image, video, carousel, text), since (seen on/after a date), and search (full-text over ad copy). Requires no Meta connection — the corpus is maintained by Hopkin's daily scrape of tracked advertisers. Get advertiser IDs from meta_ads_list_tracked_competitors or meta_ads_track_competitor.

Fetch one competitor ad in full detail from the scraped corpus and SEE the creative: complete copy (headline, primary text, description, CTA), landing URL, run dates, and every media asset. Mirrored images and video thumbnails are returned inline as image content blocks. For videos, pass include_frames to inline extracted frames (capped at ~40 images; window with start/end seconds and stride) — short-TTL signed URLs for EVERY frame, the audio track, and each original are always in structuredContent, along with frame_count/frame_fps (duration ≈ frame_count / frame_fps), the voiceover transcript, and the audio analysis. Media not yet mirrored or processed degrades to source URLs with a note. Requires no Meta connection. Get ad IDs from meta_ads_list_competitor_ads.

Register a Meta advertiser for daily ad-library tracking. Provide exactly one identifier: page_id (numeric Facebook Page ID — most precise), page_url (a facebook.com page URL; numeric IDs resolve directly, vanity handles resolve by searching scraped advertisers), or name (searches scraped advertisers). A search resolving to exactly one advertiser tracks it; multiple matches return a candidate list (name, page_id, ad count) and track NOTHING — retry with page_id; zero matches return an error suggesting the page URL. Once tracked, the daily sweep scrapes the advertiser's ads into the corpus for meta_ads_list_competitor_ads. Requires no Meta connection.

Stop tracking a Meta advertiser. Removes only your tracking registration — the shared ad corpus is untouched, and untracking an advertiser that was never tracked succeeds with removed: false. Get advertiser IDs from meta_ads_list_tracked_competitors.

List the Meta advertisers you are tracking: advertiser name, page ID, when tracking started, last scrape time and status, and the ad count in the corpus for each. Scrape health is flagged per row — advertisers with no successful scrape in the last 48 hours are marked stale, and a non-ok scrape status (blocked, schema_error, empty) carries an explicit scrape_warning; treat flagged rows' corpus data as possibly out of date. Use the returned advertiser IDs with meta_ads_list_competitor_ads to browse their ads. Requires no Meta connection.

List the Meta Ads connections available to you — both ones you own and ones shared with you via an organization. Use this to discover connection IDs for set_default / share / rename / revoke.

Set the Meta connection that should be used by default for subsequent Meta Ads tool calls. The default is scoped to the calling actor (your user account, or the API key being used).

Share an owned Meta connection with all members of your organization, so teammates can use it without having to reconnect Meta themselves. You must be the owner of the connection.

Stop sharing an owned Meta connection with your organization. Teammates lose access immediately. You must be the owner.

Rename the display name of an owned Meta connection. The OAuth grant and underlying account are unaffected — this only changes the human-readable label. You must be the owner.

Revoke (soft-delete) an owned Meta connection. Any defaults pointing to it are invalidated and shared org members lose access. The OAuth grant at Meta is NOT revoked by this tool — the user must disconnect via the dashboard if they want to fully revoke at Meta. You must be the owner.

List custom conversion definitions for a Meta ad account, including ID, name, custom_event_type, event_source_id, rule JSON, retention_days, default_conversion_value, and description. Use this to inspect tracking setup and understand URL/event matching rules behind conversions such as offsite_conversion.fb_pixel_custom.*.

Submit feedback about missing tools, improvements, bugs, or workflow gaps in the MCP toolset. Not for user-facing issues like auth or API errors.

Retrieve performance metrics from Meta Ads with date presets/custom ranges, time grouping, entity-level aggregation, dimensional breakdowns, and filtering. Always fetches fresh data. Provide date_preset or time_range. For standard full-funnel analysis, prefer meta_ads_get_performance_report; use this for custom fields, hourly/creative-asset breakdowns, video metrics, or the \

Comprehensive pixel health check: metadata, CAPI connection status, event volume stats, automatic matching config, and diagnostic checks (including event match quality indicators). capi.connected is true when an active CAPI Gateway config exists or server events were observed in the lookback window (capi.server_event_count), false when both signals were readable and showed neither, and "unknown" when the signals could not be read — NEVER report CAPI as disconnected when it is "unknown"; tell the user to verify in Meta Events Manager instead. Use this to diagnose tracking issues before analyzing ad performance — low ROAS could be a tracking problem, not a campaign problem. When event_stats_status is "permission_denied", surface event_stats_message to the user — the rest of the pixel health audit is still valid.