Meta Ads

npm version License: MIT

MCP server for the Meta Marketing API v26.0 — 134 tools for managing Facebook & Instagram ad campaigns, audiences, creatives, insights, catalogs, and more.

When to Use

Use this MCP when you need to:

• "Create a new Facebook ad campaign" — use create_campaign, create_adset, create_ad, and create_creative to build a full funnel
• "Check how my ads are performing today" — use get_account_insights or get_campaign_insights with today's date range
• "Pause all campaigns with ROAS below 2" — use list_campaigns + get_campaign_insights to find underperformers, then update_campaign to pause
• "Set up A/B test between two ad creatives" — use create_experiment to run a controlled test between ad sets
• "Create a lookalike audience from my customers" — use create_custom_audience, add_users_to_audience, then create_lookalike_audience
• "Upload ad images and create a carousel ad" — use upload_image for each image, then create_creative with carousel format
• "Get a detailed performance report for last 30 days" — use create_async_report for large date ranges, then get_async_report to retrieve
• "Search the Facebook Ad Library for competitor ads" — use search_ad_library to find public ad data
• "Set up automated rules to pause underperforming ads" — use create_rule with conditions like CPA > threshold
• "Manage my product catalog for dynamic ads" — use create_catalog, create_feed, and upload_feed to set up dynamic product ads

What's New in v1.6.0

• create_adset accepts bid_amount; creation and updates accept dsa_beneficiary and dsa_payor. For EU-targeted ads, supply each required value or configure the corresponding account default. The payer does not automatically copy the beneficiary.
• Ad and ad-set lists use campaign/ad-set edges when scoped. Combined campaign/ad-set filters and explicit account IDs are checked for consistency.
• create_adset and update_adset accept destination_type, attribution_spec, adset_schedule, pacing_type, and validate_only. Existing calls still perform their requested writes; set validate_only: true to ask Meta to validate without mutation. A successful validation does not create an ad set.
• Hourly schedules accept minute ranges and days (Sunday = 0); specify timezone_type as USER or ADVERTISER. Scheduling adds day_parting pacing. Meta validates effective lifetime budgeting, objective eligibility, and attribution restrictions. No budget or status is changed automatically.
• create_custom_audience accepts a JSON rule, pixel_id, and retention_days for rule-based audiences. Audience creation is a real write, not a dry run.

See the official ad-set creation and ad-set update contracts.

What's New in v1.5.0

• Conversion tools validate the existing events JSON input and send it as the required data array. Use test_event_code to verify receipt in Events Manager; offline events use a dataset ID and action_source=physical_store for store events.
• Creative creation accepts top-level destination_spec, wamo_whatsapp_identity_spec, and degrees_of_freedom_spec JSON objects. Dynamic creatives also accept object_story_spec for Page identity. To opt out of the v26 Shops destination default, set destination_spec to {"destination_type":"WEBSITE_AND_SHOP_OPT_OUT"}.
• Includes complete async-report result retrieval, token extension, and budget schedule fixes since v1.4.1. Some detailed Insights breakdowns require an Ads Manager opt-in; an empty response does not necessarily mean zero performance.

Installation

Requires Node.js 20 or later, including the MCP host's npx environment.

{
  "mcpServers": {
    "meta-ads": {
      "command": "npx",
      "args": ["-y", "@mikusnuz/meta-ads-mcp"],
      "env": {
        "META_ADS_ACCESS_TOKEN": "your-access-token",
        "META_AD_ACCOUNT_ID": "123456789",
        "META_APP_ID": "your-app-id",
        "META_APP_SECRET": "your-app-secret",
        "META_BUSINESS_ID": "your-business-id",
        "META_PIXEL_ID": "your-pixel-id"
      }
    }
  }
}

Environment Variables

