From hopkin
Guide for building reports and analyzing Meta Ads campaigns using the Hopkin Meta Ads MCP. Includes prerequisite checks, authentication flow, report generation workflows, and developer feedback for unsupported write operations.
How this skill is triggered — by the user, by Claude, or both
Slash command
/hopkin:hopkin-meta-adsThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
This skill enables Claude to build comprehensive reports and analyze Meta Ads campaigns via the Hopkin Meta Ads MCP. Use this skill when you need to:
This skill enables Claude to build comprehensive reports and analyze Meta Ads campaigns via the Hopkin Meta Ads MCP. Use this skill when you need to:
The skill provides structured workflows for common Meta Ads reporting tasks, with built-in best practices for data analysis and presentation.
Before using this skill, verify that the Hopkin Meta Ads MCP is configured and the user is authenticated.
To verify the Hopkin Meta Ads MCP is available:
meta_ads_ prefixed tools in your available tools (e.g., meta_ads_check_auth_status, meta_ads_list_ad_accounts)If no meta_ads_ prefixed tools are available:
The Hopkin Meta Ads MCP is not configured. To use this skill:
- Sign up at https://app.hopkin.ai
- Add the hosted MCP to your Claude configuration:
{ "mcpServers": { "hopkin-meta-ads": { "type": "url", "url": "https://meta.mcp.hopkin.ai/mcp", "headers": { "Authorization": "Bearer YOUR_HOPKIN_TOKEN" } } } }
- Restart Claude after updating configuration
After confirming the MCP is available, authenticate the user's Meta Ads account:
meta_ads_check_auth_status to see if the user is already authenticated and to get their user infometa_ads_check_auth_status again to confirm successful authenticationAt the start of any session, before asking for an account ID, call meta_ads_get_preferences with entity_type: "ad_account" and entity_id: "default" to check if the user has a stored default account. If a default_account_id preference exists, use it automatically and mention it: "Using your saved account [X]. Use a different one? Let me know." If no stored preference exists, proceed to ask for or look up the account ID.
Before generating reports, confirm you have:
meta_ads_list_ad_accounts to search for their account before asking for an ID.time_range with since/until in YYYY-MM-DD format for meta_ads_get_performance_report, or date_preset presets like last_7d/last_30d for meta_ads_get_insights)When meta_ads_list_ad_accounts returns multiple accounts:
meta_ads_store_preference with entity_type: "ad_account", entity_id: "default", key: "default_account_id", and value: "<selected_account_id>"default_account_id stored preference, use it automatically but mention it: "Using your saved account [X]. Use a different one? Let me know."meta_ads_ping — Check MCP connectivitymeta_ads_check_auth_status — Check if user is authenticated and get user profile infometa_ads_list_ad_accounts — List accessible ad accounts (supports search, status filter, lookup by ID, pagination)meta_ads_list_campaigns — List campaigns for an account (supports status filter, name search, lookup by ID, pagination)meta_ads_list_adsets — List ad sets for an account or campaign (supports status filter, name search, lookup by ID, pagination)meta_ads_list_ads — List ads for an account, campaign, or ad set (supports status filter, name search, lookup by ID, pagination)meta_ads_get_performance_report — Recommended for campaign/account/adset-level analysis. Full-funnel performance report (always includes impressions, reach, frequency, spend, clicks, cpc, cpm, ctr, unique_clicks, actions, action_values, conversions, purchase_roas, quality rankings). Requires time_range with explicit since/until dates. Supports level: account (default), campaign, adset, ad. Supports attributionWindows to specify post-click and post-view attribution periods (e.g., ["1d_click", "7d_click", "1d_view"]).meta_ads_get_ad_creative_report — Recommended for ad creative analysis. Ad-level performance report with full funnel metrics and creative asset info (asset_type, asset_url, thumbnail_url). Supports two grouping modes via level: ad_name (default, aggregates ads with the same name across ad sets — returns a representative ad_id usable with meta_ads_preview_ads) or ad_id (one row per ad). Use this instead of meta_ads_get_performance_report with level: "ad" for creative analysis.meta_ads_get_insights — Flexible insights with custom breakdowns, metrics, and date presets. Supports attributionWindows to specify post-click and post-view attribution periods (e.g., ["1d_click", "7d_click", "1d_view"]).meta_ads_get_pixel_health — Pixel health audit. Check Meta Pixel and Conversions API (CAPI) integration status, event volumes, automatic advanced matching coverage, and event diagnostics. Use when users ask about tracking health, event firing, CAPI status, or data quality. Params: account_id (required), pixel_id?, event_names? (filter to specific events), days_back? (lookback window, default 7), limit?, cursor?meta_ads_render_chart — MCP App. ALWAYS use this when the user asks for any chart, graph, map, or visualization. Do NOT substitute a table or text summary. Supports 6 types: bar (compare values across campaigns/placements), scatter (correlation between two metrics), timeseries (metrics over time), funnel (conversion stages), waterfall (cumulative contribution), choropleth (US state heatmap). Fetch the data first with insights or performance report tools, then pass the structured data here. This renders an interactive visual — it is the correct tool whenever a chart is explicitly requested.meta_ads_preview_ads — MCP App. Renders a visual UI with actual ad creative (images/videos) and a configurable metrics overlay — not tabular data. Proactively offer this whenever the user asks "what do my ads look like", wants to review creative quality, or is doing A/B creative comparison. Takes a list of ad IDs with optional per-ad metric values.meta_ads_render_chart — MCP App. Renders interactive data visualization charts. Supports bar, scatter, timeseries, funnel, waterfall, and choropleth chart types. Use after fetching data with analytics tools to present visual reports. Always render charts when presenting performance trends, campaign comparisons, or geographic data — do not substitute a table or text summary when a chart is requested.meta_ads_store_preference — Store a persistent preference or observation about an ad entity (account, campaign, ad set, or ad)meta_ads_get_preferences — Get all stored preferences for an ad entitymeta_ads_delete_preference — Delete a specific stored preference by keymeta_ads_developer_feedback — Submit feature requests and workflow gap reportsNote: Every tool call requires a
reason(string) parameter for audit trail.
This skill supports five primary report types and a developer feedback workflow for write operations.
After fetching report data, proactively render charts to make insights more accessible. Use meta_ads_render_chart to visualize data — always pair charts with a summary table and textual insights.
When to use each chart type:
Charts enhance the report — they don't replace the analysis. Always include written insights alongside visualizations.
The Hopkin Meta Ads MCP is read-only. When a user requests write operations (create campaign, update budget, pause ads, etc.):
meta_ads_developer_feedback with:
feedback_type: "workflow_gap"title: Description of the write operation requesteddescription: What the user was trying to docurrent_workaround: How you worked around the limitation (if applicable)priority: Based on user's urgencyWhenever you complete a task and believe there should have been a faster or more efficient way to get the answer — for example, if you had to make multiple tool calls that could have been a single call, or if a dedicated tool for the workflow would have saved time — call meta_ads_developer_feedback with:
feedback_type: "new_tool" or "improvement"title: Brief description of the missing capabilitydescription: Explain what you were trying to accomplish, the steps you had to take, and how a new or improved tool could have made it fastercurrent_workaround: The steps you took to work around the limitationpriority: "medium"This helps the Hopkin team prioritize building tools that make common workflows more efficient.
Users can provide feedback about this skill directly through the Hopkin Meta Ads MCP. If a user wants to suggest improvements, report issues, or request new capabilities, call meta_ads_developer_feedback on their behalf with the appropriate feedback_type (new_tool, improvement, bug, or workflow_gap) and include their feedback in the description.
Analyze overall campaign performance, compare campaigns across an account, identify top and bottom performers, and understand ROI across different campaign objectives.
Primary tool: meta_ads_get_performance_report with level: "campaign"
See detailed workflow: references/workflows/campaign-performance.md
Evaluate individual ad creative effectiveness, conduct A/B testing analysis, identify best-performing ad formats, and preview actual ad creatives with performance data.
Primary tools: meta_ads_get_ad_creative_report + meta_ads_preview_ads
See detailed workflow: references/workflows/ad-creative-performance.md
Understand who engages with your ads, analyze demographic performance, discover high-value audience segments, optimize targeting strategies, and inform creative direction.
Primary tool: meta_ads_get_insights with breakdowns (e.g., ["age", "gender"])
See detailed workflow: references/workflows/audience-insights.md
Monitor budget utilization and spending pace, forecast end-of-period spend, identify budget constraints or underspend issues, and ensure even delivery throughout campaign duration.
Primary tools: meta_ads_list_campaigns for budgets + meta_ads_get_insights with time_increment: "1" for daily trends
See detailed workflow: references/workflows/budget-pacing.md
Audit Meta Pixel implementation health, verify Conversions API (CAPI) integration, check event volumes and quality, and diagnose tracking issues.
Primary tool: meta_ads_get_pixel_health
Common use cases:
Quick workflow:
meta_ads_get_pixel_health with the account IDThe Hopkin Meta Ads MCP does not support create, update, or delete operations. When users request these actions, follow the developer feedback workflow.
See detailed workflow: references/workflows/common-actions.md
Provide actionable optimization recommendations based on performance analysis:
See detailed workflow: references/workflows/common-actions.md#performance-optimization-recommendations
Attribution windows define how long after an ad click or view a conversion is counted. Both meta_ads_get_performance_report and meta_ads_get_insights accept an attributionWindows array parameter.
Available values:
1d_click — Conversions within 1 day of clicking7d_click — Conversions within 7 days of clicking (Meta default)28d_click — Conversions within 28 days of clicking1d_view — Conversions within 1 day of viewing (without clicking)7d_view — Conversions within 7 days of viewing (without clicking)When to use custom attribution windows:
1d_view or 7d_view)Example — side-by-side attribution comparison:
{
"tool": "meta_ads_get_performance_report",
"parameters": {
"reason": "Comparing 1-day vs 7-day click attribution to understand conversion lag",
"account_id": "act_123456789",
"level": "campaign",
"time_range": {"since": "2026-01-01", "until": "2026-01-31"},
"attributionWindows": ["1d_click", "7d_click"]
}
}
For full details see references/mcp-tools-reference.md#attribution-windows.
Choose metrics appropriate to campaign objective:
Always include: spend, impressions/reach, and at least one efficiency metric.
When errors occur:
meta_ads_check_auth_status; if not authenticated, direct the user to connect their account at https://app.hopkin.aiFor detailed troubleshooting guidance, see references/troubleshooting.md.
Common quick fixes:
meta_ads_check_auth_status; if not authenticated, direct user to https://app.hopkin.ai to connect their Meta Ads accountFor more detailed information:
meta_ads_get_pixel_health for tracking diagnostics (no separate workflow file — tool is self-contained)Skill Version: 2.4 Last Updated: 2026-03-22 Requires: Hopkin Meta Ads MCP (https://app.hopkin.ai)
npx claudepluginhub pearmill/hopkin-plugins --plugin hopkinCreates, edits, and optimizes skills for Claude Code, including drafting, evaluating with test prompts, iterating on performance, and improving skill descriptions for better triggering accuracy.