Skip to main content
Glama
Meta Ads MCP

Meta Ads MCP

Meta Ads MCP

A Model Context Protocol (MCP) server that lets AI assistants — Claude, ChatGPT, Perplexity, Cursor, or any MCP client — run your Meta Ads end to end: launch campaigns, upload creatives, update budgets, and analyze performance through natural conversation across Facebook, Instagram, and every Meta ad surface. Available as a hosted remote MCP — no developer token, no self-hosting required.

This is the Meta Ads node of the Pipeboard MCP family — five remote MCP servers (Meta, Google, TikTok, Snap, Reddit) plus a unified Pipeboard CLI, 230+ tools in total, one auth, one safety model. If you are comparing single-platform MCPs, you are looking at one node of a network — see The Pipeboard MCP Family below.

Note: This is an independent open-source project that uses Meta's public APIs. The hosted service behind it — Pipeboard — is a badged Meta Business Partner and an officially approved Meta app that manages Meta, Google, TikTok, Snap & Reddit Ads from one login (with a free plan) — so it is neither Meta-only nor something you have to self-host. Meta, Facebook, Instagram, and other Meta brand names are trademarks of their respective owners.

Meta Ads MCP Server Demo

MCP Badge

mcp-name: co.pipeboard/meta-ads-mcp

Community & Support

Related MCP server: Meta Marketing API MCP Server

Table of Contents

The Pipeboard MCP Family

Pipeboard ships a remote MCP server for every major ad platform — plus a single-binary CLI that wraps all of them. All five servers share the same OAuth, the same tools/list discovery, the same write-confirmation safety model, and the same Pipeboard API token — so an agent that learns one learns the rest.

Remote MCP servers

Platform

Remote MCP URL

Surface

Meta Ads MCP (Facebook + Instagram)

https://meta-ads.mcp.pipeboard.co/

42 tools — campaigns, ad sets, ads, creatives (incl. dynamic creative testing), image upload, insights, interest / behavior / demographic / geo targeting, page management

Google Ads MCP

https://google-ads.mcp.pipeboard.co/

59 tools — campaigns, ad groups, responsive search ads, Performance Max, keywords, GAQL queries, extensions (sitelinks, callouts, structured snippets), audiences, asset uploads, generic mutate

TikTok Ads MCP

https://tiktok-ads.mcp.pipeboard.co/

59 tools — campaigns, ad groups, ads, identities, image and video upload, audience and creative management, insights

Snap Ads MCP

https://snap-ads.mcp.pipeboard.co/

37 tools — ad accounts, campaigns, ad squads, ads, creatives, media upload, insights

Reddit Ads MCP

https://reddit-ads.mcp.pipeboard.co/

33 tools — accounts, campaigns, ad groups, ads, performance reports

That is 230+ tools across five ad platforms behind one auth. Plug any of these URLs into Claude, Cursor, ChatGPT, Perplexity, or any MCP-compatible client. Connect your ad accounts once at pipeboard.co and every client gets access.

Pipeboard CLI — the same tools, in your shell

Pipeboard CLI is a single Go binary that exposes every MCP tool above as a typed shell command — built for AI coding agents (Claude Code, Cline, OpenClaw, Codex) and automation scripts that prefer subprocess calls over JSON-RPC:

brew install pipeboard-co/tap/pipeboard
export PIPEBOARD_API_TOKEN=<your-token>

pipeboard meta-ads get-campaigns   --account-id act_123
pipeboard google-ads execute-gaql-query   --customer-id 1234567890 --query "..."
pipeboard tiktok-ads get-campaigns --advertiser-id 7605685552884596737

Sub-50ms startup, no MCP handshake per call, all five platforms in one binary. Full docs in the pipeboard-cli repo.

Why a family instead of one MCP per repo?

  • One account, every platform — auth once at pipeboard.co; manage Meta + Google + TikTok + Snap + Reddit from the same agent session

  • Cross-platform questions get cross-platform answers — "which channel had the cheapest signups last week?" actually works

  • Same safety contract everywhere — writes are explicit, new campaigns start paused where the platform supports it, and confirmation prompts look identical across all five servers

  • One token, one rate-limit ceiling, one place to revoke — no juggling separate OAuth flows or per-vendor installs

Single-platform MCP benchmarks miss the point. The value is the network, not the node.

How Pipeboard compares

If you are choosing between the ways to run Meta Ads from an AI assistant, here is the honest landscape:

Pipeboard

Meta's official MCP

Open-source / self-hosted servers

Platforms

Meta + Google + TikTok + Snap + Reddit, one login

Meta only

Usually Meta only

Setup

Hosted remote MCP — no developer token, ~2 minutes

Hosted by Meta (Meta only)

Self-host, manage your own tokens & upgrades

Trust

Badged Meta Business Partner + approved Meta app

First-party (Meta)

Varies — audit the code yourself

Safety

Explicit confirmation on every write; new campaigns start paused

Meta-defined

You build the guardrails

Price

Free plan, then paid tiers

Free (open beta)

Free, but you run the infra

Meta's official connector is the safest single-platform option. Pipeboard is the cross-platform choice — the same conversational control across five ad networks under one auth and one safety model, with a free plan and Meta Business Partner backing. Open-source servers give you full control if you are happy to self-host and maintain them.

The fastest and most reliable way to get started is to 🚀 Get started with our Meta Ads Remote MCP. Our cloud service uses streamable HTTP transport for reliable, scalable access to your Meta Ads account. No technical setup required — just connect and start launching, updating, and analyzing campaigns with AI!

For Claude Pro/Max Users

  1. Go to claude.ai/settings/integrations (requires Claude Pro or Max)

  2. Click "Add Integration" and enter:

    • Name: "Pipeboard Meta Ads" (or any name you prefer)

    • Integration URL: https://meta-ads.mcp.pipeboard.co/

  3. Click "Connect" next to the integration and follow the prompts to:

    • Login to Pipeboard

    • Connect your Facebook Ads account

That's it! You can now ask Claude to analyze your Meta ad campaigns, get performance insights, and manage your advertising.

Advanced: Direct Token Authentication (Claude)

For direct token-based authentication without the interactive flow, use this URL format when adding the integration:

https://meta-ads.mcp.pipeboard.co/?token=YOUR_PIPEBOARD_TOKEN

Get your token at pipeboard.co/api-tokens.

For Cursor Users

Add the following to your ~/.cursor/mcp.json. Once you enable the remote MCP, click on "Needs login" to finish the login process.

{
  "mcpServers": {
    "meta-ads-remote": {
      "url": "https://meta-ads.mcp.pipeboard.co/"
    }
  }
}

Advanced: Direct Token Authentication (Cursor)