Variable	Required	Description
META_ADS_ACCESS_TOKEN	Yes	Meta Marketing API access token
META_AD_ACCOUNT_ID	Yes	Ad account ID (numeric, without act_ prefix)
META_APP_ID	Optional	App ID — required for token exchange/extension and debug
META_APP_SECRET	Optional	App secret — required for token exchange/extension and debug
META_BUSINESS_ID	Optional	Business Manager ID — required for business tools
META_PIXEL_ID	Optional	Pixel ID — required for conversion tools

Tools (134)

Campaign Management (25)

Tool	Description
list_campaigns	List campaigns with filtering and pagination
get_campaign	Get campaign details by ID
create_campaign	Create a new campaign
update_campaign	Update campaign settings
delete_campaign	Delete a campaign
copy_campaign	Copy an existing campaign with ad sets and ads
get_campaign_adsets	List ad sets within a campaign
get_campaign_ads	List ads within a campaign
get_campaign_leads	Get leads from a campaign
list_adsets	List ad sets with filtering
get_adset	Get ad set details by ID
create_adset	Create a new ad set
update_adset	Update ad set settings
delete_adset	Delete an ad set
copy_adset	Copy an existing ad set to same or different campaign
get_adset_targeting_sentence	Get human-readable targeting description
get_adset_ads	List ads within an ad set
get_adset_leads	Get leads from an ad set
list_ads	List ads with filtering
get_ad	Get ad details by ID
create_ad	Create a new ad
update_ad	Update ad settings
delete_ad	Delete an ad
copy_ad	Copy an existing ad to same or different ad set
get_ad_preview	Generate ad preview HTML
get_delivery_estimate	Get delivery estimate for an ad set

Creatives (6)

Tool	Description
list_creatives	List ad creatives
get_creative	Get creative details
create_creative	Create a new ad creative
update_creative	Update an ad creative
create_dynamic_creative	Create a dynamic creative
generate_preview	Generate ad preview from creative spec without an existing ad

Media Assets (12)

Tool	Description
list_images	List ad images
upload_image	Upload an image from a URL or local file
get_image	Get image details
delete_image	Delete an image
list_videos	List ad videos
upload_video	Upload a video from a URL or local file
get_video	Get video details
delete_video	Delete a video
list_canvases	List Instant Experience canvases
get_canvas	Get canvas details
create_canvas	Create a canvas
delete_canvas	Delete a canvas

Audiences & Targeting (16)

Tool	Description
list_custom_audiences	List custom audiences
get_audience	Get audience details
create_custom_audience	Create a custom audience
update_audience	Update audience settings
delete_audience	Delete an audience
add_users_to_audience	Add users to a custom audience
remove_users_from_audience	Remove users from a custom audience
create_lookalike_audience	Create a lookalike audience
get_audience_health	Get audience health, delivery status, and match rate
list_saved_audiences	List saved audiences
get_saved_audience	Get saved audience details
search_targeting	Search targeting interests, behaviors, demographics
search_locations	Search targetable locations
search_targeting_map	Browse targeting category tree
get_reach_estimate	Estimate audience reach for targeting spec
get_targeting_suggestions	Get related targeting suggestions

Insights & Reporting (6)

Tool	Description
get_account_insights	Account-level performance metrics
get_campaign_insights	Campaign-level performance metrics
get_adset_insights	Ad set-level performance metrics
get_ad_insights	Ad-level performance metrics
create_async_report	Create an async insights report
get_async_report	Poll the report-run status, then fetch its /insights results when complete

date_preset values are lowercase Graph API identifiers such as today, yesterday, last_7d, and last_30d. create_async_report always creates an asynchronous job; get_async_report returns status immediately and, by default, fetches the paginated result edge after the status becomes Job Completed.

Leads (5)

Tool	Description
get_form_leads	Get leads from a lead form
get_lead	Get a single lead by ID
create_lead_form	Create a new lead generation form on a page
list_lead_forms	List lead gen forms for a page
get_lead_form	Get lead form details

