Meta Ads

Platform Overview

The Meta Ads MCP server enables AI assistants to manage and analyze Meta (Facebook/Instagram) advertising campaigns through the Meta Marketing API v21.0. It provides comprehensive tools for account management, campaign and audience targeting configuration, performance analytics, creative analysis, and pixel health diagnostics — allowing you to automate campaign workflows, retrieve insights at any aggregation level, and debug tracking issues.

Your prompt → Claude + Hopkin → Meta Marketing API v21.0
                                    ↓
                              Campaign Data
                              Performance Metrics  
                              Audience Insights
                              Creative Reports
                              Pixel Health Diagnostics

Common Workflows

Performance Reporting

Get a snapshot of how your campaigns are performing across impressions, clicks, conversions, and return on ad spend.

"What was our total spend, impressions, and ROAS last month?"

Calls meta_ads_get_account_summary with a date range. Returns aggregated account-level metrics in a standardized format for quick overviews without needing to drill down into individual campaigns.

"Show me performance by campaign for January."

Calls meta_ads_get_performance_report with level: 'campaign' and a custom date range. Returns full-funnel metrics (delivery → engagement → conversions → ROAS) broken down by campaign so you can compare which campaigns are driving the most value.

"What are the impressions, clicks, and conversion rate for all active campaigns this week?"

Calls meta_ads_list_campaigns with status filter, then meta_ads_get_insights or meta_ads_get_performance_report at the campaign level for the current week. Returns a table-format response showing each campaign's key metrics side-by-side.

Campaign Management

View, search, and explore the hierarchy of campaigns, ad sets, and individual ads.

"List all my active campaigns"

Calls meta_ads_list_campaigns with status: ['ACTIVE']. Returns paginated list of active campaigns with names, IDs, statuses, budgets, and stored preferences or recent change history.

"Find ad sets in campaign ABC123 that are paused"

Calls meta_ads_list_adsets with campaign_id: 'ABC123' and status: ['PAUSED']. Returns ad sets filtered by that campaign with pagination, search capability, and optional metrics if include_assets: true.

"Get all ads in ad set XYZ with their creative assets and landing pages"

Calls meta_ads_list_ads with adset_id: 'XYZ' and include_assets: true. Response includes resolved creative media URLs (images, videos) plus a summary section listing all unique landing page URLs found in those ads — ideal for quickly auditing destination URLs without reading every ad individually.

Audience & Creative Analysis

Analyze demographic performance and compare which creative variants are driving engagement.

"Break down our last week's performance by age and gender"

Calls meta_ads_get_insights with date_preset: 'last_7d', level: 'account', and breakdowns: ['age', 'gender']. Returns demographic slice of performance metrics showing which age/gender groups have the highest CTR, conversion rate, and ROAS.

"Show creative performance for all ads, aggregated by creative name"

Calls meta_ads_get_ad_creative_report with level: 'ad_name' and a date range. Returns creative variants grouped by name with full-funnel metrics; each group includes a representative ad_id that can be passed to meta_ads_preview_ads to visually inspect that creative.

"Which video ads have the highest video completion rate?"

Calls meta_ads_get_insights with level: 'ad', fields: ['video_p25_watched_actions', 'video_p50_watched_actions', 'video_p75_watched_actions', 'video_p100_watched_actions'], and a date range. Returns per-ad video completion funnel showing what percentage of viewers watched 25%, 50%, 75%, and 100% of each video.

Budget & Spend Monitoring

Keep tabs on spending and campaign pacing.

"How much have we spent this month across all campaigns?"

Calls meta_ads_get_account_summary with the current month's date range. Returns account-level spend, impressions, clicks, and conversions in one call.

"Show daily spend trend for the past week"

Calls meta_ads_get_performance_report with time_increment: 1 (daily), date_preset: 'last_7d'. Returns spend broken down day-by-day, ideal for spotting anomalies or tracking pacing toward daily/monthly budgets.

Recipes

"I suspect a tracking issue is tanking our ROAS. Check our pixel health first."

Calls meta_ads_get_pixel_health to retrieve pixel metadata, CAPI connection status, event volume, automatic matching config, and diagnostic checks (including event match quality). If CAPI is not connected or event volume is low, tracking is the problem — not campaign performance. This is the essential diagnostic tool before investigating campaign-level metrics.

"Show me the top 3 performing creatives by ROAS this month, with a visual preview of each."

Calls meta_ads_get_ad_creative_report with level: 'ad_name' sorted by ROAS descending, limited to 3 results. Extracts the representative ad_id from each, then calls meta_ads_preview_ads with those ad IDs and includes ROAS as a metric label. Returns visual previews of the creative images/videos alongside the ROAS figure so you can visually compare winners.

"List all paused campaigns, show me their recent change history, and tell me who paused them."

Calls meta_ads_list_campaigns with status: ['PAUSED']. For each campaign ID, calls meta_ads_get_activities with entity_id: <campaign_id> and entity_type: 'CAMPAIGN'. Aggregates the activity logs to show when each campaign was paused and by whom (from the activity record).

"Find underperforming ad sets (low ROAS) within my top-spend campaign and show me their demographic breakdowns."

Calls meta_ads_get_performance_report with level: 'adset', filtered to the top-spend campaign. Identifies ad sets with ROAS below a threshold. For each, calls meta_ads_get_insights with breakdowns: ['age', 'gender'] to find demographic segments (e.g., women 35-44) that are underperforming — useful for tightening audience targeting.

"I need to audit all landing pages being used across active ads. Give me a categorized summary."

Calls meta_ads_list_ads with status: ['ACTIVE'] and include_assets: true. The markdown response includes a "Landing Page URLs" summary section listing all unique destination URLs. Group those by domain (e.g., homepage vs. product pages) to identify which landing pages are live and used by active ads.

"Show me a 90-day performance trend by publisher (Instagram vs. Facebook) to decide where to shift budget."

Calls meta_ads_get_insights with date_preset: 'last_90d', breakdowns: ['publisher_platform'], and optional time_increment: 7 for weekly aggregation. Returns 90-day performance sliced by Instagram, Facebook, Audience Network, etc., so you can see which platform is most efficient and recommend budget reallocation.

Tips

Date Presets vs. Custom Ranges: Use date_preset for standard lookbacks (e.g., last_7d, last_30d, last_quarter) for faster responses. For precise custom ranges, use time_range: { since: '2026-01-01', until: '2026-01-31' }. Both meta_ads_get_insights and meta_ads_get_performance_report support both modes.

Breakdowns Available: Demographic (age, gender, country), device/platform (device_platform, publisher_platform, platform_position), time-based (hourly_stats_aggregated_by_advertiser_time_zone for intra-day analysis), and creative assets (ad_format_asset, video_asset, image_asset, etc.). Not all breakdowns are available at all levels — try the combination first; if unsupported, the API will return an error with guidance.

Cache-First Behavior: List tools (meta_ads_list_campaigns, meta_ads_list_ad_accounts, etc.) return cached data by default with a cached: boolean flag and synced_at timestamp. For real-time data, pass refresh: true. Reporting tools (meta_ads_get_performance_report, meta_ads_get_insights) always fetch fresh data — no caching applies.

Landing Pages in Ad List: When calling meta_ads_list_ads with include_assets: true, the markdown response automatically includes a "Landing Page URLs" summary at the end listing all unique destination URLs found across the ads — saves you from parsing individual ad objects to audit where traffic is going.