Skip to main content
Glama
Meta Ads MCP

Meta Ads MCP

Meta Ads MCP

A Model Context Protocol (MCP) server for interacting with Meta Ads. Analyze, manage and optimize Meta advertising campaigns through an AI interface. Use an LLM to retrieve performance data, visualize ad creatives, and provide strategic insights for your ads on Facebook, Instagram, and other Meta platforms.

DISCLAIMER: This is an unofficial third-party tool and is not associated with, endorsed by, or affiliated with Meta in any way. This project is maintained independently and uses Meta's public APIs according to their terms of service. Meta, Facebook, Instagram, and other Meta brand names are trademarks of their respective owners.

Meta Ads MCP Server Demo

MCP Badge

mcp-name: co.pipeboard/meta-ads-mcp

Community & Support

Table of Contents

The fastest and most reliable way to get started is to 🚀 Get started with our Meta Ads Remote MCP. Our cloud service uses streamable HTTP transport for reliable, scalable access to Meta Ads data. No technical setup required - just connect and start analyzing your ad campaigns with AI!

For Claude Pro/Max Users

  1. Go to claude.ai/settings/integrations (requires Claude Pro or Max)

  2. Click "Add Integration" and enter:

    • Name: "Pipeboard Meta Ads" (or any name you prefer)

    • Integration URL: https://mcp.pipeboard.co/meta-ads-mcp

  3. Click "Connect" next to the integration and follow the prompts to:

    • Login to Pipeboard

    • Connect your Facebook Ads account

That's it! You can now ask Claude to analyze your Meta ad campaigns, get performance insights, and manage your advertising.

Advanced: Direct Token Authentication (Claude)

For direct token-based authentication without the interactive flow, use this URL format when adding the integration:

https://mcp.pipeboard.co/meta-ads-mcp?token=YOUR_PIPEBOARD_TOKEN

Get your token at pipeboard.co/api-tokens.

For Cursor Users

Add the following to your ~/.cursor/mcp.json. Once you enable the remote MCP, click on "Needs login" to finish the login process.

{
  "mcpServers": {
    "meta-ads-remote": {
      "url": "https://mcp.pipeboard.co/meta-ads-mcp"
    }
  }
}

Advanced: Direct Token Authentication (Cursor)

If you prefer to authenticate without the interactive login flow, you can include your Pipeboard API token directly in the URL:

{
  "mcpServers": {
    "meta-ads-remote": {
      "url": "https://mcp.pipeboard.co/meta-ads-mcp?token=YOUR_PIPEBOARD_TOKEN"
    }
  }
}

Get your token at pipeboard.co/api-tokens.

For Other MCP Clients

Use the Remote MCP URL: https://mcp.pipeboard.co/meta-ads-mcp

📖 Get detailed setup instructions for your AI client here

Advanced: Direct Token Authentication (Other Clients)

For MCP clients that support token-based authentication, you can append your Pipeboard API token to the URL:

https://mcp.pipeboard.co/meta-ads-mcp?token=YOUR_PIPEBOARD_TOKEN

This bypasses the interactive login flow and authenticates immediately. Get your token at pipeboard.co/api-tokens.

Local Installation (Advanced Technical Users Only)

🚀 We strongly recommend using Remote MCP instead - it's faster, more reliable, and requires no technical setup.

Meta Ads MCP also supports a local streamable HTTP transport, allowing you to run it as a standalone HTTP API for web applications and custom integrations. See Streamable HTTP Setup Guide for complete instructions.