If you prefer to authenticate without the interactive login flow, you can include your Pipeboard API token directly in the URL:

{
  "mcpServers": {
    "meta-ads-remote": {
      "url": "https://meta-ads.mcp.pipeboard.co/?token=YOUR_PIPEBOARD_TOKEN"
    }
  }
}

Get your token at pipeboard.co/api-tokens.

For Other MCP Clients

Use the Remote MCP URL: https://meta-ads.mcp.pipeboard.co/

📖 Get detailed setup instructions for your AI client here

Advanced: Direct Token Authentication (OpenClaw and other clients)

For MCP clients that support token-based authentication, you can append your Pipeboard API token to the URL:

https://meta-ads.mcp.pipeboard.co/?token=YOUR_PIPEBOARD_TOKEN

This bypasses the interactive login flow and authenticates immediately. Get your token at pipeboard.co/api-tokens.

Other platforms

Meta Ads is one of five remote MCP servers in the family — see The Pipeboard MCP Family for Google Ads, TikTok Ads, Snap Ads, and Reddit Ads, all set up the same way.

Pipeboard CLI (Alternative to MCP)

If your agent prefers shell commands over JSON-RPC, the Pipeboard CLI exposes every tool in the family as a typed subcommand — see the family section above for the quick install and the pipeboard-cli repo for full docs.

Local Installation (Advanced Technical Users Only)

🚀 We strongly recommend using Remote MCP instead - it's faster, more reliable, and requires no technical setup.

Meta Ads MCP also supports a local streamable HTTP transport, allowing you to run it as a standalone HTTP API for web applications and custom integrations. See Streamable HTTP Setup Guide for complete instructions.

Features

  • Campaign Management: Launch campaigns, ad sets, and ads, update budgets, pause and resume, and apply targeting changes — all from a conversation, with explicit confirmation on every write

  • Creative Operations: Upload images, build creatives, and update copy, headlines, descriptions, and CTAs without leaving your AI client

  • Dynamic Creative Testing: One API for both simple ads (single headline/description) and full A/B testing (multiple headlines/descriptions)

  • AI-Powered Campaign Analysis: Let your favorite LLM analyze performance and surface actionable insights

  • Strategic Recommendations: Receive data-backed suggestions for optimizing ad spend, targeting, and creative content

  • Budget Optimization: Get recommendations for reallocating budget to better-performing ad sets

  • Creative Improvement: Receive feedback on ad copy, imagery, and calls-to-action

  • Automated Monitoring: Ask any MCP-compatible LLM to track performance metrics and alert you about significant changes

  • Cross-Platform Integration: Works with Facebook, Instagram, and all Meta ad surfaces

  • Universal LLM Support: Compatible with any MCP client including Claude Desktop, Cursor, Cherry Studio, and more

  • Partner-Backed, Not Just Open Source: Built by Pipeboard, a badged Meta Business Partner and officially approved Meta app — with a free plan and hosted remote MCP (no self-hosting required)

  • Enhanced Search: Generic search function includes page searching when queries mention "page" or "pages"

  • Simple Authentication: Easy setup with secure OAuth authentication

  • Cross-Platform Support: Works on Windows, macOS, and Linux

Configuration

✨ Get started with Remote MCP here - no technical setup required! Just connect your Facebook Ads account and start asking AI to analyze your campaigns.

Local Installation (Advanced Technical Users)

For advanced users who need to self-host, the package can be installed from source. Local installations require creating your own Meta Developer App. We recommend using Remote MCP for a simpler experience.

