meta-ads-mcp

mcp_meta_ads_get_campaigns

• Get campaigns for a Meta Ads account with optional filtering
• Inputs:
  • access_token (optional): Meta API access token (will use cached token if not provided)
  • account_id: Meta Ads account ID (format: act_XXXXXXXXX)
  • limit: Maximum number of campaigns to return (default: 10)
  • status_filter: Filter by status (empty for all, or 'ACTIVE', 'PAUSED', etc.)
• Returns: List of campaigns matching the criteria

mcp_meta_ads_get_campaign_details

• Get detailed information about a specific campaign
• Inputs:
  • access_token (optional): Meta API access token (will use cached token if not provided)
  • campaign_id: Meta Ads campaign ID
• Returns: Detailed information about the specified campaign

mcp_meta_ads_create_campaign

• Create a new campaign in a Meta Ads account

• Inputs:

  • access_token (optional): Meta API access token (will use cached token if not provided)

  • account_id: Meta Ads account ID (format: act_XXXXXXXXX)

  • name: Campaign name

  • objective: Campaign objective (ODAX, outcome-based). Must be one of:

    • OUTCOME_AWARENESS
    • OUTCOME_TRAFFIC
    • OUTCOME_ENGAGEMENT
    • OUTCOME_LEADS
    • OUTCOME_SALES
    • OUTCOME_APP_PROMOTION

    Note: Legacy objectives such as BRAND_AWARENESS, LINK_CLICKS, CONVERSIONS, APP_INSTALLS, etc. are no longer valid for new campaigns and will cause a 400 error. Use the outcome-based values above. Common mappings:

    • BRAND_AWARENESS → OUTCOME_AWARENESS
    • REACH → OUTCOME_AWARENESS
    • LINK_CLICKS, TRAFFIC → OUTCOME_TRAFFIC
    • POST_ENGAGEMENT, PAGE_LIKES, EVENT_RESPONSES, VIDEO_VIEWS → OUTCOME_ENGAGEMENT
    • LEAD_GENERATION → OUTCOME_LEADS
    • CONVERSIONS, CATALOG_SALES, MESSAGES (sales-focused flows) → OUTCOME_SALES
    • APP_INSTALLS → OUTCOME_APP_PROMOTION

  • status: Initial campaign status (default: PAUSED)

  • special_ad_categories: List of special ad categories if applicable

  • daily_budget: Daily budget in account currency (in cents)

  • lifetime_budget: Lifetime budget in account currency (in cents)

  • bid_strategy: Bid strategy. Must be one of: LOWEST_COST_WITHOUT_CAP, LOWEST_COST_WITH_BID_CAP, COST_CAP, LOWEST_COST_WITH_MIN_ROAS.

• Returns: Confirmation with new campaign details

• Example:

  {
    "name": "2025 - Bedroom Furniture - Awareness",
    "account_id": "act_123456789012345",
    "objective": "OUTCOME_AWARENESS",
    "special_ad_categories": [],
    "status": "PAUSED",
    "buying_type": "AUCTION",
    "bid_strategy": "LOWEST_COST_WITHOUT_CAP",
    "daily_budget": 10000
  }
  

mcp_meta_ads_get_adsets

• Get ad sets for a Meta Ads account with optional filtering by campaign
• Inputs:
  • access_token (optional): Meta API access token (will use cached token if not provided)
  • account_id: Meta Ads account ID (format: act_XXXXXXXXX)
  • limit: Maximum number of ad sets to return (default: 10)
  • campaign_id: Optional campaign ID to filter by
• Returns: List of ad sets matching the criteria

mcp_meta_ads_get_adset_details

• Get detailed information about a specific ad set
• Inputs:
  • access_token (optional): Meta API access token (will use cached token if not provided)
  • adset_id: Meta Ads ad set ID
• Returns: Detailed information about the specified ad set

mcp_meta_ads_create_adset

• Create a new ad set in a Meta Ads account
• Inputs:
  • account_id: Meta Ads account ID (format: act_XXXXXXXXX)
  • campaign_id: Meta Ads campaign ID this ad set belongs to
  • name: Ad set name
  • status: Initial ad set status (default: PAUSED)
  • daily_budget: Daily budget in account currency (in cents) as a string
  • lifetime_budget: Lifetime budget in account currency (in cents) as a string
  • targeting: Targeting specifications (e.g., age, location, interests)
  • optimization_goal: Conversion optimization goal (e.g., 'LINK_CLICKS')
  • billing_event: How you're charged (e.g., 'IMPRESSIONS')
  • bid_amount: Bid amount in cents. Required for LOWEST_COST_WITH_BID_CAP, COST_CAP, TARGET_COST.
  • bid_strategy: Bid strategy (e.g., 'LOWEST_COST_WITHOUT_CAP', 'LOWEST_COST_WITH_MIN_ROAS')
  • bid_constraints: Bid constraints dict. Required for LOWEST_COST_WITH_MIN_ROAS (e.g., {"roas_average_floor": 20000})
  • start_time, end_time: Optional start/end times (ISO 8601)
  • access_token (optional): Meta API access token