Catalog & Commerce (17)

Tool	Description
list_catalogs	List product catalogs
get_catalog	Get catalog details
create_catalog	Create a product catalog
update_catalog	Update a catalog
list_product_sets	List product sets in a catalog
create_product_set	Create a product set
get_product_set	Get product set details
update_product_set	Update a product set
list_products	List products in a catalog
get_product	Get product details
update_product	Update a product
list_feeds	List data feeds for a catalog
create_feed	Create a data feed
upload_feed	Upload data to a feed
get_feed_uploads	Get feed upload history
batch_products	Batch create, update, or delete products (up to 5,000/request)
get_batch_status	Check status of a catalog batch operation

Automation & Rules (5)

Tool	Description
list_rules	List automated rules
get_rule	Get rule details
create_rule	Create an automated rule
update_rule	Update a rule
delete_rule	Delete a rule

Experiments (5)

Tool	Description
list_experiments	List A/B test experiments
create_experiment	Create an experiment
get_experiment	Get experiment details
update_experiment	Update an experiment
get_experiment_results	Get experiment results

Conversions (4)

Tool	Description
send_conversion_event	Send server-side conversion event via Conversions API
send_offline_event	Send an offline conversion event
list_offline_event_sets	List offline event sets
create_offline_event_set	Create an offline event set

Budget & Planning (8)

Tool	Description
list_budget_schedules	List schedules from a campaign or ad set budget_schedules edge
create_budget_schedule	Create a schedule on a campaign or ad set
update_budget_schedule	Update a budget schedule
delete_budget_schedule	Delete a budget schedule
list_rf_predictions	List Reach & Frequency predictions
create_rf_prediction	Create a Reach & Frequency prediction
get_rf_prediction	Get prediction details
delete_rf_prediction	Delete a prediction

Brand Safety (5)

Tool	Description
list_block_lists	List publisher block lists
create_block_list	Create a block list
add_to_block_list	Add URLs/domains to a block list
remove_from_block_list	Remove entries from a block list
delete_block_list	Delete a block list

Account & Business (15)

Tool	Description
get_ad_account	Get ad account details
list_ad_accounts	List ad accounts for a business
update_ad_account	Update ad account settings
get_account_activities	Get account activity log
list_account_users	List users with access to the account
list_businesses	List businesses you have access to
get_business	Get business details
list_business_ad_accounts	List ad accounts in a business
list_business_users	List users in a business
add_business_user	Add a user to a business
remove_business_user	Remove a user from a business
list_business_pages	List Facebook Pages owned by a business
list_business_instagram_accounts	List Instagram accounts owned by a business
list_system_users	List system users for a business
create_system_user	Create a system user

Auth & Token (3)

Tool	Description
exchange_token	Exchange short-lived token for long-lived token
refresh_token	Extend a valid long-lived user token through the documented exchange flow
debug_token	Debug/inspect token metadata

Ad Library (1)

Tool	Description
search_ad_library	Search Meta Ad Library for public ad data

Resources (3)

URI	Description
ads://account	Ad account overview — status, balance, currency, timezone, and total spend
ads://campaigns-overview	All active campaigns with budget information
ads://spending-today	Today's spending summary — spend, impressions, clicks, and reach

Prompts (3)

Prompt	Description
campaign_wizard	Step-by-step guide to create a full ad campaign from scratch
performance_report	Analyze ad performance with detailed breakdowns and recommendations
audience_builder	Build and refine target audiences using Meta's targeting tools

Permissions Required

Your Meta access token needs the following permissions depending on which tools you use:

Permission	Tools
ads_management	All campaign, ad set, ad, and creative CRUD operations
ads_read	All read/list operations and insights
business_management	Business tools, system users, account assignments
leads_retrieval	Lead form and lead data tools
catalog_management	Catalog, product set, product, and feed tools
pages_read_engagement	Lead forms linked to pages

License

MIT