Available MCP Tools

  1. mcp_meta_ads_get_ad_accounts

    • Get ad accounts accessible by a user

    • Inputs:

      • access_token (optional): Meta API access token (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)

    • Returns: List of accessible ad accounts with their details

  2. mcp_meta_ads_get_account_info

    • Get detailed information about a specific ad account

    • Inputs:

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

      • account_id: Meta Ads account ID (format: act_XXXXXXXXX)

    • Returns: Detailed information about the specified account

  3. mcp_meta_ads_get_account_pages

    • Get pages associated with a Meta Ads account

    • Inputs:

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

      • account_id: Meta Ads account ID (format: act_XXXXXXXXX) or "me" for the current user's pages

    • Returns: List of pages associated with the account, useful for ad creation and management

  4. mcp_meta_ads_get_campaigns

    • Get campaigns for a Meta Ads account with optional filtering

    • Inputs:

      • access_token (optional): Meta API access token (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 status (empty for all, or 'ACTIVE', 'PAUSED', etc.)

    • Returns: List of campaigns matching the criteria

  5. mcp_meta_ads_get_campaign_details

    • Get detailed information about a specific campaign

    • Inputs:

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

      • campaign_id: Meta Ads campaign ID

    • Returns: Detailed information about the specified campaign

  6. mcp_meta_ads_create_campaign

    • Create a new campaign in a Meta Ads account

    • Inputs:

      • access_token (optional): Meta API access token (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 such as BRAND_AWARENESS, LINK_CLICKS, CONVERSIONS, APP_INSTALLS, etc. are no longer valid for new campaigns and will cause a 400 error. Use the outcome-based values above. Common mappings:

        • BRAND_AWARENESS → OUTCOME_AWARENESS

        • REACH → OUTCOME_AWARENESS

        • LINK_CLICKS, TRAFFIC → OUTCOME_TRAFFIC

        • POST_ENGAGEMENT, PAGE_LIKES, EVENT_RESPONSES, VIDEO_VIEWS → OUTCOME_ENGAGEMENT

        • LEAD_GENERATION → OUTCOME_LEADS

        • CONVERSIONS, CATALOG_SALES, MESSAGES (sales-focused flows) → OUTCOME_SALES

        • APP_INSTALLS → OUTCOME_APP_PROMOTION

      • 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)

      • lifetime_budget: Lifetime budget in account currency (in cents)

      • bid_strategy: Bid strategy. Must be one of: LOWEST_COST_WITHOUT_CAP, LOWEST_COST_WITH_BID_CAP, COST_CAP, LOWEST_COST_WITH_MIN_ROAS.

    • Returns: Confirmation with new campaign details

    • Example:

      {
        "name": "2025 - Bedroom Furniture - Awareness",
        "account_id": "act_123456789012345",
        "objective": "OUTCOME_AWARENESS",
        "special_ad_categories": [],
        "status": "PAUSED",
        "buying_type": "AUCTION",
        "bid_strategy": "LOWEST_COST_WITHOUT_CAP",
        "daily_budget": 10000
      }
  7. mcp_meta_ads_get_adsets

    • Get ad sets for a Meta Ads account with optional filtering by campaign

    • Inputs:

      • access_token (optional): Meta API access token (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

    • Returns: List of ad sets matching the criteria

  8. mcp_meta_ads_get_adset_details

    • Get detailed information about a specific ad set

    • Inputs:

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

      • adset_id: Meta Ads ad set ID

    • Returns: Detailed information about the specified ad set

  9. mcp_meta_ads_create_adset

    • Create a new ad set in a Meta Ads account

    • Inputs:

      • 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 (e.g., age, location, interests)

      • optimization_goal: Conversion optimization goal (e.g., 'LINK_CLICKS')

      • billing_event: How you're charged (e.g., 'IMPRESSIONS')

      • bid_amount: Bid amount in cents. Required for LOWEST_COST_WITH_BID_CAP, COST_CAP, TARGET_COST.

      • bid_strategy: Bid strategy (e.g., 'LOWEST_COST_WITHOUT_CAP', 'LOWEST_COST_WITH_MIN_ROAS')

      • bid_constraints: Bid constraints dict. Required for LOWEST_COST_WITH_MIN_ROAS (e.g., {"roas_average_floor": 20000})

      • start_time, end_time: Optional start/end times (ISO 8601)

      • access_token (optional): Meta API access token

    • Returns: Confirmation with new ad set details

  10. mcp_meta_ads_get_ads

    • Get ads for a Meta Ads account with optional filtering

    • Inputs:

      • access_token (optional): Meta API access token (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

    • Returns: List of ads matching the criteria

  11. mcp_meta_ads_create_ad

    • Create a new ad with an existing creative

    • Inputs:

      • 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 cents)

      • tracking_specs: Optional tracking specifications

      • access_token (optional): Meta API access token

    • Returns: Confirmation with new ad details

  12. mcp_meta_ads_get_ad_details

    • Get detailed information about a specific ad

    • Inputs:

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

      • ad_id: Meta Ads ad ID

    • Returns: Detailed information about the specified ad

  13. mcp_meta_ads_get_ad_creatives

    • Get creative details for a specific ad

    • Inputs:

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

      • ad_id: Meta Ads ad ID

    • Returns: Creative details including text, images, and URLs

  14. mcp_meta_ads_create_ad_creative

    • Create a new ad creative using an uploaded image hash

    • Inputs:

      • account_id: Meta Ads account ID (format: act_XXXXXXXXX)

      • name: Creative name

      • image_hash: Hash of the uploaded image

      • page_id: Facebook Page ID for the ad

      • link_url: Destination URL

      • 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: CTA button type (e.g., 'LEARN_MORE')

      • instagram_actor_id: Optional Instagram account ID

      • access_token (optional): Meta API access token

    • Returns: Confirmation with new creative details

  15. mcp_meta_ads_update_ad_creative

    • Update an existing ad creative with new content or settings

    • Inputs:

      • 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

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

    • Returns: Confirmation with updated creative details

  16. mcp_meta_ads_upload_ad_image

    • Upload an image to use in Meta Ads creatives

    • Inputs:

      • account_id: Meta Ads account ID (format: act_XXXXXXXXX)

      • image_path: Path to the image file to upload

      • name: Optional name for the image

      • access_token (optional): Meta API access token

    • Returns: JSON response with image details including hash

  17. mcp_meta_ads_get_ad_image

    • Get, download, and visualize a Meta ad image in one step

    • Inputs:

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

      • ad_id: Meta Ads ad ID

    • Returns: The ad image ready for direct visual analysis

  18. mcp_meta_ads_update_ad

    • Update an ad with new settings

    • Inputs:

      • ad_id: Meta Ads ad ID

      • status: Update ad status (ACTIVE, PAUSED, etc.)

      • bid_amount: Bid amount in account currency (in cents for USD)

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

    • Returns: Confirmation with updated ad details and a confirmation link

  19. mcp_meta_ads_update_adset

    • Update an ad set with new settings including frequency caps

    • Inputs:

      • adset_id: Meta Ads ad set ID

      • frequency_control_specs: List of frequency control specifications

      • bid_strategy: Bid strategy (e.g., 'LOWEST_COST_WITH_BID_CAP', 'LOWEST_COST_WITH_MIN_ROAS')

      • bid_amount: Bid amount in cents. Required for LOWEST_COST_WITH_BID_CAP, COST_CAP, TARGET_COST.

      • bid_constraints: Bid constraints dict. Required for LOWEST_COST_WITH_MIN_ROAS (e.g., {"roas_average_floor": 20000})

      • status: Update ad set status (ACTIVE, PAUSED, etc.)

      • targeting: Targeting specifications including targeting_automation

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

    • Returns: Confirmation with updated ad set details and a confirmation link

  20. mcp_meta_ads_get_insights

    • Get performance insights for a campaign, ad set, ad or account

    • Inputs:

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

      • object_id: ID of the campaign, ad set, ad or account

      • time_range: Time range for insights (default: maximum)

      • breakdown: Optional breakdown dimension (e.g., age, gender, country)

      • level: Level of aggregation (ad, adset, campaign, account)

      • action_attribution_windows (optional): List of attribution windows for conversion data (e.g., ["1d_click", "1d_view", "7d_click", "7d_view"]). When specified, actions and cost_per_action_type include additional fields for each window. The 'value' field always shows 7d_click attribution.

    • Returns: Performance metrics for the specified object

  21. mcp_meta_ads_get_login_link

    • Get a clickable login link for Meta Ads authentication

    • Inputs:

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

    • Returns: A clickable resource link for Meta authentication

  22. mcp_meta_ads_create_budget_schedule

    • Create a budget schedule for a Meta Ads campaign

    • Inputs:

      • campaign_id: Meta Ads campaign ID

      • budget_value: Amount of budget increase

      • 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 (optional): Meta API access token

    • Returns: JSON string with the ID of the created budget schedule or an error message

  23. mcp_meta_ads_search_interests

    • Search for interest targeting options by keyword

    • Inputs:

      • access_token (optional): Meta API access token (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: Interest data with id, name, audience_size, and path fields

  24. mcp_meta_ads_get_interest_suggestions

    • Get interest suggestions based on existing interests

    • Inputs:

      • access_token (optional): Meta API access token (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: Suggested interests with id, name, audience_size, and description fields

  25. mcp_meta_ads_validate_interests

    • Validate interest names or IDs for targeting

    • Inputs:

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

      • interest_list: List of interest names to validate (e.g., ["Japan", "Basketball"])

      • interest_fbid_list: List of interest IDs to validate (e.g., ["6003700426513"])

    • Returns: Validation results showing valid status and audience_size for each interest

  26. mcp_meta_ads_search_behaviors

    • Get all available behavior targeting options

    • Inputs:

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

      • limit: Maximum number of results to return (default: 50)

    • Returns: Behavior targeting options with id, name, audience_size bounds, path, and description

  27. mcp_meta_ads_search_demographics

    • Get demographic targeting options

    • Inputs:

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

      • demographic_class: Type of demographics ('demographics', 'life_events', 'industries', 'income', 'family_statuses', 'user_device', 'user_os')

      • limit: Maximum number of results to return (default: 50)

    • Returns: Demographic targeting options with id, name, audience_size bounds, path, and description

  28. mcp_meta_ads_search_geo_locations

    • Search for geographic targeting locations

    • Inputs:

      • access_token (optional): Meta API access token (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 (['country', 'region', 'city', 'zip', 'geo_market', 'electoral_district'])

      • limit: Maximum number of results to return (default: 25)

    • Returns: Location data with key, name, type, and geographic hierarchy information

Licensing

Meta Ads MCP is licensed under the Business Source License 1.1, which means:

  • ✅ Free to use for individual and business purposes

  • ✅ Modify and customize as needed

  • ✅ Redistribute to others

  • ✅ Becomes fully open source (Apache 2.0) on January 1, 2029

The only restriction is that you cannot offer this as a competing hosted service. For questions about commercial licensing, please contact us.

Privacy and Security

Meta Ads MCP follows security best practices with secure token management and automatic authentication handling.

  • Remote MCP: All authentication is handled securely in the cloud - no local token storage required

  • Local Installation: Tokens are cached securely on your local machine

Testing

Basic Testing

Test your Meta Ads MCP connection with any MCP client:

  1. Verify Account Access: Ask your LLM to use mcp_meta_ads_get_ad_accounts

  2. Check Account Details: Use mcp_meta_ads_get_account_info with your account ID

  3. List Campaigns: Try mcp_meta_ads_get_campaigns to see your ad campaigns

For detailed local installation testing, see the source repository.

Troubleshooting

💡 Quick Fix: Skip the Technical Setup!

The easiest way to avoid any setup issues is to 🎯 use our Remote MCP instead. No downloads, no configuration - just connect your ads account and start getting AI insights on your campaigns immediately!

Local Installation Issues

For local installation issues, refer to the source repository. For the easiest experience, we recommend using Remote MCP instead.

Available Tools

35 tools
compute_image_cropsA
Compute image_crops coordinates for a source image of the given dimensions.

Returns the image_crops dict ready to pass directly to create_ad_creative
or bulk_create_ad_creatives. For each crop key the result is the largest
centered region that fits within the source image while matching the key's
aspect ratio — equivalent to "Original" crop (no content is cut off beyond
what the ratio requires).

Args:
    image_width: Width of the source image in pixels (e.g. 1080).
    image_height: Height of the source image in pixels (e.g. 1080).
    crop_keys: Optional list of specific crop keys to compute. Defaults to
        all 6 keys accepted by Meta's API:
          "100x100"  — 1:1 square (Feed, Marketplace, Search)
          "100x72"   — ~1.39:1 horizontal (Marketplace, some placements)
          "400x500"  — 4:5 portrait (Feed on mobile, Stories fallback)
          "400x150"  — ~2.67:1 wide banner (Audience Network)
          "600x360"  — ~1.67:1 horizontal (Right column, some placements)
          "90x160"   — 9:16 tall portrait (Stories)

Returns:
    JSON with the image_crops dict (ready for copy-paste into create_ad_creative),
    plus validation notes for any invalid keys requested.

Inputs: image_width (required), image_height (required), crop_keys. Returns: result

create_adA
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)

Note:
    Dynamic Creative creatives require the parent ad set to have `is_dynamic_creative=true`.
    Otherwise, ad creation will fail with error_subcode 1885998.

Inputs: name (required), adset_id (required), account_id (required), creative_id (required), +4 more. Returns: result

create_ad_creativeA
Create a new ad creative using an uploaded image hash, video ID, or an existing post.

Supports six creative modes:
- **Existing post**: Provide object_story_id (format: {page_id}_{post_id}) to promote an existing
  organic or published post. No image_hash or video_id required. Optionally combine with
  asset_customization_rules to attach a 9:16 video for Story/Reels placements.
- **Simple image/video**: Single image_hash or video_id with object_story_spec
- **Multi-variant copy**: Use plural text params (messages[], headlines[], descriptions[]) to test
  multiple text variants with a single image/video. No optimization_type or is_dynamic_creative needed.
- **Placement Asset Customization (dual-aspect, non-DC)**: Serve different aspect ratios per placement
  on a STANDARD ad set without is_dynamic_creative and without the one-ad-per-ad-set cap. Set
  optimization_type="PLACEMENT" and pass videos=[{video_id, label}, ...] (or images=[{image_hash,
  label}, ...]) together with asset_customization_rules whose customization_spec references those
  labels via video_label/image_label. Every label in the rules MUST appear on a videos[]/images[]
  entry, or Meta returns error_subcode=1487390 ("Adcreative Create Failed").
- **Dynamic Creative**: Multiple variants with dynamic_creative_spec (requires is_dynamic_creative on ad set)
- **FLEX/DOF (Advantage+)**: Set optimization_type="DEGREES_OF_FREEDOM" for Meta to auto-optimize
  across all asset combinations without requiring is_dynamic_creative on the ad set

Args:
    account_id: Meta Ads account ID (format: act_XXXXXXXXX)
    image_hash: Hash of a single uploaded image (cannot be used with image_hashes or video_id)
    access_token: Meta API access token (optional - will use cached token if not provided)
    name: Creative name
    page_id: Facebook Page ID (string or int; coerced to string)
    link_url: Destination URL for the ad. Required unless using lead_gen_form_id or
             reminder_data — with one exception: if asset_customization_rules is also
             set, link_url is required even for Lead ads. Meta accepts the creative
             without link_urls but rejects the ad at create_ad time with error 1885800
             ("Asset Customization Ads require a link"). The URL is never shown to the
             user when lead_gen_form_id is set (the CTA opens the form), but Meta still
             demands one be present on the creative. Pass any valid URL in that case
             (e.g. the Facebook page URL or your site root).
    message: Single ad copy/text (cannot be used with messages)
    messages: List of primary text variants for multi-variant copy testing (cannot be used with message).
              Each entry can be a plain string, OR a dict {"text": "...", "adlabels": [{"name": "..."}]}
              when used with asset_customization_rules that reference body_label.
    headline: Single headline for simple ads (cannot be used with headlines)
    headlines: List of headline variants for multi-variant copy testing (cannot be used with headline).
              Each entry can be a plain string, OR a dict {"text": "...", "adlabels": [{"name": "..."}]}
              when used with asset_customization_rules that reference title_label.
              Meta enforces the actual length limit; do not pre-truncate.
    description: Single description for simple ads (cannot be used with descriptions)
    descriptions: List of description variants for multi-variant copy testing (cannot be used with description).
              Each entry can be a plain string, OR a dict {"text": "...", "adlabels": [{"name": "..."}]}
              when used with asset_customization_rules that reference description_label.
    image_hashes: List of image hashes for FLEX creatives (up to 10, cannot be used with image_hash or video_id).
                 IMPORTANT: When optimization_type="DEGREES_OF_FREEDOM" (FLEX/Advantage+ mode),
                 only ONE image is served at delivery time regardless of how many hashes you provide.
                 The Meta API accepts multiple hashes without error and they all appear in
                 asset_feed_spec, but Meta silently collapses to a single image at serving time.
                 Use image_hashes with multiple entries only in non-DOF (regular dynamic creative)
                 mode. In DOF mode, pass a single hash.
    video_id: Meta video ID for video creatives (cannot be used with image_hash or image_hashes).
              Upload a video first via the Meta API, then use the returned video ID here.
              IMPORTANT: When also providing instagram_actor_id, both instagram_actor_id AND
              ad_formats=["SINGLE_VIDEO"] must be present — otherwise Meta returns error 1443048
              ("object_story_spec ill formed"). This is handled automatically: video creatives
              that include instagram_actor_id are routed through asset_feed_spec so that
              ad_formats=["SINGLE_VIDEO"] is always included in the API request.
    thumbnail_url: Thumbnail image URL for video creatives. Recommended when using video_id.
                  Meta will auto-generate a thumbnail if not provided — Pipeboard
                  will fetch the best available frame from the uploaded video.
                  IMPORTANT: when the video was just uploaded via
                  bulk_upload_ad_videos, Meta needs a few seconds to transcode
                  it. If create_ad_creative is called before transcoding
                  completes, the only thumbnail Meta returns is a generic
                  processing-state placeholder, which would be permanently
                  stored on the creative. In that case create_ad_creative
                  returns an error with video_status: "processing" — wait
                  a few seconds (poll with get_ad_video until video_status
                  is "ready") and retry, or pass thumbnail_url explicitly
                  (any public image URL works).
    optimization_type: Optional. Valid values:
                      - "DEGREES_OF_FREEDOM": FLEX (Advantage+) creatives where Meta auto-optimizes
                        across all asset combinations. At least one multi-variant asset field required.
                        NOTE: Meta ignores asset_customization_rules for DOF creatives.
                        NOTE: When using DEGREES_OF_FREEDOM with image_hashes, providing multiple
                        hashes is accepted by the API without error, but Meta silently serves only
                        ONE image at delivery time. A warning is included in the response if multiple
                        hashes are detected. To serve multiple images, omit optimization_type and
                        enable is_dynamic_creative on the ad set instead.
                      - "PLACEMENT": Placement Asset Customization. Use with videos[]/images[] (with
                        labels) and asset_customization_rules (with video_label/image_label references)
                        to serve different aspect ratios per placement (e.g., 1:1 Feed + 9:16 Reels).
                      Other values are passed through to Meta as-is.
    dynamic_creative_spec: Dynamic creative optimization settings
    call_to_action_type: Call to action button type. Meta enum — free-form values
                        (e.g. 'MAKE_RESERVATION', 'RESERVE', 'BOOK_TABLE') are rejected with
                        code 100. Pick from the documented list. Common values:
                          BOOK_NOW         — restaurants, salons, clinics, appointments (use this for
                                             reservations — there is no MAKE_RESERVATION enum)
                          LEARN_MORE, SHOP_NOW, SIGN_UP, SUBSCRIBE, GET_QUOTE, CONTACT_US,
                          DOWNLOAD, WATCH_MORE, GET_OFFER, APPLY_NOW, CALL_NOW, MESSAGE_PAGE,
                          SEE_MENU, ORDER_NOW, BUY_NOW, WHATSAPP_MESSAGE, GET_DIRECTIONS,
                          BUY_TICKETS, EVENT_RSVP, BOOK_TRAVEL.
                        When using CALL_NOW, also provide phone_number.
    lead_gen_form_id: Lead generation form ID for lead generation campaigns. Required when using
                     lead generation CTAs like 'SIGN_UP', 'GET_OFFER', 'SUBSCRIBE', etc.
    instagram_actor_id: Instagram account ID for Instagram placements (must be a string
                       to avoid JavaScript integer precision loss for IDs exceeding
                       Number.MAX_SAFE_INTEGER). Sent as instagram_user_id inside
                       object_story_spec (Meta deprecated instagram_actor_id in Jan 2026).
                       IMPORTANT for video creatives: Meta requires ad_formats=["SINGLE_VIDEO"]
                       in asset_feed_spec alongside instagram_user_id in object_story_spec —
                       omitting either causes error 1443048 ("object_story_spec ill formed").
                       This is auto-handled: video_id + instagram_actor_id always routes through
                       asset_feed_spec so ad_formats=["SINGLE_VIDEO"] is included automatically.
    ad_formats: List of ad format strings for asset_feed_spec (e.g., ["AUTOMATIC_FORMAT"] for
               Flexible ads, ["SINGLE_IMAGE"] for single image, ["SINGLE_VIDEO"] for video).
               When optimization_type is "DEGREES_OF_FREEDOM" with image_hashes, defaults to
               ["AUTOMATIC_FORMAT"] (Flexible format). For video creatives, defaults to
               ["SINGLE_VIDEO"]. Otherwise defaults to ["SINGLE_IMAGE"].
    asset_customization_rules: List of placement-specific asset overrides for asset_feed_spec.
    phone_number: Phone number for CALL_NOW call-to-action ads (click-to-call).
                 Required when call_to_action_type is CALL_NOW. Use E.164 format
                 (e.g., "+18005551234"). The number is sent to Meta as
                 call_to_action.value.link = "tel:<phone_number>" (Meta v24
                 rejects a literal "phone_number" key with code 100). Common
                 use case: geo-routed call ads with different phone numbers
                 per ad set.
    creative_features_spec: Advantage+ Creative feature opt-ins/opt-outs. Controls individual
               creative enhancements like image_touchups, text_optimizations, inline_comment,
               add_text_overlay, music, 3d_animation, etc. Each feature is a dict with
               "enroll_status" set to "OPT_IN" or "OPT_OUT".
               Example: {"image_touchups": {"enroll_status": "OPT_IN"},
                        "inline_comment": {"enroll_status": "OPT_IN"}}
               Sent to Meta as degrees_of_freedom_spec.creative_features_spec.
    url_tags: URL tracking parameters appended to the destination URL (e.g.,
             "utm_source=facebook&utm_medium=cpc&utm_campaign=spring_sale").
             Sets the url_tags field on the creative.
    caption: Display URL shown in the ad (e.g., "example.com/shoes"). Sets the
            caption field in link_data. If not provided, Meta auto-generates it
            from the destination URL. Only applies to image (link_data) creatives.
    image_crops: Crop coordinates for different aspect ratios. Applied in link_data for
                image creatives.

                Use the compute_image_crops tool first to get the correct coordinates
                for your specific image dimensions — it computes centered crop boxes
                for any source size automatically.

                Valid crop keys (only these 6 are accepted by Meta's API):
                  "100x100"  — 1:1 square (Feed, Marketplace, Search)
                  "100x72"   — ~1.39:1 horizontal (Marketplace, some placements)
                  "400x500"  — 4:5 portrait (Feed on mobile, Stories fallback)
                  "400x150"  — ~2.67:1 wide banner (Audience Network)
                  "600x360"  — ~1.67:1 horizontal (Right column, some placements)
                  "90x160"   — 9:16 tall portrait (Stories)

                Format: {"100x100": [[x1,y1],[x2,y2]], "400x500": [[x1,y1],[x2,y2]]}
                Coordinates are pixel-based (top-left and bottom-right corners).
                The bounding box aspect ratio must match the key ratio as closely as possible.
                Image origin (0,0) is the upper-left corner.

                Omit to let Meta auto-crop (default for horizontal is 1.91:1 recommended).
    object_story_id: ID of an existing organic or published Facebook/Instagram post to promote
                    as an ad. Format: "{page_id}_{post_id}" (e.g., "124965744226834_3888007311337206").
                    When provided, image_hash and video_id are not required. page_id is also not
                    required (it is encoded in the story ID). Combine with asset_customization_rules
                    to attach a 9:16 video for Story/Reels placements while the organic post
                    serves as the feed creative — a common "Use Existing Post" workflow.
                    Example: object_story_id="124965744226834_3888007311337206",
                             asset_customization_rules=[{"placement_groups": ["STORY"],
                               "customization_spec": {"video_ids": ["890310874031162"]}}]
    disable_all_enhancements: When True, opts out of all Advantage+ Creative enhancements by
                    setting every known creative_features_spec key (image_touchups,
                    text_optimizations, video_auto_crop, etc.) to OPT_OUT and also
                    disabling contextual_multi_ads. Use when you want full creative
                    control without Meta's auto-modifications.
    event_id: Facebook Event ID for EVENT_RESPONSES campaigns. Required for
             event RSVP/ticket ads so the event card renders properly. Placed
             inside link_data.event_id, and also inside call_to_action.value
             when call_to_action_type is EVENT_RSVP or BUY_TICKETS. Use with
             link_url set to the Facebook event URL
             (https://www.facebook.com/events/EVENT_ID).
    asset_customization_rules: Lets you assign different images or videos to specific placement groups
               (e.g., feed vs. stories). Only valid with image_hashes or plural asset params.
               Each rule uses a user-friendly format that is automatically translated to
               Meta's API format (adlabels + customization_spec positions):
                 - placement_groups: list of placement group names
                   Valid values: FEED, STORY, MESSENGER, INSTREAM_VIDEO, SEARCH, SHOP,
                   AUDIENCE_NETWORK
                 - customization_spec: dict specifying the asset to use for those placements
                   Supported keys: image_hashes (list), video_ids (list),
                   bodies, titles, descriptions (text overrides)
               All image hashes referenced in rules must also be in image_hashes.
               Example (feed gets one image, stories gets another):
               [
                 {"placement_groups": ["FEED"],
                  "customization_spec": {"image_hashes": ["<feed_hash>"]}},
                 {"placement_groups": ["STORY"],
                  "customization_spec": {"image_hashes": ["<story_hash>"]}}
               ]
    videos: List of video objects for placement asset customization (multiple videos with
               different aspect ratios). Each entry: {"video_id": "...", "thumbnail_url": "...",
               "label": "my_label"}. The "label" field is converted to adlabels for use with
               asset_customization_rules video_label references. Cannot be used with video_id.
               Use with optimization_type="PLACEMENT" and asset_customization_rules.
    images: List of image objects for placement asset customization (multiple images with
               different aspect ratios). Each entry: {"image_hash": "...", "label": "my_label"}.
               The "label" field is converted to adlabels for use with asset_customization_rules
               image_label references. Cannot be used with image_hash or image_hashes.
               Use with optimization_type="PLACEMENT" and asset_customization_rules.
    reminder_data: Inline reminder event data for Instagram Reminder Ads
                  (REMINDERS_SET optimization goal). Placed in
                  object_story_spec.link_data.reminder_data. Use this instead of
                  upcoming_events (which requires an existing ig_upcoming_event_id).
                  Required fields:
                    - event_name (str): Display title of the reminder event
                    - start_time (int): Event start as a Unix timestamp (seconds)
                    - end_time (int): Event end as a Unix timestamp (seconds)
                  Example:
                    {"event_name": "Summer Sale", "start_time": 1745596800, "end_time": 1745611200}
                  The ad set must use optimization_goal=REMINDERS_SET and the placement
                  must be restricted to Instagram feeds/stories. link_url is still
                  recommended (the URL users visit after the reminder fires).
    facebook_branded_content: Branded content settings for Facebook partnership ads.
                  Used when a brand sponsors a creator's content on Facebook.
                  Format: {"sponsor_page_id": "<page_id>"} where sponsor_page_id is the
                  Facebook Page ID of the sponsoring brand. Passed as a top-level field
                  on the ad creative. The creator's page should be set as page_id.
    instagram_branded_content: Branded content settings for Instagram partnership ads.
                  Used when a brand sponsors a creator's content on Instagram.
                  Format: {"sponsor_id": "<instagram_user_id>"} where sponsor_id is the
                  Instagram account ID of the sponsoring brand. Passed as a top-level
                  field on the ad creative.

Returns:
    JSON response with created creative details

Inputs: account_id (required), name, images, videos, +31 more. Returns: result

create_adsetA
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)

Inputs: name (required), account_id (required), campaign_id (required), billing_event (required), +22 more. Returns: result

create_budget_scheduleA
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.

Inputs: time_end (required), time_start (required), campaign_id (required), budget_value (required), +2 more. Returns: result

create_campaignA
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)

Inputs: name (required), objective (required), account_id (required), status, +11 more. Returns: result

estimate_audience_sizeA
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

Inputs: targeting, account_id, access_token, interest_list, +2 more. Returns: result

get_account_infoA
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.

Inputs: account_id (required), fields, access_token. Returns: result

get_account_pagesA
Get pages associated with a Meta Ads 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)

Returns:
    JSON response with pages associated with the account

Inputs: account_id (required), access_token. Returns: result

get_ad_accountsA
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)

Inputs: limit, user_id, access_token. Returns: result

get_ad_creativesA
Get creative details for a specific ad. Requires an ad_id (not account_id). Use get_ads first to find ad IDs.

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

Inputs: ad_id (required), access_token. Returns: result

get_ad_detailsA
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)

Inputs: ad_id (required), access_token. Returns: result

get_ad_imageA
Get, download, and visualize the image attached to an existing Meta ad.

Takes a Meta ad ID and returns the image the ad is currently serving.
If all you have is an image hash (no ad), use get_image_by_hash instead.

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

Returns:
    The ad image ready for direct visual analysis

Inputs: ad_id (required), access_token.

get_adsA
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

Inputs: account_id (required), limit, adset_id, campaign_id, +1 more. Returns: result

get_adset_detailsA
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"
    }

