# mikusnuz/meta-ads-mcp [Health: Active]

**Category:** 🎯 Marketing  
**Repository:** https://github.com/mikusnuz/meta-ads-mcp  
**GitHub Stars:** 91  
**npm Downloads (last month):** 1837  
**Views:** 2  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/mikusnuz-meta-ads-mcp

## Description
MCP server for Meta Marketing API v25.0 — 123 tools for Facebook & Instagram ad campaigns, audiences, creatives, insights, catalogs, and automated rules.

## Tools
Capabilities this server exposes over MCP:

- **list_campaigns** — List campaigns in the ad account. Supports filtering by status and objective. Returns paginated results.
- **get_campaign** — Get details of a specific campaign by ID.
- **create_campaign** — Create a new ad campaign. Defaults to PAUSED status. Requires name and objective. Budget can be set at campaign or ad set level.
- **update_campaign** — Update an existing campaign. Only provided fields will be modified.
- **delete_campaign** — Delete a campaign. This action is irreversible.
- **copy_campaign** — Copy an existing campaign. Creates a duplicate with optional name override. Copies structure including ad sets and ads.
- **get_campaign_adsets** — Get all ad sets belonging to a specific campaign.
- **get_campaign_ads** — Get all ads belonging to a specific campaign.
- **get_campaign_leads** — Get leads generated by a specific campaign. Requires leads_retrieval permission.
- **list_adsets** — List ad sets in the ad account. Optionally filter by campaign or status.
- **get_adset** — Get details of a specific ad set by ID.
- **create_adset** — Create a new ad set. Requires name, campaign_id, budget, optimization_goal, billing_event, and targeting. Defaults to PAUSED status.
- **update_adset** — Update an existing ad set. Only provided fields will be modified.
- **delete_adset** — Delete an ad set. This action is irreversible.
- **copy_adset** — Copy an existing ad set. Creates a duplicate within the same or different campaign.
- **get_adset_targeting_sentence** — Get human-readable targeting description for an ad set. Converts targeting spec into readable sentences.
- **get_adset_ads** — Get all ads belonging to a specific ad set.
- **get_adset_leads** — Get leads generated by a specific ad set. Requires leads_retrieval permission.
- **list_ads** — List ads in the ad account. Optionally filter by campaign, ad set, or status.
- **get_ad** — Get details of a specific ad by ID.
- **create_ad** — Create a new ad. Requires name, adset_id, and creative (JSON object_story_spec). Defaults to PAUSED status.
- **update_ad** — Update an existing ad. Only provided fields will be modified.
- **delete_ad** — Delete an ad. This action is irreversible.
- **copy_ad** — Copy an existing ad. Creates a duplicate within the same or different ad set.
- **get_ad_preview** — Get a preview of an ad in a specific format. Returns HTML iframe for rendering.
- **get_delivery_estimate** — Get delivery estimate for an ad set, including estimated daily reach. Note: the delivery_estimate edge exists on the ad set (and ad account) node, not on individual ads. Also note: as of v26.0, the daily_outcomes_curve, budget_guardrail, and estimate_dau fields are no longer returned (removed with no replacement).
- **list_creatives** — List ad creatives in the ad account.
- **get_creative** — Get details of a specific ad creative by ID.
- **create_creative** — Create a new ad creative with object_story_spec. The spec defines the ad content (link, photo, or video) and the associated Facebook Page. Notes for v26.0: poll_spec and the poll type under interactive_components_spec are no longer supported and will be rejected. If the advertiser has a shop, eligible creatives now default to destination_spec.destination_type=WEBSITE_AND_SHOP — set it to WEBSITE_AND_SHOP_OPT_OUT to opt out.
- **update_creative** — Update an existing ad creative. Only name and url_tags can be modified after creation.
- **create_dynamic_creative** — Create a dynamic creative with asset_feed_spec. Meta automatically combines different images, videos, titles, bodies, and CTAs to find the best performing combinations.
- **generate_preview** — Generate an ad preview without needing an existing ad. Provide creative spec directly to see how it would look.
- **list_images** — List ad images uploaded to the ad account.
- **upload_image** — Upload an ad image from a public URL or a local file. Returns image hash for use in ad creatives. Note: fetching from a URL requires the app to have Meta's URL-fetch capability — if that fails with an OAuthException 'Application does not have the capability to make this API call', use file_path to upload the raw bytes instead, which does not require that capability.
- **get_image** — Get details of a specific ad image by ID.
- **delete_image** — Delete an ad image by hash. This action is irreversible.
- **list_videos** — List ad videos uploaded to the ad account.
- **upload_video** — Upload an ad video from a public URL or a local file. Returns video ID for use in ad creatives.
- **get_video** — Get details of a specific ad video by ID.
- **delete_video** — Delete an ad video. This action is irreversible.
- **list_canvases** — List Instant Experience (Canvas) creatives in the ad account.
- **get_canvas** — Get details of a specific Instant Experience (Canvas) by ID.
- **create_canvas** — Create a new Instant Experience (Canvas) on a Facebook Page. Requires page_id and body_elements JSON array defining the canvas layout.
- **delete_canvas** — Delete an Instant Experience (Canvas). This action is irreversible.
- **list_custom_audiences** — List custom audiences in the ad account.
- **get_audience** — Get details of a specific custom audience by ID.
- **create_custom_audience** — Create a new custom audience. Subtype determines the audience source (CUSTOM, WEBSITE, APP, OFFLINE_CONVERSION, LOOKALIKE, ENGAGEMENT, etc.).
- **update_audience** — Update an existing custom audience. Only provided fields will be modified.
- **delete_audience** — Delete a custom audience. This action is irreversible.
- **add_users_to_audience** — Add users to a custom audience. Payload must be a JSON string containing hashed user data with a schema array defining the data types (e.g. EMAIL, PHONE, FN, LN).
- **remove_users_from_audience** — Remove users from a custom audience. Payload format is the same as add_users_to_audience.
- **create_lookalike_audience** — Create a lookalike audience based on an existing custom audience. Ratio (1-10) determines how closely the new audience resembles the source.
- **get_audience_health** — Get health status and delivery readiness of a custom audience. Shows match rate, size, and operation status.
- **list_saved_audiences** — List saved audiences in the ad account. Saved audiences are reusable targeting presets.
- **get_saved_audience** — Get details of a specific saved audience by ID.
- **search_targeting** — Search for targeting options (interests, behaviors, demographics, etc.) by keyword. Use this to find valid targeting IDs for ad set targeting specs.
- **search_locations** — Search for geographic locations (countries, regions, cities, zip codes) for ad targeting.
- **search_targeting_map** — Map targeting IDs to their full details (names, types, paths). Useful for resolving IDs obtained from other endpoints.
- **get_reach_estimate** — Get estimated audience reach for a given targeting specification. Useful for planning campaigns before creating them.
- **get_targeting_suggestions** — Get targeting suggestions based on existing targeting criteria. Meta suggests related interests, behaviors, and demographics.
- **get_account_insights** — Get performance insights for the ad account. Returns metrics like impressions, clicks, spend, reach, etc.
- **get_campaign_insights** — Get performance insights for a specific campaign.
- **get_adset_insights** — Get performance insights for a specific ad set.
- **get_ad_insights** — Get performance insights for a specific ad.
- **create_async_report** — Create an async insight report for large data queries. Returns a report_run_id to poll with get_async_report.
- **get_async_report** — Check status and retrieve results of an async insight report.
- **get_form_leads** — Get leads submitted through a lead generation form.
- **get_lead** — Get details of a specific lead by ID.
- **list_lead_forms** — List lead generation forms for a Facebook Page.
- **create_lead_form** — Create a new lead generation form on a Facebook Page. Requires pages_manage_ads permission.
- **get_lead_form** — Get details of a specific lead generation form.
- **list_catalogs** — List product catalogs for the ad account.
- **get_catalog** — Get details of a specific product catalog.
- **create_catalog** — Create a new product catalog for the ad account.
- **update_catalog** — Update an existing product catalog.
- **list_product_sets** — List product sets within a catalog.
- **create_product_set** — Create a new product set within a catalog.
- **get_product_set** — Get details of a specific product set.
- **update_product_set** — Update an existing product set.
- **list_products** — List products within a catalog.
- **get_product** — Get details of a specific product.
- **update_product** — Update an existing product in a catalog.
- **batch_products** — Batch create, update, or delete products in a catalog. Supports up to 5,000 items per request. Update operations support upsert.
- **get_batch_status** — Check the status of a catalog batch operation.
- **list_feeds** — List product feeds for a catalog.
- **create_feed** — Create a new product feed for a catalog.
- **upload_feed** — Upload/trigger a feed file upload for a product feed.
- **get_feed_uploads** — Get upload history for a product feed.
- **list_rules** — List automated rules for the ad account.
- **get_rule** — Get details of a specific automated rule.
- **create_rule** — Create a new automated rule for the ad account.
- **update_rule** — Update an existing automated rule.
- **delete_rule** — Delete an automated rule.
- **list_experiments** — List A/B test experiments (ad studies) for the ad account.
- **create_experiment** — Create a new A/B test experiment (ad study).
- **get_experiment** — Get details of a specific experiment (ad study).
- **update_experiment** — Update an existing experiment (ad study).
- **get_experiment_results** — Get results/cells of an experiment (ad study).
- **send_conversion_event** — Send a server-side conversion event via the Conversions API (pixel).
- **send_offline_event** — Send an offline conversion event to an offline event set.
- **list_offline_event_sets** — List offline conversion data sets for the ad account.
- **create_offline_event_set** — Create a new offline conversion data set.
- **list_budget_schedules** — List ad budget schedules for the ad account. Returns paginated results.
- **create_budget_schedule** — Create a new ad budget schedule for the ad account.
- **update_budget_schedule** — Update an existing budget schedule. Only provided fields will be modified.
- **delete_budget_schedule** — Delete a budget schedule. This action is irreversible.
- **list_rf_predictions** — List reach & frequency predictions for the ad account. Returns paginated results.
- **create_rf_prediction** — Create a new reach & frequency prediction. Provide targeting spec as JSON string, budget in cents, and scheduling info.
- **get_rf_prediction** — Get details of a specific reach & frequency prediction by ID.
- **delete_rf_prediction** — Delete a reach & frequency prediction. This action is irreversible.
- **list_block_lists** — List publisher block lists for the ad account. Returns paginated results.
- **create_block_list** — Create a new publisher block list for the ad account.
- **add_to_block_list** — Add publisher URLs to an existing block list.
- **remove_from_block_list** — Remove publisher URLs from an existing block list.
- **delete_block_list** — Delete a publisher block list. This action is irreversible.
- **get_ad_account** — Get details of the configured ad account including status, balance, currency, timezone, and spend info.
- **list_ad_accounts** — List all ad accounts accessible by the current user. Returns paginated results.
- **update_ad_account** — Update the configured ad account settings. Only provided fields will be modified.
- **get_account_activities** — Get activity log for the ad account. Shows changes made to campaigns, ad sets, ads, etc.
- **list_account_users** — List users who have access to the ad account with their roles and permissions.
- **list_businesses** — List all businesses accessible by the current user. Returns paginated results.
- **get_business** — Get details of a specific business by ID.
- **list_business_ad_accounts** — List ad accounts owned by the configured business. Requires META_BUSINESS_ID env var.
- **list_business_users** — List users of the configured business. Requires META_BUSINESS_ID env var.
- **add_business_user** — Add a user to the configured business by email. Requires META_BUSINESS_ID env var.
- **remove_business_user** — Remove a user from the configured business. Requires META_BUSINESS_ID env var.
- **list_business_pages** — List Facebook Pages owned by the configured business. Requires META_BUSINESS_ID env var.
- **list_business_instagram_accounts** — List Instagram accounts owned by the configured business. Requires META_BUSINESS_ID env var.
- **list_system_users** — List system users of the configured business. Requires META_BUSINESS_ID env var.
- **create_system_user** — Create a new system user in the configured business. Requires META_BUSINESS_ID env var.
- **exchange_token** — Exchange a short-lived access token for a long-lived token. Requires META_APP_ID and META_APP_SECRET to be configured.
- **refresh_token** — Refresh a long-lived access token to extend its expiration. Returns a new long-lived token.
- **debug_token** — Debug an access token to inspect its properties, permissions, expiration, and validity. Requires META_APP_ID and META_APP_SECRET.
- **search_ad_library** — Search the Meta Ad Library for ads. Allows searching by keywords, countries, and ad type. Useful for competitive research and transparency.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "meta-ads-mcp": {
    "command": "npx",
    "args": ["-y","@mikusnuz/meta-ads-mcp"],
    "env": {
      "META_ADS_ACCESS_TOKEN": "",
      "META_AD_ACCOUNT_ID": ""
    }
  }
}
```

**Requires environment variables:** `META_ADS_ACCESS_TOKEN`, `META_AD_ACCOUNT_ID` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What mikusnuz/meta-ads-mcp does

mikusnuz/meta-ads-mcp exposes Meta Marketing API operations through MCP tools. The repository describes 134 tools covering Facebook and Instagram advertising, including campaign hierarchies, creatives, media assets, audiences, targeting, reporting, catalogs, and automated rules.

Campaign tools can list, inspect, create, update, copy, and delete campaigns, ad sets, and ads. Creation tools support common campaign-building sequences: create a campaign, add an ad set with targeting and budget, create a creative, and create an ad. New campaigns, ad sets, and ads default to paused status. The server also provides lead retrieval, ad previews, delivery estimates, and human-readable ad set targeting descriptions.

The broader toolset supports custom and lookalike audiences, audience health checks, targeting searches, location searches, reach estimates, image and video uploads, account and object-level insights, asynchronous reports, ad library searches, experiments, catalogs, feeds, and automated rules.

## How it works

An MCP-compatible host starts the package with `npx`, and the server sends requests to the Meta Marketing API using the configured credentials. Agents can combine read and write tools into workflows, such as finding campaigns with weak performance and then pausing them, or creating a full funnel from campaign through ad.

Insight tools accept date ranges and can query account, campaign, ad set, or ad performance. Large reporting jobs use an asynchronous flow: create the report, poll its status, and retrieve the completed results. Audience workflows can create an audience, add users, and then create a lookalike audience. The MCP server does not automatically make write operations safe or reversible; deletion and audience creation require particular care.

## Setup and configuration

mikusnuz/meta-ads-mcp requires Node.js 20 or later. Configure the MCP host to run:

```json
{
  "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_ADS_ACCESS_TOKEN` and `META_AD_ACCOUNT_ID` are required. The account ID is numeric and should not include the `act_` prefix. `META_APP_ID` and `META_APP_SECRET` support token exchange, extension, and debugging. `META_BUSINESS_ID` is used by business tools, while `META_PIXEL_ID` is used by conversion tools.

## Tools and capabilities

The mikusnuz/meta-ads-mcp MCP server includes tools for:

- Campaign, ad set, ad, and creative lifecycle management
- Image, video, canvas, and other media asset operations
- Custom, saved, and lookalike audience management
- Targeting, location, reach, and delivery estimates
- Account, campaign, ad set, and ad insights
- Asynchronous report creation and result retrieval
- Experiments, conversion events, catalogs, product feeds, and automated rules
- Facebook Ad Library searches and ad previews

Recent capabilities include ad set validation without mutation through `validate_only`, bid and scheduling fields, rule-based custom audiences, and creative destination settings for Shops. EU-targeted ads may require both DSA beneficiary and payer values or corresponding account defaults.

## Limitations and notes

Meta permissions and account configuration still govern what the tools can access or change. Lead retrieval requires `leads_retrieval` permission. Some business and conversion operations need the optional business or pixel identifiers. Deleting campaigns, ad sets, ads, creatives, media, or audiences can be irreversible.

The repository targets Meta Marketing API v26.0. In that version, several delivery-estimate fields are no longer returned, including `daily_outcomes_curve`, `budget_guardrail`, and `estimate_dau`. Poll and fetch asynchronous reports rather than expecting large insight queries to complete immediately. Detailed insight breakdowns may require Ads Manager opt-in, so an empty response does not necessarily indicate zero performance.

_Full upstream README: https://allmcps.com/mcp/mikusnuz-meta-ads-mcp/readme_