Features

  • AI-Powered Campaign Analysis: Let your favorite LLM analyze your campaigns and provide actionable insights on performance

  • Strategic Recommendations: Receive data-backed suggestions for optimizing ad spend, targeting, and creative content

  • Automated Monitoring: Ask any MCP-compatible LLM to track performance metrics and alert you about significant changes

  • Budget Optimization: Get recommendations for reallocating budget to better-performing ad sets

  • Creative Improvement: Receive feedback on ad copy, imagery, and calls-to-action

  • Dynamic Creative Testing: Easy API for both simple ads (single headline/description) and advanced A/B testing (multiple headlines/descriptions)

  • Campaign Management: Request changes to campaigns, ad sets, and ads (all changes require explicit confirmation)

  • Cross-Platform Integration: Works with Facebook, Instagram, and all Meta ad platforms

  • Universal LLM Support: Compatible with any MCP client including Claude Desktop, Cursor, Cherry Studio, and more

  • Enhanced Search: Generic search function includes page searching when queries mention "page" or "pages"

  • Simple Authentication: Easy setup with secure OAuth authentication

  • Cross-Platform Support: Works on Windows, macOS, and Linux

Configuration

✨ Get started with Remote MCP here - no technical setup required! Just connect your Facebook Ads account and start asking AI to analyze your campaigns.

Local Installation (Advanced Technical Users)

For advanced users who need to self-host, the package can be installed from source. Local installations require creating your own Meta Developer App. We recommend using Remote MCP for a simpler experience.

Available MCP Tools

  1. mcp_meta_ads_get_ad_accounts

    • Get ad accounts accessible by a user

    • Inputs:

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

      • user_id: Meta user ID or "me" for the current user

      • limit: Maximum number of accounts to return (default: 200)

    • Returns: List of accessible ad accounts with their details

  2. mcp_meta_ads_get_account_info

    • Get detailed information about a specific ad 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)

    • Returns: Detailed information about the specified account

  3. mcp_meta_ads_get_account_pages

    • Get pages associated with 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) or "me" for the current user's pages

    • Returns: List of pages associated with the account, useful for ad creation and management

  4. 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

  5. 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

  6. 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
      }
  7. 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

  8. 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

  9. 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 account currency (in cents)

      • bid_strategy: Bid strategy (e.g., 'LOWEST_COST')

      • start_time, end_time: Optional start/end times (ISO 8601)

      • access_token (optional): Meta API access token

    • Returns: Confirmation with new ad set details

  10. 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

  11. 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

  12. 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

  13. 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

  14. 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

  15. 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

  16. 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

  17. 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

  18. 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

  19. 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')

      • bid_amount: Bid amount in account currency (in cents for USD)

      • 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

  20. 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

  21. 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

  22. 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

  23. 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

  24. 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

  25. 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

  26. 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

  27. 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

  28. 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

  29. 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

Licensing

Meta Ads MCP is licensed under the Business Source License 1.1, which means:

  • ✅ Free to use for individual and business purposes

  • ✅ Modify and customize as needed

  • ✅ Redistribute to others

  • ✅ Becomes fully open source (Apache 2.0) on January 1, 2029

The only restriction is that you cannot offer this as a competing hosted service. For questions about commercial licensing, please contact us.

Privacy and Security

Meta Ads MCP follows security best practices with secure token management and automatic authentication handling.

  • Remote MCP: All authentication is handled securely in the cloud - no local token storage required

  • Local Installation: Tokens are cached securely on your local machine

Testing

Basic Testing

Test your Meta Ads MCP connection with any MCP client:

  1. Verify Account Access: Ask your LLM to use mcp_meta_ads_get_ad_accounts

  2. Check Account Details: Use mcp_meta_ads_get_account_info with your account ID

  3. List Campaigns: Try mcp_meta_ads_get_campaigns to see your ad campaigns

For detailed local installation testing, see the source repository.

Troubleshooting

💡 Quick Fix: Skip the Technical Setup!

The easiest way to avoid any setup issues is to 🎯 use our Remote MCP instead. No downloads, no configuration - just connect your ads account and start getting AI insights on your campaigns immediately!

Local Installation Issues

For local installation issues, refer to the source repository. For the easiest experience, we recommend using Remote MCP instead.

Available Tools

33 tools
create_adA
Create a new ad with an existing creative.

Args:
    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 account currency (in cents)
    tracking_specs: Optional tracking specifications (e.g., for pixel events).
                  Example: [{"action.type":"offsite_conversion","fb_pixel":["YOUR_PIXEL_ID"]}]
    access_token: Meta API access token (optional - will use cached token if not provided)