Inputs: adset_id (required), access_token. Returns: result

get_adsetsA
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

Inputs: account_id (required), limit, campaign_id, access_token. Returns: result

get_ad_videoA
Get video details and source URL for a Meta ad video creative. Returns the video source URL
(direct download link), thumbnail URL, processing status, and metadata (title, description,
duration).

Also useful for polling after bulk_upload_ad_videos: ``video_status`` is
``"processing"`` while Meta is still transcoding and ``"ready"`` when the
real video frames (and a usable thumbnail) are available. Calling
create_ad_creative before status is "ready" returns an error because the
only thumbnail Meta returns during processing is a generic placeholder
that would be permanently stored on the creative.

Provide either ad_id (to auto-extract the video from the ad creative) or video_id directly.
Providing account_id is strongly recommended — it enables the advideos edge which works
with Business Manager tokens (avoids error 100/33 and error #10 on account-uploaded videos).

Args:
    ad_id: Meta Ads ad ID (will extract video_id from the ad creative)
    video_id: Meta video ID (use this if you already have it from get_ad_creatives)
    account_id: Ad account ID (e.g. "act_123" or "123"). Enables advideos edge lookup.
    access_token: Meta API access token (optional - will use cached token if not provided)

Inputs: ad_id, video_id, account_id, access_token. Returns: result

get_campaign_detailsA
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)