• Returns: Confirmation with new ad set details

mcp_meta_ads_get_ads

• Get ads for a Meta Ads account with optional filtering
• Inputs:
  • access_token (optional): Meta API access token (will use cached token if not provided)
  • account_id: Meta Ads account ID (format: act_XXXXXXXXX)
  • limit: Maximum number of ads to return (default: 10)
  • campaign_id: Optional campaign ID to filter by
  • adset_id: Optional ad set ID to filter by
• Returns: List of ads matching the criteria

mcp_meta_ads_create_ad

• Create a new ad with an existing creative
• Inputs:
  • account_id: Meta Ads account ID (format: act_XXXXXXXXX)
  • name: Ad name
  • adset_id: Ad set ID where this ad will be placed
  • creative_id: ID of an existing creative to use
  • status: Initial ad status (default: PAUSED)
  • bid_amount: Optional bid amount (in cents)
  • tracking_specs: Optional tracking specifications
  • access_token (optional): Meta API access token
• Returns: Confirmation with new ad details

mcp_meta_ads_get_ad_details

• Get detailed information about a specific ad
• Inputs:
  • access_token (optional): Meta API access token (will use cached token if not provided)
  • ad_id: Meta Ads ad ID
• Returns: Detailed information about the specified ad

mcp_meta_ads_get_ad_creatives

• Get creative details for a specific ad
• Inputs:
  • access_token (optional): Meta API access token (will use cached token if not provided)
  • ad_id: Meta Ads ad ID
• Returns: Creative details including text, images, and URLs

mcp_meta_ads_create_ad_creative

• Create a new ad creative using an uploaded image hash
• Inputs:
  • account_id: Meta Ads account ID (format: act_XXXXXXXXX)
  • name: Creative name
  • image_hash: Hash of the uploaded image
  • page_id: Facebook Page ID for the ad
  • link_url: Destination URL
  • message: Ad copy/text
  • headline: Single headline for simple ads (cannot be used with headlines)
  • headlines: List of headlines for dynamic creative testing (cannot be used with headline)
  • description: Single description for simple ads (cannot be used with descriptions)
  • descriptions: List of descriptions for dynamic creative testing (cannot be used with description)
  • dynamic_creative_spec: Dynamic creative optimization settings
  • call_to_action_type: CTA button type (e.g., 'LEARN_MORE')
  • instagram_actor_id: Optional Instagram account ID
  • access_token (optional): Meta API access token
• Returns: Confirmation with new creative details

mcp_meta_ads_update_ad_creative

• Update an existing ad creative with new content or settings
• Inputs:
  • creative_id: Meta Ads creative ID to update
  • name: New creative name
  • message: New ad copy/text
  • headline: Single headline for simple ads (cannot be used with headlines)
  • headlines: New list of headlines for dynamic creative testing (cannot be used with headline)
  • description: Single description for simple ads (cannot be used with descriptions)
  • descriptions: New list of descriptions for dynamic creative testing (cannot be used with description)
  • dynamic_creative_spec: New dynamic creative optimization settings
  • call_to_action_type: New call to action button type
  • access_token (optional): Meta API access token (will use cached token if not provided)
• Returns: Confirmation with updated creative details

mcp_meta_ads_upload_ad_image

• Upload an image to use in Meta Ads creatives
• Inputs:
  • account_id: Meta Ads account ID (format: act_XXXXXXXXX)
  • image_path: Path to the image file to upload
  • name: Optional name for the image
  • access_token (optional): Meta API access token
• Returns: JSON response with image details including hash

mcp_meta_ads_get_ad_image

• Get, download, and visualize a Meta ad image in one step
• Inputs:
  • access_token (optional): Meta API access token (will use cached token if not provided)
  • ad_id: Meta Ads ad ID
• Returns: The ad image ready for direct visual analysis

mcp_meta_ads_update_ad

• Update an ad with new settings
• Inputs:
  • ad_id: Meta Ads ad ID
  • status: Update ad status (ACTIVE, PAUSED, etc.)
  • bid_amount: Bid amount in account currency (in cents for USD)
  • access_token (optional): Meta API access token (will use cached token if not provided)
• Returns: Confirmation with updated ad details and a confirmation link

mcp_meta_ads_update_adset