Note:
    Dynamic Creative creatives require the parent ad set to have `is_dynamic_creative=true`.
    Otherwise, ad creation will fail with error_subcode 1885998.

Inputs: account_id (required), name (required), adset_id (required), creative_id (required), +4 more. Returns: result

create_ad_creativeA
Create a new ad creative using an uploaded image hash.

Args:
    account_id: Meta Ads account ID (format: act_XXXXXXXXX)
    image_hash: Hash of the uploaded image
    access_token: Meta API access token (optional - will use cached token if not provided)
    name: Creative name
    page_id: Facebook Page ID to be used for the ad
    link_url: Destination URL for the ad
    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: Call to action button type (e.g., 'LEARN_MORE', 'SIGN_UP', 'SHOP_NOW')
    lead_gen_form_id: Lead generation form ID for lead generation campaigns. Required when using
                     lead generation CTAs like 'SIGN_UP', 'GET_OFFER', 'SUBSCRIBE', etc.
    instagram_actor_id: Optional Instagram account ID for Instagram placements

Returns:
    JSON response with created creative details

Inputs: account_id (required), image_hash (required), access_token, name, +11 more. Returns: result

create_adsetB
Create a new ad set in a Meta Ads account.

Args:
    account_id: Meta Ads account ID (format: act_XXXXXXXXX)
    campaign_id: Meta Ads campaign ID this ad set belongs to
    name: Ad set name
    optimization_goal: Conversion optimization goal (e.g., 'LINK_CLICKS', 'REACH', 'CONVERSIONS', 'APP_INSTALLS')
    billing_event: How you're charged (e.g., 'IMPRESSIONS', 'LINK_CLICKS')
    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 including age, location, interests, etc.
              Use targeting_automation.advantage_audience=1 for automatic audience finding
    bid_amount: Bid amount in account currency (in cents)
    bid_strategy: Bid strategy (e.g., 'LOWEST_COST', 'LOWEST_COST_WITH_BID_CAP')
    start_time: Start time in ISO 8601 format (e.g., '2023-12-01T12:00:00-0800')
    end_time: End time in ISO 8601 format
    dsa_beneficiary: DSA beneficiary (person/organization benefiting from ads) for European compliance
    promoted_object: Mobile app configuration for APP_INSTALLS campaigns. Required fields: application_id, object_store_url.
                    Optional fields: custom_event_type, pixel_id, page_id.
                    Example: {"application_id": "123456789012345", "object_store_url": "https://apps.apple.com/app/id123456789"}
    destination_type: Where users are directed after clicking the ad (e.g., 'APP_STORE', 'DEEPLINK', 'APP_INSTALL', 'ON_AD').
                      Required for mobile app campaigns and lead generation campaigns.
                      Use 'ON_AD' for lead generation campaigns where user interaction happens within the ad.
    is_dynamic_creative: Enable Dynamic Creative for this ad set (required when using dynamic creatives with asset_feed_spec/dynamic_creative_spec).
    access_token: Meta API access token (optional - will use cached token if not provided)

Inputs: account_id (required), campaign_id (required), name (required), optimization_goal (required), +14 more. Returns: result

create_budget_scheduleA
Create a budget schedule for a Meta Ads campaign.

Allows scheduling budget increases based on anticipated high-demand periods.
The times should be provided as Unix timestamps.

Args:
    campaign_id: Meta Ads campaign ID.
    budget_value: Amount of budget increase. Interpreted based on budget_value_type.
    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: Meta API access token (optional - will use cached token if not provided).
    
Returns:
    A JSON string containing the ID of the created budget schedule or an error message.

Inputs: campaign_id (required), budget_value (required), budget_value_type (required), time_start (required), +2 more. Returns: result

create_campaignA
Create a new campaign in a Meta Ads account.