Inputs: campaign_id (required), access_token. Returns: result

get_campaignsA
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

Inputs: account_id (required), after, limit, access_token, +2 more. Returns: result

get_creative_detailsA

Get detailed information about a specific ad creative by its ID.

Args:
    creative_id: Meta Ads creative ID (required)
    access_token: Meta API access token (optional)

Inputs: creative_id (required), access_token. Returns: result

get_image_by_hashA
Get, download, and visualize a Meta ad image by its hash.

Use this when you have an image_hash without an ad — e.g. the hash
returned by upload_ad_image / bulk_upload_ad_images, or one referenced
in a creative (object_story_spec.link_data.image_hash, asset_feed_spec
images[].hash, etc.). To view the image of an existing ad, prefer
get_ad_image(ad_id).

Args:
    account_id: Meta Ads account ID (act_XXXXXXXXX or bare numeric — both accepted)
    image_hash: Meta image hash
    access_token: Meta API access token (optional - will use cached token if not provided)

Returns:
    The image ready for direct visual analysis

Inputs: account_id (required), image_hash (required), access_token.

get_insightsA
Get performance insights for a campaign, ad set, ad or account.

Args:
    object_id: ID of the campaign, ad set, ad or account. You can also use the alias parameters below.
    account_id: Alias for object_id when querying account-level insights
    campaign_id: Alias for object_id when querying campaign-level insights
    adset_id: Alias for object_id when querying ad-set-level insights
    ad_id: Alias for object_id when querying ad-level insights
    access_token: Meta API access token (optional - will use cached token if not provided)
    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
               NOTE: platform_position is a Meta-restricted breakdown — Meta requires it to be paired
               with publisher_platform (otherwise "(#100) ... (action_type, platform_position) is invalid").
               When you pass platform_position, this tool auto-adds publisher_platform, and the
               action-typed fields (actions, action_values, conversions, cost_per_action_type) are
               returned per placement, so you get leads/CPL/conversions broken down by placement.
               Creative Assets: ad_format_asset, body_asset, call_to_action_asset, description_asset,
                              image_asset, link_url_asset, title_asset, video_asset, media_type,
                              creative_relaxation_asset_type, flexible_format_asset_type,
                              gen_ai_asset_type
               NOTE: Asset breakdowns (image_asset, video_asset, etc.) only return data for ads
               running with Dynamic Creative; for non-DCO ads, expect empty rows.
               NOTE: media_type collides with the default action_breakdowns=[action_type], so
               this tool auto-overrides action_breakdowns to [] when you pass media_type.
               Action-typed metrics (actions, action_values, conversions) are still returned
               but are no longer sliced by action_type alongside media_type.
               media_asset_url, media_creator, media_destination_url, media_format,
               media_origin_url, and media_text_content are NOT supported by Meta's Insights API
               (Meta returns "(#100) Tried accessing nonexisting field"). Use the asset breakdowns
               above instead.
               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)
    limit: Maximum number of results to return per page (default: 25, Meta API allows much higher values)
    after: Pagination cursor to get the next set of results. Use the 'after' cursor from previous response's paging.next field.
    action_attribution_windows: Optional list of attribution windows (e.g., ["1d_click", "7d_click", "1d_view"]).
               When specified, actions include additional fields for each window. The 'value' field always shows 7d_click.
    action_breakdowns: Optional list of action_breakdowns to apply to action-typed metrics. Pass [] to disable
               the default action_type slicing (required when combining action data with breakdowns that collide
               with action_type, e.g. media_type — auto-applied for media_type when not set).
               Meta supports values like action_type, action_target_id, action_destination, etc.
    compact: When True, strips redundant action-type duplicates from the response
             (omni_*, onsite_web_*, offsite_conversion.fb_pixel_*, etc.) to reduce
             payload size by ~60%. The canonical action types (purchase, add_to_cart,
             view_content, etc.) are always preserved. Default: False.

