X402 API vs Meta Ads MCP

X402 API tools

No tool names declared yet. Check the project README from the listing page.

Meta Ads MCP tools 35

• get_ad_accounts Get ad accounts accessible by a user. amount_spent and balance are returned in currency units (e.g. USD dollars), not cents. 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: account_id: Meta Ads account ID (format: act_XXXXXXXXX) access_token: Meta API access token (optional - will use cached token if not provided) fields: Optional comma-separated Graph API fields to return. When provided, replaces the default field set. Useful for fetching extras like funding_source_details, spend_cap, is_prepay_account, min_daily_budget, disable_reason, capabilities. Default fields: id, name, account_id, account_status, amount_spent, balance, currency, age, business_city, business_country_code, timezone_name. For prepaid accounts (is_prepay_account=true, common in Brazil), the Business Manager "available balance" is the sum of funding_source_details STORED_BALANCE entries plus coupons — the `balance` field alone is the amount due to be billed, not the available pre-paid funds.
• 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', '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
• 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: campaign_id: Meta Ads campaign ID access_token: Meta API access token (optional - will use cached token if not provided)
• create_campaign Create a new Facebook or Instagram ad campaign in a Meta Ads account. Use this to start a new campaign with an ODAX objective (OUTCOME_LEADS, OUTCOME_SALES, OUTCOME_AWARENESS, OUTCOME_TRAFFIC, OUTCOME_ENGAGEMENT, OUTCOME_APP_PROMOTION), pick CBO (campaign budget optimization) or ABO (ad-set-level budgets), and set bid strategy, spend cap, and special ad categories. This is the first step of the campaign group → ad set → ad hierarchy on Meta. Returns the new campaign id. Also known as: create campaign, new campaign, make campaign, campaign group, ABO campaign, CBO campaign. Note: Campaigns do not support start_time for scheduling — set start_time on the ad set instead. 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 (default: LOWEST_COST_WITHOUT_CAP). Must be one of: 'LOWEST_COST_WITHOUT_CAP', 'LOWEST_COST_WITH_BID_CAP', 'COST_CAP', 'LOWEST_COST_WITH_MIN_ROAS'. WARNING: If you use LOWEST_COST_WITH_BID_CAP or COST_CAP, all child ad sets will require bid_amount to be set. 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. Note: Campaigns do not support start_time for scheduling — set start_time on the ad set instead. Migrating CBO (Advantage Campaign Budget) → ABO (ad set level budgets): Pass `adset_budgets` with one entry per ad set in the campaign. Meta atomically removes the campaign-level budget and assigns budgets at the ad set level in a single call. This is Meta's documented mechanism — the legacy `use_adset_level_budgets=true` flag attempts to clear `daily_budget`/`lifetime_budget` but Meta silently ignores the empty values, so the migration does not persist. 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). lifetime_budget: New lifetime budget in account currency (in cents). 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: Deprecated for CBO → ABO migration — use `adset_budgets` instead. Kept for backwards compatibility; sends empty `daily_budget`/ `lifetime_budget` which Meta silently ignores in most cases. adset_budgets: List of `{"adset_id": "...", "daily_budget": <cents>}` objects. Use to migrate from CBO to ABO: Meta removes the campaign-level Advantage budget and assigns the provided daily budgets at the ad set level in one atomic call. Example: [{"adset_id": "1234", "daily_budget": 5000}, {"adset_id": "5678", "daily_budget": 7000}]
• get_adsets 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
• get_adset_details 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" }
• 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 optimization_goal: Conversion optimization goal. Valid values depend on the campaign objective and destination_type. OUTCOME_ENGAGEMENT + destination_type=WEBSITE: OFFSITE_CONVERSIONS, LANDING_PAGE_VIEWS, LINK_CLICKS, IMPRESSIONS, REACH. OUTCOME_ENGAGEMENT + On Post (destination_type=ON_POST): POST_ENGAGEMENT, IMPRESSIONS, REACH. Also set promoted_object={page_id} at creation (immutable; without it create_ad fails with subcode 1885154). Do NOT use ON_AD here — ON_AD is the OUTCOME_LEADS instant-form destination and Meta rejects it for OUTCOME_ENGAGEMENT (subcode 1815715). OUTCOME_ENGAGEMENT + On Video (destination_type=ON_VIDEO): THRUPLAY, TWO_SECOND_CONTINUOUS_VIDEO_VIEWS. OUTCOME_ENGAGEMENT + On Event (destination_type=ON_EVENT): EVENT_RESPONSES, IMPRESSIONS, POST_ENGAGEMENT, REACH. OUTCOME_ENGAGEMENT + On Page (destination_type=ON_PAGE): PAGE_LIKES. OUTCOME_ENGAGEMENT + Messaging (MESSENGER/WHATSAPP/INSTAGRAM_DIRECT): CONVERSATIONS, LINK_CLICKS. OUTCOME_ENGAGEMENT "Profile and Page visits" (PROFILE_AND_PAGE_ENGAGEMENT with destination_type INSTAGRAM_PROFILE / FACEBOOK_PAGE / INSTAGRAM_PROFILE_AND_FACEBOOK_PAGE) is shown in Ads Manager but NOT supported via the Marketing API — Meta rejects every variant (code 100). Closest API-supported option is POST_ENGAGEMENT + ON_POST. OUTCOME_TRAFFIC + WEBSITE: LANDING_PAGE_VIEWS, LINK_CLICKS, IMPRESSIONS, REACH. OUTCOME_AWARENESS: REACH, IMPRESSIONS, AD_RECALL_LIFT, THRUPLAY. OUTCOME_LEADS: LEAD_GENERATION, QUALITY_LEAD (forms), QUALITY_CALL (calls), OFFSITE_CONVERSIONS, LINK_CLICKS (website). OUTCOME_SALES: OFFSITE_CONVERSIONS, VALUE, CONVERSATIONS, LINK_CLICKS, IMPRESSIONS, REACH. OUTCOME_APP_PROMOTION: APP_INSTALLS, APP_INSTALLS_AND_OFFSITE_CONVERSIONS, VALUE. 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. CBO NOTE: Do NOT set this if the parent campaign already has a budget (Campaign Budget Optimization / CBO mode). Meta only allows budgets at one level: either the campaign OR the ad set, not both. If the campaign has a daily_budget or lifetime_budget, omit this field — the ad set will automatically use the campaign budget. lifetime_budget: Lifetime budget in account currency (in cents) as a string. CBO NOTE: Do NOT set this if the parent campaign already has a budget (Campaign Budget Optimization / CBO mode). Omit this field when the campaign uses CBO — the ad set inherits the campaign budget automatically. targeting: Targeting specs (age, location, interests, etc). targeting_automation.advantage_audience defaults to 0 if not set (Meta API v24+ requirement). Set to 1 to enable Advantage+ Audience (requires age_max>=65). Use search_interests for interest IDs. bid_amount: Bid amount in account currency (in cents). REQUIRED for: LOWEST_COST_WITH_BID_CAP, COST_CAP, TARGET_COST. NOT USED by: LOWEST_COST_WITH_MIN_ROAS (uses bid_constraints instead). May also be required if the parent campaign's bid strategy requires it. bid_strategy: Bid strategy. Valid values: - 'LOWEST_COST_WITHOUT_CAP' (recommended) - no bid_amount required - 'LOWEST_COST_WITH_BID_CAP' - REQUIRES bid_amount - 'COST_CAP' - REQUIRES bid_amount - 'LOWEST_COST_WITH_MIN_ROAS' - REQUIRES bid_constraints with roas_average_floor, and optimization_goal='VALUE'. Does NOT use bid_amount. Note: 'LOWEST_COST' is NOT valid - use 'LOWEST_COST_WITHOUT_CAP'. Campaign-level bid strategy may constrain ad set choices. bid_constraints: Bid constraints dict. Required for LOWEST_COST_WITH_MIN_ROAS. Use {"roas_average_floor": <value>} where value = target ROAS * 10000. Example: 2.0x ROAS -> {"roas_average_floor": 20000} bid_adjustments: Bid multipliers per targeting dimension. Pass-through to Meta. Shape: {"user_groups": {"<dim>": {"<value>": <float>, "default": <float>}}} Dims: age, gender, user_os, device_platform, position_type, publisher_platform, user_bucket, home_location, locale, etc. Multipliers are floats, typically 0.0-1.0. Example: {"user_groups": {"user_os": {"iOS": 0.9, "Android": 0.7, "default": 1.0}}} NOTE: Writing bid_adjustments requires a Meta app capability that must be allowlisted. Apps without it get OAuthException (#3). start_time: Start time in ISO 8601 format (e.g., '2023-12-01T12:00:00-0800'). To schedule future delivery: set start_time to a future date and status=ACTIVE. Meta will show effective_status as SCHEDULED and automatically begin delivery at start_time. NOTE: Only ad set start_time controls delivery scheduling. Campaigns do not support start_time. end_time: End time in ISO 8601 format. Required when lifetime_budget is specified. dsa_beneficiary: DSA beneficiary for European compliance (person/org that benefits from ads). Required for EU-targeted ad sets along with dsa_payor. dsa_payor: DSA payor for European compliance (person/org paying for the ads). Required for EU-targeted ad sets along with dsa_beneficiary. promoted_object: For APP_INSTALLS: app config, required application_id + object_store_url. For OUTCOME_ENGAGEMENT On-Post (destination_type=ON_POST): set {"page_id": "<id>"} at creation — required for ads (else create_ad fails with subcode 1885154) and immutable afterward (cannot be added via update_adset). destination_type: Conversion location / where users go. Pass-through to Meta (no client-side validation). Common values: 'WEBSITE', 'WHATSAPP', 'MESSENGER', 'INSTAGRAM_DIRECT', 'APP', 'FACEBOOK', 'SHOP_AUTOMATIC'. OUTCOME_ENGAGEMENT on-asset locations: 'ON_POST' (post engagement; needs promoted_object={page_id}), 'ON_PAGE' (PAGE_LIKES), 'ON_EVENT', 'ON_VIDEO'. 'ON_AD' is the OUTCOME_LEADS instant-form destination — do NOT use it for OUTCOME_ENGAGEMENT (Meta rejects it with subcode 1815715). Also supports multi-channel combos like 'MESSAGING_MESSENGER_WHATSAPP'. is_dynamic_creative: Enable Dynamic Creative for this ad set. frequency_control_specs: Frequency cap specs. MUST be set at creation time — Meta makes this field immutable after the ad set is created (error 1815198). Only works with OUTCOME_AWARENESS campaigns + optimization_goal REACH or THRUPLAY. Example: [{"event": "IMPRESSIONS", "interval_days": 7, "max_frequency": 1}] multi_advertiser_ads: Set to 0 to opt out of Multi-Advertiser Ads, 1 to opt in. This is a TOP-LEVEL ad set parameter — do NOT put it inside the targeting object. regional_regulated_categories: List of regional regulated categories for the ad set. Required for ads targeting regulated regions (Taiwan, Australia, etc.). Valid values: TAIWAN_FINSERV, TAIWAN_UNIVERSAL, AUSTRALIA_FINSERV, INDIA_FINSERV, SINGAPORE_UNIVERSAL, THAILAND_UNIVERSAL. Example: ["TAIWAN_UNIVERSAL"] or ["TAIWAN_FINSERV", "TAIWAN_UNIVERSAL"] regional_regulation_identities: Dict of verified identity IDs for regional transparency compliance. Required when regional_regulated_categories is set. The identity IDs come from completing advertiser verification in Meta Business Settings. Keys depend on the categories declared: - TAIWAN_UNIVERSAL: taiwan_universal_beneficiary, taiwan_universal_payer - TAIWAN_FINSERV: taiwan_finserv_beneficiary, taiwan_finserv_payer - AUSTRALIA_FINSERV: australia_finserv_beneficiary, australia_finserv_payer - SINGAPORE_UNIVERSAL: singapore_universal_beneficiary, singapore_universal_payer Example: {"taiwan_universal_beneficiary": "<id>", "taiwan_universal_payer": "<id>"} attribution_spec: Attribution window specification for the ad set. Controls how conversions are attributed to ads. Default is 7-day click if not specified. Example for 1-day click: [{"event_type": "CLICK_THROUGH", "window_days": 1}] Example for 1-day click + 1-day view: [{"event_type": "CLICK_THROUGH", "window_days": 1}, {"event_type": "VIEW_THROUGH", "window_days": 1}] Valid event_type values: CLICK_THROUGH, VIEW_THROUGH. Valid window_days values: 1, 7, 28 (depends on event_type and optimization_goal). 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 name: New ad set name frequency_control_specs: Frequency control specs (e.g. [{"event": "IMPRESSIONS", "interval_days": 7, "max_frequency": 3}]) bid_strategy: Bid strategy. Valid values: - 'LOWEST_COST_WITHOUT_CAP' (recommended) - no bid_amount required - 'LOWEST_COST_WITH_BID_CAP' - REQUIRES bid_amount - 'COST_CAP' - REQUIRES bid_amount - 'LOWEST_COST_WITH_MIN_ROAS' - REQUIRES bid_constraints with roas_average_floor Note: 'LOWEST_COST' is NOT valid - use 'LOWEST_COST_WITHOUT_CAP'. bid_amount: Bid amount in cents. Required for LOWEST_COST_WITH_BID_CAP, COST_CAP, TARGET_COST. NOT USED by LOWEST_COST_WITH_MIN_ROAS (uses bid_constraints instead). bid_constraints: Bid constraints dict. Required for LOWEST_COST_WITH_MIN_ROAS. Use {"roas_average_floor": <value>} where value = target ROAS * 10000. Example: 2.0x ROAS -> {"roas_average_floor": 20000} bid_adjustments: Bid multipliers per targeting dimension. Pass-through to Meta. Shape: {"user_groups": {"<dim>": {"<value>": <float>, "default": <float>}}} See create_adset for full docs and dim list. NOTE: Writing requires a Meta app capability that must be allowlisted. status: Update ad set status (ACTIVE, PAUSED, etc.) targeting: Complete targeting specifications (replaces existing targeting) optimization_goal: Conversion optimization goal (e.g., 'LINK_CLICKS', 'CONVERSIONS', 'VALUE') daily_budget: Daily budget in account currency (in cents) lifetime_budget: Lifetime budget in account currency (in cents) is_dynamic_creative: Enable/disable Dynamic Creative for this ad set. WARNING: This field is immutable after ad set creation. Meta's API will return success but silently ignore the change. To change this, create a new ad set. start_time: Start time in ISO 8601 format (e.g., '2023-12-01T12:00:00-0800'). Use with status=ACTIVE to schedule the ad set for future delivery (effective_status will be SCHEDULED until start_time). end_time: End time in ISO 8601 format. Required when lifetime_budget is specified. dsa_beneficiary: DSA beneficiary for European compliance (person/org that benefits from ads). Required for EU-targeted ad sets along with dsa_payor. dsa_payor: DSA payor for European compliance (person/org paying for the ads). Required for EU-targeted ad sets along with dsa_beneficiary. multi_advertiser_ads: Set to 0 to opt out of Multi-Advertiser Ads, 1 to opt in. This is a TOP-LEVEL ad set parameter — do NOT put it inside the targeting object. regional_regulated_categories: List of regional regulated categories for the ad set. Required for ads targeting regulated regions (Taiwan, Australia, etc.). Valid values: TAIWAN_FINSERV, TAIWAN_UNIVERSAL, AUSTRALIA_FINSERV, INDIA_FINSERV, SINGAPORE_UNIVERSAL, THAILAND_UNIVERSAL. Set to null/empty to remove existing categories. regional_regulation_identities: Dict of verified identity IDs for regional transparency compliance. Required when regional_regulated_categories is set. Set individual keys to null to remove them. attribution_spec: Attribution window specification for the ad set. WARNING: Meta no longer supports updating attribution_spec after ad set creation (error 1504040). To change attribution windows, create a new ad set instead. This parameter is kept for compatibility but will be rejected by Meta's API. Valid event_type values: CLICK_THROUGH, VIEW_THROUGH. Valid window_days values: 1, 7, 28 (depends on event_type and optimization_goal). 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: 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
• get_ad_details 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)
• +23 more on the listing page