Args:
    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 like BRAND_AWARENESS, LINK_CLICKS,
               CONVERSIONS, APP_INSTALLS, etc. are not valid for new
               campaigns and will cause a 400 error. Use the outcome-based
               values above (e.g., BRAND_AWARENESS → OUTCOME_AWARENESS).
    access_token: Meta API access token (optional - will use cached token if not provided)
    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) as a string (only used if use_adset_level_budgets=False)
    lifetime_budget: Lifetime budget in account currency (in cents) as a string (only used if use_adset_level_budgets=False)
    buying_type: Buying type (e.g., 'AUCTION')
    bid_strategy: Bid strategy. Must be one of: 'LOWEST_COST_WITHOUT_CAP', 'LOWEST_COST_WITH_BID_CAP', 'COST_CAP', 'LOWEST_COST_WITH_MIN_ROAS'.
    bid_cap: Bid cap in account currency (in cents) as a string
    spend_cap: Spending limit for the campaign in account currency (in cents) as a string
    campaign_budget_optimization: Whether to enable campaign budget optimization (only used if use_adset_level_budgets=False)
    ab_test_control_setups: Settings for A/B testing (e.g., [{"name":"Creative A", "ad_format":"SINGLE_IMAGE"}])
    use_adset_level_budgets: If True, budgets will be set at the ad set level instead of campaign level (default: False)

Inputs: account_id (required), name (required), objective (required), access_token, +11 more. Returns: result

estimate_audience_sizeA
Estimate audience size for targeting specifications using Meta's delivery_estimate API.

This function provides comprehensive audience estimation for complex targeting combinations
including demographics, geography, interests, and behaviors. It also maintains backwards
compatibility for simple interest validation.

Args:
    access_token: Meta API access token (optional - will use cached token if not provided)
    account_id: Meta Ads account ID (format: act_XXXXXXXXX) - required for comprehensive estimation
    targeting: Complete targeting specification including demographics, geography, interests, etc.
              Example: {
                  "age_min": 25,
                  "age_max": 65,
                  "geo_locations": {"countries": ["PL"]},
                  "flexible_spec": [
                      {"interests": [{"id": "6003371567474"}]},
                      {"interests": [{"id": "6003462346642"}]}
                  ]
              }
    optimization_goal: Optimization goal for estimation (default: "REACH"). 
                      Options: "REACH", "LINK_CLICKS", "IMPRESSIONS", "CONVERSIONS", etc.
    interest_list: [DEPRECATED - for backwards compatibility] List of interest names to validate
    interest_fbid_list: [DEPRECATED - for backwards compatibility] List of interest IDs to validate

Returns:
    JSON string with audience estimation results including estimated_audience_size,
    reach_estimate, and targeting validation

Inputs: access_token, account_id, targeting, optimization_goal, +2 more. Returns: result

fetchA
Fetch complete record data by ID.
It retrieves the full data for a specific record identified by its ID.

Args:
    id: The record ID to fetch (format: "type:id", e.g., "account:act_123456")
    
Returns:
    JSON response with complete record data including id, title, text, and metadata
    
Example Usage:
    fetch(id="account:act_123456789")
    fetch(id="campaign:23842588888640185")
    fetch(id="ad:23842614006130185")
    fetch(id="page:123456789")

Inputs: id (required). Returns: result

get_account_infoA
Get detailed information about a specific ad account.

Args:
    account_id: Meta Ads account ID (format: act_XXXXXXXXX)
    access_token: Meta API access token (optional - will use cached token if not provided)

Inputs: account_id (required), access_token. Returns: result

get_account_pagesA
Get pages associated with a Meta Ads account.

Args:
    account_id: Meta Ads account ID (format: act_XXXXXXXXX)
    access_token: Meta API access token (optional - will use cached token if not provided)

Returns:
    JSON response with pages associated with the account

Inputs: account_id (required), access_token. Returns: result

get_ad_accountsB
Get ad accounts accessible by a user.

Args:
    access_token: Meta API access token (optional - will use cached token if not provided)
    user_id: Meta user ID or "me" for the current user
    limit: Maximum number of accounts to return (default: 200)