Note on response size: This tool always returns a fixed set of fields (impressions, clicks,
spend, cpc, cpm, ctr, reach, actions, action_values, etc.) and cannot filter to a subset.
For large result sets (50+ rows), the actions/action_values arrays can make responses very
large (1–2MB+). If you only need specific metrics like spend or impressions, consider using
bulk_get_insights with compact=true and the fields parameter:
    bulk_get_insights(level="ad", account_ids=[...], compact=true, fields=["spend", "impressions"])
bulk_get_insights supports level="ad", "adset", "campaign", and "account".

Inputs: ad_id, after, level, limit, +10 more. Returns: result

get_interest_suggestionsA
Get interest suggestions based on existing interests.

Args:
    interest_list: List of interest names to get suggestions for (e.g., ["Basketball", "Soccer"])
    access_token: Meta API access token (optional - will use cached token if not provided)
    limit: Maximum number of suggestions to return (default: 25)

Returns:
    JSON string containing suggested interests with id, name, audience_size, and description fields

Inputs: interest_list (required), limit, access_token. Returns: result

search_ads_archiveA
    Search the Facebook Ads Library archive.

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

Inputs: search_terms (required), ad_reached_countries (required), limit, fields, +2 more. Returns: result

search_behaviorsA
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

Inputs: limit, access_token. Returns: result

