Skip to main content
Glama

Meta Ads MCP

by pipeboard-co

Server Configuration

Describes the environment variables required to run the server.

NameRequiredDescriptionDefault
PIPEBOARD_API_TOKENYesYour Pipeboard API token for authentication

Schema

Prompts

Interactive templates invoked by user choice

NameDescription

No prompts

Resources

Contextual data attached and managed by the client

NameDescription
list_resources List all available resources (like ad creative images) Returns: Dictionary with resources list

Tools

Functions exposed to the LLM to take actions

NameDescription
get_ad_accounts
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)
get_account_info
Get detailed information about a specific ad account.

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
get_campaigns
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:
    access_token: Meta API access token (optional - 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 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.
    after: Pagination cursor to get the next set of results
get_campaign_details
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:
    access_token: Meta API access token (optional - will use cached token if not provided)
    campaign_id: Meta Ads campaign ID
create_campaign
Create a new campaign in a Meta Ads account.

Args:
    access_token: Meta API access token (optional - 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 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).
    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)
update_campaign
Update an existing campaign in a Meta Ads account.

Args:
    access_token: Meta API access token (optional - will use cached token if not provided)
    campaign_id: Meta Ads campaign ID (required)
    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
get_adsets
Get ad sets for a Meta Ads account with optional filtering by campaign.

Args:
    access_token: Meta API access token (optional - 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
get_adset_details
Get detailed information about a specific ad set.

Args:
    adset_id: Meta Ads ad set ID (required)
    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"
    }
create_adset
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
    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
    optimization_goal: Conversion optimization goal (e.g., 'LINK_CLICKS', 'REACH', 'CONVERSIONS', 'APP_INSTALLS')
    billing_event: How you're charged (e.g., 'IMPRESSIONS', 'LINK_CLICKS')
    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.
    access_token: Meta API access token (optional - will use cached token if not provided)
update_adset
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
    access_token: Meta API access token (optional - will use cached token if not provided)
get_ads
Get ads for a Meta Ads account with optional filtering.

Args:
    access_token: Meta API access token (optional - 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
get_ad_details
Get detailed information about a specific ad.

Args:
    access_token: Meta API access token (optional - will use cached token if not provided)
    ad_id: Meta Ads ad ID
create_ad
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)
get_ad_creatives
Get creative details for a specific ad. Best if combined with get_ad_image to get the full image.

Args:
    access_token: Meta API access token (optional - will use cached token if not provided)
    ad_id: Meta Ads ad ID
get_ad_image
Get, download, and visualize a Meta ad image in one step. Useful to see the image in the LLM.

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

Returns:
    The ad image ready for direct visual analysis
save_ad_image_locally
Get, download, and save a Meta ad image locally, returning the file path.

Args:
    access_token: Meta API access token (optional - will use cached token if not provided)
    ad_id: Meta Ads ad ID
    output_dir: Directory to save the image file (default: 'ad_images')

Returns:
    The file path to the saved image, or an error message string.
update_ad
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)
upload_ad_image
Upload an image to use in Meta Ads creatives.

Args:
    access_token: Meta API access token (optional - will use cached token if not provided)
    account_id: Meta Ads account ID (format: act_XXXXXXXXX)
    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
create_ad_creative
Create a new ad creative using an uploaded image hash.

Args:
    access_token: Meta API access token (optional - will use cached token if not provided)
    account_id: Meta Ads account ID (format: act_XXXXXXXXX)
    name: Creative name
    image_hash: Hash of the uploaded image
    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')
    instagram_actor_id: Optional Instagram account ID for Instagram placements

Returns:
    JSON response with created creative details
update_ad_creative
Update an existing ad creative with new content or settings.

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

Returns:
    JSON response with updated creative details
search_pages_by_name
Search for pages by name within an account.

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

Returns:
    JSON response with matching pages
get_account_pages
Get pages associated with a Meta Ads account.

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

Returns:
    JSON response with pages associated with the account
get_insights
Get performance insights for a campaign, ad set, ad or account.

Args:
    access_token: Meta API access token (optional - will use cached token if not provided)
    object_id: ID of the campaign, ad set, ad or account
    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)
get_login_link
Get a clickable login link for Meta Ads authentication.

NOTE: This method should only be used if you're using your own Facebook app.
If using Pipeboard authentication (recommended), set the PIPEBOARD_API_TOKEN
environment variable instead (token obtainable via https://pipeboard.co).

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

Returns:
    A clickable resource link for Meta authentication
search_ads_archive
    Search the Facebook Ads Library archive.

    Args:
        access_token: Meta API access token (optional - will use cached token if not provided).
        search_terms: The search query for ads.
        ad_type: Type of ads to search for (e.g., POLITICAL_AND_ISSUE_ADS, HOUSING_ADS, ALL).
        ad_reached_countries: List of country codes (e.g., ["US", "GB"]).
        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"
    
create_budget_schedule
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.
search_interests
Search for interest targeting options by keyword.

Args:
    access_token: Meta API access token (optional - 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:
    JSON string containing interest data with id, name, audience_size, and path fields
get_interest_suggestions
Get interest suggestions based on existing interests.

Args:
    access_token: Meta API access token (optional - 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:
    JSON string containing suggested interests with id, name, audience_size, and description fields
estimate_audience_size
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
search_behaviors
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
search_demographics
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
search_geo_locations
Search for geographic targeting locations.

Args:
    access_token: Meta API access token (optional - 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. 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
search
Search through Meta Ads data and return matching record IDs.

This tool is required for OpenAI ChatGPT Deep Research integration.
It searches across ad accounts, campaigns, ads, pages, and businesses to find relevant records
based on the provided query.

Args:
    access_token: Meta API access token (optional - will use cached token if not provided)
    query: Search query string to find relevant Meta Ads records
    
Returns:
    JSON response with list of matching record IDs
    
Example Usage:
    search(query="active campaigns")
    search(query="account spending")
    search(query="facebook ads performance")
    search(query="facebook pages")
    search(query="user businesses")
fetch
Fetch complete record data by ID.

This tool is required for OpenAI ChatGPT Deep Research integration.
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")

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/pipeboard-co/meta-ads-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server