Inputs: access_token, user_id, limit. Returns: result

get_ad_creativesA
Get creative details for a specific ad. Best if combined with get_ad_image to get the full image.

Args:
    ad_id: Meta Ads ad ID
    access_token: Meta API access token (optional - will use cached token if not provided)

Inputs: ad_id (required), access_token. Returns: result

get_ad_detailsA
Get detailed information about a specific ad.

Args:
    ad_id: Meta Ads ad ID
    access_token: Meta API access token (optional - will use cached token if not provided)

Inputs: ad_id (required), access_token. Returns: result

get_ad_imageA
Get, download, and visualize a Meta ad image in one step. Useful to see the image in the LLM.

Args:
    ad_id: Meta Ads ad ID
    access_token: Meta API access token (optional - will use cached token if not provided)

Returns:
    The ad image ready for direct visual analysis

Inputs: ad_id (required), access_token.

get_adsA
Get ads for a Meta Ads account with optional filtering.

Args:
    account_id: Meta Ads account ID (format: act_XXXXXXXXX)
    access_token: Meta API access token (optional - will use cached token if not provided)
    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

Inputs: account_id (required), access_token, limit, campaign_id, +1 more. Returns: result

get_adset_detailsA
Get detailed information about a specific ad set.

Args:
    adset_id: Meta Ads ad set ID
    access_token: Meta API access token (optional - will use cached token if not provided)

Example:
    To call this function through MCP, pass the adset_id as the first argument:
    {
        "args": "YOUR_ADSET_ID"
    }

Inputs: adset_id (required), access_token. Returns: result

get_adsetsA
Get ad sets for a Meta Ads account with optional filtering by campaign.

Args:
    account_id: Meta Ads account ID (format: act_XXXXXXXXX)
    access_token: Meta API access token (optional - will use cached token if not provided)
    limit: Maximum number of ad sets to return (default: 10)
    campaign_id: Optional campaign ID to filter by

Inputs: account_id (required), access_token, limit, campaign_id. Returns: result

get_campaign_detailsA
Get detailed information about a specific campaign.

Note: This function requests a specific set of fields ('id,name,objective,status,...'). 
The Meta API offers many other fields for campaigns (e.g., 'effective_status', 'source_campaign_id', etc.) 
that could be added to the 'fields' parameter in the code if needed.

Args:
    campaign_id: Meta Ads campaign ID
    access_token: Meta API access token (optional - will use cached token if not provided)

Inputs: campaign_id (required), access_token. Returns: result

get_campaignsA
Get campaigns for a Meta Ads account with optional filtering.