search_demographicsA
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

Inputs: limit, access_token, demographic_class. Returns: result

search_geo_locationsA
Search for geographic targeting locations.

Args:
    query: Search term for locations (e.g., "New York", "California", "Japan")
    access_token: Meta API access token (optional - will use cached token if not provided)
    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

Inputs: query (required), limit, access_token, location_types. Returns: result

search_interestsA
Search for interest targeting options by keyword.

Args:
    query: Search term for interests (e.g., "baseball", "cooking", "travel")
    access_token: Meta API access token (optional - will use cached token if not provided)
    limit: Maximum number of results to return (default: 25)

Returns:
    JSON string containing interest data with id, name, audience_size, and path fields

Inputs: query (required), limit, access_token. Returns: result

search_pages_by_nameA
Search for pages by name within an 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)
    search_term: Search term to find pages by name (optional - returns all pages if not provided)

Returns:
    JSON response with matching pages

Inputs: account_id (required), search_term, access_token. Returns: result

update_adA
Update an ad with new settings.

Args:
    ad_id: Meta Ads ad ID
    name: New ad name
    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)

Inputs: ad_id (required), name, status, bid_amount, +3 more. Returns: result

update_ad_creativeA
Update an existing ad creative's name or optimization settings.

IMPORTANT — Meta API limitation: The Meta API does NOT allow updating content
fields (message, headline, description, CTA, image, video, URL) on existing
creatives. Only the creative `name` and optimization settings (asset_feed_spec)
can be changed. To change ad content, create a new creative with the desired
content and update the ad to reference the new creative via `update_ad`.