• Update an ad set with new settings including frequency caps
• Inputs:
  • adset_id: Meta Ads ad set ID
  • frequency_control_specs: List of frequency control specifications
  • bid_strategy: Bid strategy (e.g., 'LOWEST_COST_WITH_BID_CAP', 'LOWEST_COST_WITH_MIN_ROAS')
  • bid_amount: Bid amount in cents. Required for LOWEST_COST_WITH_BID_CAP, COST_CAP, TARGET_COST.
  • bid_constraints: Bid constraints dict. Required for LOWEST_COST_WITH_MIN_ROAS (e.g., {"roas_average_floor": 20000})
  • status: Update ad set status (ACTIVE, PAUSED, etc.)
  • targeting: Targeting specifications including targeting_automation
  • access_token (optional): Meta API access token (will use cached token if not provided)
• Returns: Confirmation with updated ad set details and a confirmation link

mcp_meta_ads_get_insights

• Get performance insights for a campaign, ad set, ad or account
• Inputs:
  • access_token (optional): Meta API access token (will use cached token if not provided)
  • object_id: ID of the campaign, ad set, ad or account
  • time_range: Time range for insights (default: maximum)
  • breakdown: Optional breakdown dimension (e.g., age, gender, country)
  • level: Level of aggregation (ad, adset, campaign, account)
  • action_attribution_windows (optional): List of attribution windows for conversion data (e.g., ["1d_click", "1d_view", "7d_click", "7d_view"]). When specified, actions and cost_per_action_type include additional fields for each window. The 'value' field always shows 7d_click attribution.
• Returns: Performance metrics for the specified object

mcp_meta_ads_get_login_link

• Get a clickable login link for Meta Ads authentication
• Inputs:
  • access_token (optional): Meta API access token (will use cached token if not provided)
• Returns: A clickable resource link for Meta authentication

mcp_meta_ads_create_budget_schedule

• Create a budget schedule for a Meta Ads campaign
• Inputs:
  • campaign_id: Meta Ads campaign ID
  • budget_value: Amount of budget increase
  • budget_value_type: Type of budget value ("ABSOLUTE" or "MULTIPLIER")
  • time_start: Unix timestamp for when the high demand period should start
  • time_end: Unix timestamp for when the high demand period should end
  • access_token (optional): Meta API access token
• Returns: JSON string with the ID of the created budget schedule or an error message

mcp_meta_ads_search_interests

• Search for interest targeting options by keyword
• Inputs:
  • access_token (optional): Meta API access token (will use cached token if not provided)
  • query: Search term for interests (e.g., "baseball", "cooking", "travel")
  • limit: Maximum number of results to return (default: 25)
• Returns: Interest data with id, name, audience_size, and path fields

mcp_meta_ads_get_interest_suggestions

• Get interest suggestions based on existing interests
• Inputs:
  • access_token (optional): Meta API access token (will use cached token if not provided)
  • interest_list: List of interest names to get suggestions for (e.g., ["Basketball", "Soccer"])
  • limit: Maximum number of suggestions to return (default: 25)
• Returns: Suggested interests with id, name, audience_size, and description fields

mcp_meta_ads_validate_interests

• Validate interest names or IDs for targeting
• Inputs:
  • access_token (optional): Meta API access token (will use cached token if not provided)
  • interest_list: List of interest names to validate (e.g., ["Japan", "Basketball"])
  • interest_fbid_list: List of interest IDs to validate (e.g., ["6003700426513"])
• Returns: Validation results showing valid status and audience_size for each interest

mcp_meta_ads_search_behaviors

• Get all available behavior targeting options
• Inputs:
  • access_token (optional): Meta API access token (will use cached token if not provided)
  • limit: Maximum number of results to return (default: 50)
• Returns: Behavior targeting options with id, name, audience_size bounds, path, and description

mcp_meta_ads_search_demographics

• Get demographic targeting options
• Inputs:
  • access_token (optional): Meta API access token (will use cached token if not provided)
  • demographic_class: Type of demographics ('demographics', 'life_events', 'industries', 'income', 'family_statuses', 'user_device', 'user_os')
  • limit: Maximum number of results to return (default: 50)
• Returns: Demographic targeting options with id, name, audience_size bounds, path, and description

mcp_meta_ads_search_geo_locations

• Search for geographic targeting locations
• Inputs:
  • access_token (optional): Meta API access token (will use cached token if not provided)
  • query: Search term for locations (e.g., "New York", "California", "Japan")
  • location_types: Types of locations to search (['country', 'region', 'city', 'zip', 'geo_market', 'electoral_district'])
  • limit: Maximum number of results to return (default: 25)
• Returns: Location data with key, name, type, and geographic hierarchy information

mcp_meta_ads_search (Enhanced)

• Generic search across accounts, campaigns, ads, and pages
• Automatically includes page searching when query mentions "page" or "pages"
• Inputs:
  • access_token (optional): Meta API access token (will use cached token if not provided)
  • query: Search query string (e.g., "Injury Payouts pages", "active campaigns")
• Returns: List of matching record IDs in ChatGPT-compatible format