Note: By default, the Meta API returns a subset of available fields. 
Other fields like 'effective_status', 'special_ad_categories', 
'lifetime_budget', 'spend_cap', 'budget_remaining', 'promoted_object', 
'source_campaign_id', etc., might be available but require specifying them
in the API call (currently not exposed by this tool's parameters).

Args:
    account_id: Meta Ads account ID (format: act_XXXXXXXXX)
    access_token: Meta API access token (optional - will use cached token if not provided)
    limit: Maximum number of campaigns to return (default: 10)
    status_filter: Filter by effective status (e.g., 'ACTIVE', 'PAUSED', 'ARCHIVED').
                   Maps to the 'effective_status' API parameter, which expects an array
                   (this function handles the required JSON formatting). Leave empty for all statuses.
    objective_filter: Filter by campaign objective(s). Can be a single objective string or a list of objectives.
                     Valid objectives: 'OUTCOME_AWARENESS', 'OUTCOME_TRAFFIC', 'OUTCOME_ENGAGEMENT',
                     'OUTCOME_LEADS', 'OUTCOME_SALES', 'OUTCOME_APP_PROMOTION'.
                     Examples: 'OUTCOME_LEADS' or ['OUTCOME_LEADS', 'OUTCOME_SALES'].
                     Leave empty for all objectives.
    after: Pagination cursor to get the next set of results

Inputs: account_id (required), access_token, limit, status_filter, +2 more. Returns: result

get_insightsA
Get performance insights for a campaign, ad set, ad or account.

Args:
    object_id: ID of the campaign, ad set, ad or account
    access_token: Meta API access token (optional - will use cached token if not provided)
    time_range: Either a preset time range string or a dictionary with "since" and "until" dates in YYYY-MM-DD format
               Preset options: today, yesterday, this_month, last_month, this_quarter, maximum, data_maximum, 
               last_3d, last_7d, last_14d, last_28d, last_30d, last_90d, last_week_mon_sun, 
               last_week_sun_sat, last_quarter, last_year, this_week_mon_today, this_week_sun_today, this_year
               Dictionary example: {"since":"2023-01-01","until":"2023-01-31"}
    breakdown: Optional breakdown dimension. Valid values include:
               Demographic: age, gender, country, region, dma
               Platform/Device: device_platform, platform_position, publisher_platform, impression_device
               Creative Assets: ad_format_asset, body_asset, call_to_action_asset, description_asset, 
                              image_asset, link_url_asset, title_asset, video_asset, media_asset_url,
                              media_creator, media_destination_url, media_format, media_origin_url,
                              media_text_content, media_type, creative_relaxation_asset_type,
                              flexible_format_asset_type, gen_ai_asset_type
               Campaign/Ad Attributes: breakdown_ad_objective, breakdown_reporting_ad_id, app_id, product_id
               Conversion Tracking: coarse_conversion_value, conversion_destination, standard_event_content_type,
                                   signal_source_bucket, is_conversion_id_modeled, fidelity_type, redownload
               Time-based: hourly_stats_aggregated_by_advertiser_time_zone, 
                          hourly_stats_aggregated_by_audience_time_zone, frequency_value
               Extensions/Landing: ad_extension_domain, ad_extension_url, landing_destination, 
                                  mdsa_landing_destination
               Attribution: sot_attribution_model_type, sot_attribution_window, sot_channel, 
                           sot_event_type, sot_source
               Mobile/SKAN: skan_campaign_id, skan_conversion_id, skan_version, postback_sequence_index
               CRM/Business: crm_advertiser_l12_territory_ids, crm_advertiser_subvertical_id,
                            crm_advertiser_vertical_id, crm_ult_advertiser_id, user_persona_id, user_persona_name
               Advanced: hsid, is_auto_advance, is_rendered_as_delayed_skip_ad, mmm, place_page_id,
                        marketing_messages_btn_name, impression_view_time_advertiser_hour_v2, comscore_market,
                        comscore_market_code
    level: Level of aggregation (ad, adset, campaign, account)
    limit: Maximum number of results to return per page (default: 25, Meta API allows much higher values)
    after: Pagination cursor to get the next set of results. Use the 'after' cursor from previous response's paging.next field.
    action_attribution_windows: Optional list of attribution windows (e.g., ["1d_click", "7d_click", "1d_view"]).
               When specified, actions include additional fields for each window. The 'value' field always shows 7d_click.

Inputs: object_id (required), access_token, time_range, breakdown, +4 more. Returns: result

get_interest_suggestionsA
Get interest suggestions based on existing interests.

Args:
    interest_list: List of interest names to get suggestions for (e.g., ["Basketball", "Soccer"])
    access_token: Meta API access token (optional - will use cached token if not provided)  
    limit: Maximum number of suggestions to return (default: 25)

Returns:
    JSON string containing suggested interests with id, name, audience_size, and description fields

Inputs: interest_list (required), access_token, limit. Returns: result

search_ads_archiveA
    Search the Facebook Ads Library archive.

    Args:
        search_terms: The search query for ads.
        ad_reached_countries: List of country codes (e.g., ["US", "GB"]).
        access_token: Meta API access token (optional - will use cached token if not provided).
        ad_type: Type of ads to search for (e.g., POLITICAL_AND_ISSUE_ADS, HOUSING_ADS, ALL).
        limit: Maximum number of ads to return.
        fields: Comma-separated string of fields to retrieve for each ad.

    Example Usage via curl equivalent:
        curl -G \
        -d "search_terms='california'" \
        -d "ad_type=POLITICAL_AND_ISSUE_ADS" \
        -d "ad_reached_countries=['US']" \
        -d "fields=ad_snapshot_url,spend" \
        -d "access_token=<ACCESS_TOKEN>" \
        "https://graph.facebook.com/<API_VERSION>/ads_archive"
    

Inputs: search_terms (required), ad_reached_countries (required), access_token, ad_type, +2 more. Returns: result

search_behaviorsA
Get all available behavior targeting options.

Args:
    access_token: Meta API access token (optional - will use cached token if not provided)
    limit: Maximum number of results to return (default: 50)

Returns:
    JSON string containing behavior targeting options with id, name, audience_size bounds, path, and description

Inputs: access_token, limit. Returns: result

search_demographicsA
Get demographic targeting options.

Args:
    access_token: Meta API access token (optional - will use cached token if not provided)
    demographic_class: Type of demographics to retrieve. Options: 'demographics', 'life_events', 
                      'industries', 'income', 'family_statuses', 'user_device', 'user_os' (default: 'demographics')
    limit: Maximum number of results to return (default: 50)

Returns:
    JSON string containing demographic targeting options with id, name, audience_size bounds, path, and description

Inputs: access_token, demographic_class, limit. Returns: result

search_geo_locationsA
Search for geographic targeting locations.

Args:
    query: Search term for locations (e.g., "New York", "California", "Japan")
    access_token: Meta API access token (optional - will use cached token if not provided)
    location_types: Types of locations to search. Options: ['country', 'region', 'city', 'zip', 
                   'geo_market', 'electoral_district']. If not specified, searches all types.
    limit: Maximum number of results to return (default: 25)

Returns:
    JSON string containing location data with key, name, type, and geographic hierarchy information

Inputs: query (required), access_token, location_types, limit. Returns: result

search_interestsA
Search for interest targeting options by keyword.

Args:
    query: Search term for interests (e.g., "baseball", "cooking", "travel")
    access_token: Meta API access token (optional - will use cached token if not provided)
    limit: Maximum number of results to return (default: 25)

Returns:
    JSON string containing interest data with id, name, audience_size, and path fields

Inputs: query (required), access_token, limit. Returns: result

search_pages_by_nameA
Search for pages by name within an account.

Args:
    account_id: Meta Ads account ID (format: act_XXXXXXXXX)
    access_token: Meta API access token (optional - will use cached token if not provided)
    search_term: Search term to find pages by name (optional - returns all pages if not provided)

Returns:
    JSON response with matching pages

Inputs: account_id (required), access_token, search_term. Returns: result

update_adB
Update an ad with new settings.

Args:
    ad_id: Meta Ads ad ID
    status: Update ad status (ACTIVE, PAUSED, etc.)
    bid_amount: Bid amount in account currency (in cents for USD)
    tracking_specs: Optional tracking specifications (e.g., for pixel events).
    creative_id: ID of the creative to associate with this ad (changes the ad's image/content)
    access_token: Meta API access token (optional - will use cached token if not provided)

Inputs: ad_id (required), status, bid_amount, tracking_specs, +2 more. Returns: result

update_ad_creativeB
Update an existing ad creative with new content or settings.

Args:
    creative_id: Meta Ads creative ID to update
    access_token: Meta API access token (optional - will use cached token if not provided)
    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
    lead_gen_form_id: Lead generation form ID for lead generation campaigns. Required when using
                     lead generation CTAs like 'SIGN_UP', 'GET_OFFER', 'SUBSCRIBE', etc.

Returns:
    JSON response with updated creative details

Inputs: creative_id (required), access_token, name, message, +7 more. Returns: result

update_adsetB
Update an ad set with new settings including frequency caps and budgets.

Args:
    adset_id: Meta Ads ad set ID
    frequency_control_specs: List of frequency control specifications 
                             (e.g. [{"event": "IMPRESSIONS", "interval_days": 7, "max_frequency": 3}])
    bid_strategy: Bid strategy (e.g., 'LOWEST_COST_WITH_BID_CAP')
    bid_amount: Bid amount in account currency (in cents for USD)
    status: Update ad set status (ACTIVE, PAUSED, etc.)
    targeting: Complete targeting specifications (will replace existing targeting)
              (e.g. {"targeting_automation":{"advantage_audience":1}, "geo_locations": {"countries": ["US"]}})
    optimization_goal: Conversion optimization goal (e.g., 'LINK_CLICKS', 'CONVERSIONS', 'APP_INSTALLS', etc.)
    daily_budget: Daily budget in account currency (in cents) as a string
    lifetime_budget: Lifetime budget in account currency (in cents) as a string
    is_dynamic_creative: Enable/disable Dynamic Creative for this ad set.
    access_token: Meta API access token (optional - will use cached token if not provided)

Inputs: adset_id (required), frequency_control_specs, bid_strategy, bid_amount, +7 more. Returns: result

update_campaignA
Update an existing campaign in a Meta Ads account.

Args:
    campaign_id: Meta Ads campaign ID
    access_token: Meta API access token (optional - will use cached token if not provided)
    name: New campaign name
    status: New campaign status (e.g., 'ACTIVE', 'PAUSED')
    special_ad_categories: List of special ad categories if applicable
    daily_budget: New daily budget in account currency (in cents) as a string. 
                 Set to empty string "" to remove the daily budget.
    lifetime_budget: New lifetime budget in account currency (in cents) as a string.
                    Set to empty string "" to remove the lifetime budget.
    bid_strategy: New bid strategy
    bid_cap: New bid cap in account currency (in cents) as a string
    spend_cap: New spending limit for the campaign in account currency (in cents) as a string
    campaign_budget_optimization: Enable/disable campaign budget optimization
    objective: New campaign objective (Note: May not always be updatable)
    use_adset_level_budgets: If True, removes campaign-level budgets to switch to ad set level budgets

Inputs: campaign_id (required), access_token, name, status, +9 more. Returns: result

upload_ad_imageA
Upload an image to use in Meta Ads creatives.

Args:
    account_id: Meta Ads account ID (format: act_XXXXXXXXX)
    access_token: Meta API access token (optional - will use cached token if not provided)
    file: Data URL or raw base64 string of the image (e.g., "data:image/png;base64,iVBORw0KG...")
    image_url: Direct URL to an image to fetch and upload
    name: Optional name for the image (default: filename)

Returns:
    JSON response with image details including hash for creative creation

Inputs: account_id (required), access_token, file, image_url, +1 more. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.6/5.0

    Scored across 33 tools

    Disambiguation4/5

    Most tools have distinct purposes with clear boundaries between resource types (ads, ad sets, campaigns, creatives) and actions (create, get, update, search). However, some potential confusion exists between 'get_ad_details' and 'get_ad_creatives', and between 'search' and 'search_ads_archive', as their descriptions overlap slightly in scope.

    Naming Consistency5/5

    Tool names follow a highly consistent verb_noun pattern throughout, with clear conventions: create_*, get_*, update_*, search_*, estimate_*, fetch, upload_*. All tools use snake_case consistently, making the naming scheme predictable and easy to understand.

    Tool Count3/5

    With 33 tools, this is a large set that feels heavy for typical MCP usage. While Meta Ads is a complex domain, many tools could potentially be consolidated (e.g., multiple get_* tools for different resource types). The count borders on overwhelming for agents to navigate efficiently.

    Completeness5/5

    The tool surface provides comprehensive coverage of the Meta Ads domain, including full CRUD operations for all major resources (campaigns, ad sets, ads, creatives), targeting research tools, insights retrieval, authentication helpers, and image management. No obvious gaps exist for core advertising workflows.

    Related MCP Connectors