@mikusnuz/meta Ads

meta-ads-mcp

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

Tools (134)

Campaign Management (25)

Creatives (6)

Media Assets (12)

Audiences & Targeting (16)

Insights & Reporting (6)

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)

Catalog & Commerce (17)

Automation & Rules (5)

Experiments (5)

Conversions (4)

Budget & Planning (8)

Brand Safety (5)

Account & Business (15)

Auth & Token (3)

Ad Library (1)

Resources (3)

Prompts (3)

Permissions Required

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

License

MIT