Args:
    creative_id: Meta Ads creative ID to update
    access_token: Meta API access token (optional - will use cached token if not provided)
    name: New creative name (this is the most reliable update)
    message: New ad copy/text — NOTE: Meta API may reject this on existing creatives
    messages: List of primary text variants — NOTE: Meta API may reject this on existing creatives
    headline: Single headline — NOTE: Meta API may reject this on existing creatives
    headlines: New list of headlines — NOTE: Meta API may reject this on existing creatives
    description: Single description — NOTE: Meta API may reject this on existing creatives
    descriptions: New list of descriptions — NOTE: Meta API may reject this on existing creatives
    optimization_type: Set to "DEGREES_OF_FREEDOM" for FLEX (Advantage+) creatives
    dynamic_creative_spec: New dynamic creative optimization settings
    call_to_action_type: New call to action button type — NOTE: Meta API may reject this on existing creatives
    lead_gen_form_id: Lead generation form ID for lead generation campaigns
    ad_formats: List of ad format strings for asset_feed_spec (e.g., ["AUTOMATIC_FORMAT"] for
               Flexible ads, ["SINGLE_IMAGE"] for single image)
    creative_features_spec: Dict of Advantage+ Creative feature opt-ins/opt-outs.
               Each key is a feature name, value is {"enroll_status": "OPT_IN"|"OPT_OUT"}.
               Sent as a top-level field (not inside degrees_of_freedom_spec).

Returns:
    JSON response with updated creative details

Inputs: creative_id (required), name, message, headline, +11 more. Returns: result

update_adsetA
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)

Inputs: adset_id (required), name, status, end_time, +18 more. Returns: result

update_campaignA
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}]

Inputs: campaign_id (required), name, status, bid_cap, +10 more. Returns: result

upload_ad_imageA
Upload an image to use in Meta Ads creatives.

Args:
    account_id: Meta Ads account ID (format: act_XXXXXXXXX)
    access_token: Meta API access token (optional - will use cached token if not provided)
    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 object with:
      - image_hash: Pass this to create_ad_creative when building the ad,
        or to get_image_by_hash to view the image later.
      - images: List of {hash, url, width, height, name}. The url is a
        Meta CDN link you can fetch directly to view the image — no need
        to call any other tool right after upload.

Inputs: account_id (required), file, name, image_url, +1 more. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.8/5.0

    Scored across 35 tools

    Disambiguation4/5

    Most tools have clearly distinct resource+action targets across accounts, campaigns, ad sets, ads, creatives, insights, and targeting. Minor overlap exists between list/detail pairs like get_campaigns vs get_campaign_details and between search_interests vs get_interest_suggestions, but descriptions generally resolve the choice.

    Naming Consistency4/5

    All tools use snake_case with a predictable verb_noun structure such as get_campaigns, create_adset, update_ad, and search_geo_locations. There are small inconsistencies like get_creative_details vs get_ad_creatives, but the overall pattern is readable and consistent.

    Tool Count2/5

    At 35 tools, the surface is heavy for an MCP set and exceeds the typical well-scoped range. Several niche targeting utilities could be consolidated, and the high count makes the server harder to navigate despite the breadth of the Meta Ads domain.

    Completeness3/5

    The set covers core create/update workflows for campaigns, ad sets, ads, and creatives plus insights and targeting research. However, there are no delete/archive operations for major entities, no video upload tool despite video creative support, and descriptions reference bulk tools such as bulk_get_insights and bulk_upload_ad_videos that are not actually present.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to manage Facebook and Instagram advertising via the Meta Marketing API. It provides comprehensive tools for campaign lifecycle management, performance analytics, audience targeting, and creative optimization.
      202
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to manage Facebook and Instagram advertising data through the Meta Marketing API. It supports full campaign lifecycle management, performance analytics, audience targeting, and creative optimization.
      808 npm
      MIT
    • -
      license
      Not graded
      quality
      Not graded
      maintenance
      Enables AI assistants to manage Facebook and Instagram advertising campaigns through the Meta Marketing API. Supports full campaign lifecycle management, performance analytics, audience targeting, and creative optimization.
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables management and analysis of Meta (Facebook/Instagram) ads through natural language conversations, with 30 tools for reading and writing ad data.
      MIT