2.0.0

    io.github.brandu-mos/konquest-meta-ads-mcp

    Supervised Meta Ads operating system for Claude Code with 57 campaign management tools.

    Rank#300
    brandu-mosmcp-registryApi wrapperLast scanned Nov 19, 2026, 11:22 PMhttps://github.com/brandu-mos/konquest-meta-ads-mcp
    Created
    8 months ago
    Last commit
    7 months ago
    Latest release
    v2.0.08 months ago

    Security Findings

    Divergent payload behind an argument trigger

    SuspiciousScanner

    1 tool(s) return a materially different payload under an argument-gated branch: delete_campaign_structure (+ads, adsets, campaigns)

    Capability gated behind an argument trigger

    SuspiciousScanner

    1 tool(s) reach a destination/decode/exec only under an argument-gated branch: upload_ad_image (dest:https://.)

    Recently created account

    SuspiciousLineage

    Account was 16d old when repo was created

    Releaser has low repo tenure

    SuspiciousLineage

    Release author 'brandu-mos' has no commits in the repo older than 30d before the release

    Tools

    57 tools exposed by this MCP server

    57 clean

    bulk_rename_objects

    Rename multiple Meta Ads objects in one call. Args: renames_json: JSON array of rename specs: [{object_id: '...', new_name: '...', object_type: 'campaign|adset|ad'}, ...]

    Clean
    meta_ads_mcp/core/ops.py

    check_token_status

    Check Meta API token health, permissions, and rate limit status. Returns token validity, granted permissions, missing permissions, and current rate limit usage percentage.

    Clean
    meta_ads_mcp/core/accounts.py

    create_ad_creative

    Create a standalone single-image ad creative. Returns creative_id for use in ad creation (create_ad_from_manifest) or ad update (update_ad creative swap). Requires a Facebook Page ID. Instagram identity is auto-resolved from the page - if unavailable, creative is created for Facebook only. Single-image creatives only in v1. For video, carousel, or dynamic creatives, use create_multi_asset_ad. Args: account_id: Ad account ID (e.g., 'act_123456789'). page_id: Facebook Page ID for the creative. image_hash: Image hash from upload_ad_image. link_url: CTA destination URL. primary_text: Main ad copy text (the "message"). headline: Optional headline (appears below image). description: Optional description text. cta_type: Call-to-action type. Default 'LEARN_MORE'. Valid: LEARN_MORE, SHOP_NOW, SIGN_UP, SUBSCRIBE, CONTACT_US, GET_OFFER, BOOK_TRAVEL, DOWNLOAD, APPLY_NOW, WATCH_MORE, GET_QUOTE, SEND_MESSAGE, ORDER_NOW, NO_BUTTON. name: Optional creative name. Subject to naming enforcement.

    Clean
    meta_ads_mcp/core/creatives.py

    create_ad_from_manifest

    Create an ad from a manifest entry (always PAUSED, manifest-driven, no exceptions). Loads the manifest entry, detects creative mode, resolves identity, checks for duplicates, validates pre-write, creates the ad, and verifies post-write. INSTAGRAM GATE: Enforced via placement_mode parameter. - full_meta (default): requires IG identity, BLOCKS if unavailable - facebook_only: explicit FB-only, no IG placements - instagram_only: requires IG identity, BLOCKS if unavailable For video ads: provide meta_video_id from upload_video_asset + poll_video_processing. The video must be in 'ready' state before calling this tool. Args: account_id: Ad account ID (e.g., 'act_123456789'). adset_id: Target ad set ID. logical_creative_id: ID of the creative entry in the manifest (e.g., 'lc_example_brand_001'). manifest_json: JSON string containing the manifest or a single creative entry. Must include the logical_creative_id entry with variants, CTA, etc. ad_name: Name for the ad. Greek text validated. page_id: Facebook Page ID for the ad identity. destination_url: Primary destination URL for the ad CTA. primary_text: Primary text / message body. Required for manual mode, optional for auto/hybrid. cta_type: Call to action type (default 'SHOP_NOW'). See VALID_CTA_TYPES. headline: Optional headline text. Auto-generated if copy_mode='auto' and not provided. description: Optional description text. Auto-generated if copy_mode='auto' and not provided. instagram_user_id: Optional IG user ID. If not provided, attempts resolution from account. destination_url_override: If set, overrides manifest URL. Logged explicitly. cta_override: If set, overrides manifest CTA. Logged explicitly. primary_text_override: If set, overrides manifest primary text. Logged explicitly. headline_override: If set, overrides manifest headline. Logged explicitly. copy_mode: 'manual' (default), 'auto' (generate from vault), 'hybrid' (fill gaps). angle_name: Marketing angle for auto/hybrid copy generation. icp_name: Target ICP for auto/hybrid copy generation. funnel_stage: 'tofu', 'mofu', 'bofu' for copy tone/structure. dry_run: If true, runs all validation but does not create the ad. Returns what would be created.

    Clean
    meta_ads_mcp/core/ads.py

    create_adset

    Create a new ad set (always PAUSED, no exceptions). Runs Advantage+ audience enforcement, parent campaign inspection, ABO/CBO enforcement, ICP signal mapping, narrowing detection, pre-write validation, creates the ad set, and verifies post-write. Args: account_id: Ad account ID (e.g., 'act_123456789'). campaign_id: Parent campaign ID. Must be PAUSED or ACTIVE. name: Ad set name. Greek text validated. optimization_goal: e.g. 'OFFSITE_CONVERSIONS', 'LINK_CLICKS', 'LEAD_GENERATION', 'REACH'. Must be compatible with parent campaign objective. billing_event: Usually 'IMPRESSIONS'. Also: 'LINK_CLICKS', 'THRUPLAY'. daily_budget: Daily budget in EUR (e.g., 15.00). Required for ABO campaigns. Omit for CBO. lifetime_budget: Lifetime budget in EUR. Alternative to daily_budget. Requires end_time. targeting_json: JSON string of targeting spec. Advantage+ mode uses signals as suggestions. Example: '{"geo_locations":{"countries":["GR"]},"age_min":25,"age_max":55}' promoted_object_json: JSON string of promoted object. Required for OUTCOME_SALES/LEADS. Example: '{"pixel_id":"123456789012345","custom_event_type":"PURCHASE"}' start_time: ISO 8601 start time. Optional (defaults to immediately when activated). end_time: ISO 8601 end time. Required if using lifetime_budget. audience_mode: 'advantage_plus' (default, recommended), 'manual', 'broad', 'existing_audience', 'restricted' (disables Advantage+). icp_name: ICP name from concept selection for signal derivation. icp_signals_json: Pre-built ICP signals JSON with interests/behaviors/demographics. experiment_type: If 'strict_audience_test', allows Advantage+ OFF. explicit_tracking_mode: Operator-declared tracking mode override. 'instant_form', 'messaging', 'page_engagement' allow writes without pixel. If not set, system infers intended flow and enforces pixel for website paths.

    Clean
    meta_ads_mcp/core/adsets.py

    create_campaign

    Create a new campaign (always PAUSED, no exceptions). Runs naming enforcement, pre-write validation, creates the campaign, verifies post-write, and logs the mutation. Args: account_id: Ad account ID (e.g., 'act_123456789'). name: Campaign name following convention: Objective | Product | Funnel | BudgetModel. If not following convention, provide product/funnel/budget_model for auto-correction. objective: Must be an outcome-based objective: OUTCOME_AWARENESS, OUTCOME_ENGAGEMENT, OUTCOME_LEADS, OUTCOME_SALES, OUTCOME_TRAFFIC, OUTCOME_APP_PROMOTION. special_ad_categories: Comma-separated special categories if applicable. product: Product/offer name for naming convention (e.g., 'Consulting', 'VitC'). funnel: Funnel stage for naming: TOFU, MOFU, BOFU, RT. budget_model: ABO or CBO for naming convention.

    Clean
    meta_ads_mcp/core/campaigns.py

    create_multi_asset_ad

    Create an ad with enforced identity, multi-asset support, and verification. Supports two asset modes (not mixed): - VIDEO: If 9:16 and/or 1:1 videos provided, creates ONE ad with asset_feed_spec and placement mapping. Single video = simple mode. - STATIC IMAGE: If 2+ of image_1x1_hash/image_4x5_hash/image_9x16_hash provided, creates ONE ad with asset_feed_spec and placement mapping. Single image hash not accepted here - use create_ad_creative instead. Mixed video + image is blocked. Provide one type only. INSTAGRAM GATE: Enforced via placement_mode. - full_meta (default): requires IG identity, BLOCKS if unavailable - facebook_only: explicit FB-only, no IG placements - instagram_only: requires IG identity, BLOCKS if unavailable Args: account_id: Ad account ID. adset_id: Target ad set ID. page_id: Facebook Page ID. ad_name: Ad name. primary_text: Main ad copy. Required for manual, auto-generated for auto/hybrid. headline: Headline text. Auto-generated for auto/hybrid if empty. destination_url: CTA destination URL. cta_type: CTA type (default LEARN_MORE). video_9x16_id: Vertical video ID (for Stories/Reels). video_1x1_id: Square video ID (for Feed). description: Optional description. copy_mode: 'manual' (default), 'auto' (generate from vault), 'hybrid'. angle_name: Marketing angle for auto/hybrid copy generation. icp_name: Target ICP for auto/hybrid copy generation. funnel_stage: 'tofu', 'mofu', 'bofu' for copy structure.

    Clean
    meta_ads_mcp/core/ad_builder.py

    create_product_set

    Create a product set with filter rules for DPA targeting. Args: catalog_id: Product catalog ID. name: Product set name. filter_json: JSON string of filter rules. Example: '{"product_type":{"i_contains":"shoes"}}'

    Clean
    meta_ads_mcp/core/catalogs.py

    delete_campaign_structure

    Delete entire campaign structure (ads -> adsets -> campaigns) in correct order. Args: account_id: Ad account ID. campaign_ids_json: JSON array of campaign IDs to delete. If not provided with delete_all_active=True, deletes all non-deleted campaigns. delete_all_active: If True and no campaign_ids, targets all campaigns. confirm: Must be True to actually delete. False = dry run showing what would be deleted.

    Clean
    meta_ads_mcp/core/ops.py

    diagnose_pixel_on_site

    Diagnose pixel installation on a website via headless browser check. Checks: pixel script presence, consent/cookie blocking, Lead event setup, Complianz/cookie banner status. Requires browser MCP (Puppeteer) to be available. Args: url: Website URL to check. pixel_id: Optional specific pixel ID to look for.

    Clean
    meta_ads_mcp/core/ops.py

    discover_all_accounts

    Discover all ad accounts, their pages, pixels, and Instagram accounts. Used to generate or update the account registry (config/accounts.yaml). Returns a comprehensive mapping of all accessible assets.

    Clean
    meta_ads_mcp/core/accounts.py

    duplicate_adset

    Duplicate a single ad set into a target campaign within the same account. All created objects are PAUSED. Does not duplicate child ads. Same-account only. Args: adset_id: Source ad set ID to duplicate. target_campaign_id: Campaign to place the duplicated ad set in. account_id: Ad account ID (must match source). name_suffix: Appended to source name (default " - Copy"). budget_override: Override budget in EUR. If None, copies source budget.

    Clean
    meta_ads_mcp/core/duplication.py

    duplicate_campaign

    Duplicate a campaign (and optionally its child ad sets and ads) within the same account. All created objects are PAUSED. When include_ads=True, ads are duplicated with their existing creative references (creatives are reused, not copied). Same-account only. Cross-account duplication is not supported. Args: campaign_id: Source campaign ID to duplicate. account_id: Ad account ID. Must match the source campaign's account. name_suffix: Appended to source names (default " - Copy"). Must result in valid names per naming convention. include_adsets: Whether to duplicate child ad sets (default True). adset_budget_override: Override all duplicated ad set budgets (EUR). Only applies to ABO campaigns. If None, copies source budgets.

    Clean
    meta_ads_mcp/core/duplication.py

    estimate_audience_size

    Estimate audience reach for a targeting specification. Returns estimated daily reach (lower/upper bounds) for the given targeting spec on the specified account. Args: account_id: Ad account ID (e.g., 'act_123456789'). targeting_json: JSON string of targeting spec. Example: '{"geo_locations":{"countries":["GR"]},"age_min":25,"age_max":55}'

    Clean
    meta_ads_mcp/core/targeting.py

    generate_names

    Generate correctly named Meta Ads object following naming convention. Convention (learned from ExampleBrand): - Campaign: Objective | Product | Funnel | BudgetModel - Ad Set: AudienceType | AgeRange | Geo | ExclusionFlag - Ad: Hook | Format | Version Args: object_type: 'campaign', 'adset', or 'ad'. objective: For campaigns: Sales, Traffic, Leads, Awareness, Engagement. product: For campaigns: product/offer name (client-specific). funnel: For campaigns: TOFU, MOFU, BOFU, RT. budget_model: For campaigns: ABO, CBO. audience_type: For ad sets: Broad, Broad-Interest, RT-WV-30d, etc. age_range: For ad sets: 24-55, 18-45, All. geo: Country code (default GR). exclusion_flag: For ad sets: Adv, ExPurch, None. hook: For ads: concept name in kebab-case (e.g., Employee-Blame). format_code: For ads: REEL, VID, IMG, REEL+FEED. version: For ads: V1, V2, V3.

    Clean
    meta_ads_mcp/core/naming.py

    get_account_info

    Get detailed information about a specific ad account. Returns account configuration, status, spend data, pixel info, and connected assets. Args: account_id: Ad account ID (e.g., 'act_123456789').

    Clean
    meta_ads_mcp/core/accounts.py

    get_account_pages

    List Facebook Pages available for ads on a specific ad account. Args: account_id: Ad account ID (e.g., 'act_123456789').

    Clean
    meta_ads_mcp/core/accounts.py

    get_ad_accounts

    List all ad accounts accessible to the authenticated user. Returns account IDs, names, statuses, currencies, and timezones for all accounts in your business portfolio. Args: limit: Maximum number of accounts to return (default 50).

    Clean
    meta_ads_mcp/core/accounts.py

    get_ad_creatives

    List ad creatives for an account or specific ad, with image hash resolution. Args: account_id: Ad account ID (e.g., 'act_123456789'). Used for image hash resolution. ad_id: Optional ad ID. If provided, returns the creative for that specific ad. limit: Max results when listing account creatives (default 50).

    Clean
    meta_ads_mcp/core/creatives.py

    get_ad_details

    Get detailed ad information including creative reference, tracking specs, conversion specs, issues, and recommendations. Args: ad_id: Ad ID (numeric string).

    Clean
    meta_ads_mcp/core/ads.py

    get_ad_image

    Retrieve metadata and URL for an uploaded ad image by hash. Returns the image URL, dimensions, name, and other metadata. Args: account_id: Ad account ID (e.g., 'act_123456789'). image_hash: Image hash from upload_ad_image.

    Clean
    meta_ads_mcp/core/images.py

    get_ads

    List ads for an account, campaign, or ad set. Args: account_id: Ad account ID (e.g., 'act_123456789'). campaign_id: Optional - filter ads by campaign. adset_id: Optional - filter ads by ad set (takes precedence over campaign_id). status_filter: Filter by effective_status: 'ACTIVE', 'PAUSED', 'ARCHIVED', or 'ALL'. limit: Maximum results per page (default 50).

    Clean
    meta_ads_mcp/core/ads.py

    get_adset_details

    Get detailed ad set information including targeting, optimization, learning stage, frequency caps, and attribution settings. Args: adset_id: Ad set ID (numeric string).

    Clean
    meta_ads_mcp/core/adsets.py

    get_adsets

    List ad sets for an account or filtered by campaign. Args: account_id: Ad account ID (e.g., 'act_123456789'). campaign_id: Optional campaign ID to filter ad sets for that campaign only. status_filter: Filter by effective_status: 'ACTIVE', 'PAUSED', 'ARCHIVED', or 'ALL'. limit: Maximum results per page (default 50).

    Clean
    meta_ads_mcp/core/adsets.py

    get_bulk_insights

    Get performance insights across all accessible ad accounts in one call. Aggregates spend, impressions, clicks, conversions, ROAS across accounts. Uses accounts from the Meta API (not accounts.yaml). Args: time_range: 'today', 'yesterday', 'last_3d', 'last_7d', 'last_14d', 'last_30d'. level: 'account' (one row per account). Campaign-level bulk is not supported. limit_accounts: Max accounts to query (default 20).

    Clean
    meta_ads_mcp/core/insights.py

    get_campaign_details

    Get detailed information about a specific campaign including budget, objective, bid strategy, special categories, and issues. Args: campaign_id: Campaign ID (numeric string).

    Clean
    meta_ads_mcp/core/campaigns.py

    get_campaigns

    List campaigns for an ad account with status and budget info. Args: account_id: Ad account ID (e.g., 'act_123456789'). status_filter: Filter by effective_status: 'ACTIVE', 'PAUSED', 'ARCHIVED', or 'ALL'. If not set, returns all campaigns. limit: Maximum results per page (default 50, max 100).

    Clean
    meta_ads_mcp/core/campaigns.py

    get_catalog_info

    Get catalog details including product count, vertical, name, and connected event sources (pixels). Args: catalog_id: Product catalog ID (numeric string).

    Clean
    meta_ads_mcp/core/catalogs.py

    get_catalog_products

    List products in a catalog with price, availability, review status, and URLs. Args: catalog_id: Product catalog ID. limit: Max products to return (default 25, max 100). filter_availability: Optional filter: 'in stock', 'out of stock', 'discontinued'.

    Clean
    meta_ads_mcp/core/catalogs.py

    get_creative_details

    Get full creative details including mode classification, media URLs, object_story_spec, asset_feed_spec, and degrees_of_freedom_spec. Args: creative_id: Creative ID (numeric string). account_id: Optional account ID for image hash resolution. If not provided, image hashes will not be resolved to URLs.

    Clean
    meta_ads_mcp/core/creatives.py

    get_event_stats

    Get event statistics with archetype-aware diagnostic analysis. Checks event coverage, parameter completeness, diagnostic flags, and classifies overall tracking health. Args: pixel_id: Pixel ID (numeric string). archetype: Account archetype for requirement matching: 'ecommerce', 'lead_gen', 'awareness', 'traffic', 'hybrid', 'messages'.

    Clean
    meta_ads_mcp/core/pixels.py

    get_insights

    Get performance insights for any Meta Ads object (account, campaign, ad set, or ad). Returns normalized metrics with objective-aware extraction: purchases/ROAS for ecommerce, leads/CPL for lead_gen, reach/frequency for awareness. Args: object_id: Account ID (act_XXX), campaign ID, ad set ID, or ad ID. time_range: Date preset ('last_7d', 'last_30d', 'this_month', etc.) or explicit range 'YYYY-MM-DD,YYYY-MM-DD'. breakdowns: Comma-separated breakdown dimensions (e.g. 'age,gender'). Supported: age, gender, country, region, impression_device, platform_position, publisher_platform, device_platform, product_id. level: Aggregation level when querying account/campaign: 'campaign', 'adset', 'ad'. Omit for object-level insights. archetype: Account archetype for metric selection: 'ecommerce', 'lead_gen', 'awareness', 'traffic', 'hybrid', 'messages'. Default 'hybrid' (all metrics). compact: If true, return a compact operator-friendly summary alongside raw data. limit: Max rows for breakdown or level queries (default 50).

    Clean
    meta_ads_mcp/core/insights.py

    get_instagram_identities

    List Instagram accounts available for ads on a specific ad account. Returns instagram_user_id (the canonical identifier) for each account. This is the first step in the Instagram identity resolution ladder. Args: account_id: Ad account ID (e.g., 'act_123456789').

    Clean
    meta_ads_mcp/core/accounts.py

    get_interest_suggestions

    Get related interest suggestions from seed interests. Accepts a comma-separated list of interest IDs or names and returns Meta's suggested related interests for targeting expansion. Args: interest_list: Comma-separated interest IDs (numeric) or interest names. Example IDs: '6003139266461,6003017845981' Example names: 'yoga,meditation' limit: Max suggestions to return (default 20).

    Clean
    meta_ads_mcp/core/targeting.py

    get_pixel_events

    Get events received by a pixel in the last 24 hours, broken down by event type and hourly counts. Args: pixel_id: Pixel ID (numeric string).

    Clean
    meta_ads_mcp/core/pixels.py

    get_pixel_info

    Get pixel status, connections, last fired time, and availability. Args: pixel_id: Pixel ID (numeric string).

    Clean
    meta_ads_mcp/core/pixels.py

    get_product_sets

    List product sets in a catalog with product counts and filter rules. Args: catalog_id: Product catalog ID.

    Clean
    meta_ads_mcp/core/catalogs.py

    list_custom_audiences

    List custom audiences for an ad account with type classification, size estimates, delivery status, and diagnostic warnings. Flags audiences that are unusable, too small, too broad, stale, or errored. Args: account_id: Ad account ID (e.g., 'act_123456789'). limit: Max audiences to return (default 50).

    Clean
    meta_ads_mcp/core/audiences.py

    poll_video_processing

    Poll video processing status until ready, failed, or max attempts reached. Args: video_id: Meta video ID from upload_video_asset. max_attempts: Maximum poll attempts (default 30 = 5 minutes at 10s interval). poll_interval_seconds: Seconds between polls (default 10).

    Clean
    meta_ads_mcp/core/video.py

    read_client_vault

    Read all client intelligence from the Obsidian vault for ad operations. Auto-resolves: brand voice, ICPs, angles, objections, profile IDs. If critical files are missing, returns explicit blockers. Args: account_id: Ad account ID. Resolved to client slug via registry. include_context: If True, also reads campaign history, assets, constraints.

    Clean
    meta_ads_mcp/core/vault_reader.py

    resolve_page_identity

    Resolve full identity for a Facebook Page: page details + Instagram business account. Uses the 3-step IG resolution ladder (registry -> promote_pages -> ad account). Falls back to direct page query if account_id not provided. Args: page_id: Facebook Page ID. account_id: Optional ad account ID for improved IG resolution.

    Clean
    meta_ads_mcp/core/ops.py

    run_setup_check

    Check MCP setup readiness and return structured results. Validates token, permissions, account access, pages, Instagram identity, pixels, and local configuration. Returns pass/warn/fail for each check with exact fix instructions for failures. Read-only. Does not modify any configuration or Meta settings.

    Clean
    meta_ads_mcp/core/setup.py

    run_tracking_diagnostic

    Run comprehensive tracking diagnostic for an ad account. Checks all connected pixels, event coverage, parameter completeness, and Meta diagnostic flags. Returns archetype-aware health classification with severity-ranked issues and fix suggestions. Args: account_id: Ad account ID (e.g., 'act_123456789'). archetype: Account archetype for requirement matching.

    Clean
    meta_ads_mcp/core/pixels.py

    search_behaviors

    Search or list behavior-based targeting options. If query is provided, filters by keyword. Otherwise returns all behaviors. Args: query: Optional search term (e.g., 'travel', 'small business'). limit: Max results (default 30).

    Clean
    meta_ads_mcp/core/targeting.py

    search_demographics

    Search or list demographic targeting options. Returns demographic categories: life events, education, work, financial, relationship, home ownership, parental status, etc. If query is provided, filters by keyword. Otherwise returns all demographics. Args: query: Optional search term (e.g., 'homeowner', 'new job', 'university'). limit: Max results (default 30).

    Clean
    meta_ads_mcp/core/targeting.py

    search_geo_locations

    Search geographic locations for ad targeting. Args: query: Location search term (e.g., 'Greece', 'Athens', 'Crete'). location_type: Type of location: 'country', 'region', 'city', 'zip', 'geo_market', 'electoral_district'. Default 'country'. limit: Max results (default 10).

    Clean
    meta_ads_mcp/core/targeting.py

    search_interests

    Search for interest-based targeting options. Returns matching interests with audience size estimates, topic category, and path. Args: query: Search term (e.g., 'yoga', 'hospitality', 'skincare'). limit: Max results (default 20).

    Clean
    meta_ads_mcp/core/targeting.py

    send_test_event

    Send a test event via the Conversions API Test Events endpoint. Args: pixel_id: Pixel ID (numeric string). event_name: Event name to send (default 'PageView'). test_event_code: Test event code from Events Manager. If not provided, generates a temporary one. custom_data: Optional JSON string of custom_data params (e.g., '{"value": 10.00, "currency": "EUR"}').

    Clean
    meta_ads_mcp/core/pixels.py

    update_ad

    Update an existing ad. Supervised write - validates before applying. Takes a pre-write snapshot for rollback, validates the update payload, applies via Meta API, and verifies post-write state. Note on creative_id: Swaps the creative attached to this ad. The new creative must already exist (created via create_multi_asset_ad or the Meta UI). This does NOT create a new creative - it re-points the ad to an existing one. Args: ad_id: Ad ID to update. name: New ad name. Subject to naming enforcement. status: New status. Allowed: 'PAUSED', 'ACTIVE', 'ARCHIVED'. Activating requires confirmation-level validation. creative_id: ID of an existing creative to attach to this ad. Format: numeric string (e.g., '120239290442460377').

    Clean
    meta_ads_mcp/core/ads.py

    update_ad_creative

    Update an existing ad creative's name. IMPORTANT: Meta API does NOT allow changing copy, headline, CTA, or link URL on existing creatives. Creative content is immutable after creation. To change ad copy: create a NEW creative with create_ad_creative, then swap it on the ad with update_ad(creative_id=new_creative_id). Args: creative_id: Creative ID to update. name: New creative name.

    Clean
    meta_ads_mcp/core/creatives.py

    update_adset

    Update an existing ad set. Supervised write - validates before applying. Takes a pre-write snapshot for rollback, validates the update payload, applies via Meta API, and verifies post-write state. Note on budgets: ABO/CBO rules are enforced. If the parent campaign uses CBO (has campaign-level budget), ad set budget updates are blocked. Budget updates are only allowed for ABO ad sets (parent campaign has no budget). Note on targeting: targeting_json must be a valid Meta targeting spec JSON object. Partial updates are supported - Meta merges provided fields with existing targeting. To clear a field, set it explicitly to null in the JSON. Args: adset_id: Ad set ID to update. name: New ad set name. Subject to naming enforcement. status: New status. Allowed: 'PAUSED', 'ACTIVE', 'ARCHIVED'. Activating requires confirmation-level validation. daily_budget: New daily budget in currency units (e.g., 15.0 for EUR 15). Only allowed for ABO ad sets. Mutually exclusive with lifetime_budget. lifetime_budget: New lifetime budget in currency units. Only allowed for ABO ad sets. Mutually exclusive with daily_budget. targeting_json: JSON string of targeting spec to apply. Example: '{"geo_locations":{"countries":["GR"]},"age_min":25,"age_max":55}' start_time: New start time (ISO 8601 format). end_time: New end time (ISO 8601 format).

    Clean
    meta_ads_mcp/core/adsets.py

    update_campaign

    Update an existing campaign. Supervised write - validates before applying. Takes a pre-write snapshot for rollback, validates the update payload, applies via Meta API, and verifies post-write state. Args: campaign_id: Campaign ID to update. name: New campaign name. Subject to naming enforcement. daily_budget: New daily budget in currency units (e.g., 50.0 for EUR 50). Mutually exclusive with lifetime_budget. lifetime_budget: New lifetime budget in currency units. Mutually exclusive with daily_budget. status: New status. Allowed: 'PAUSED', 'ACTIVE', 'ARCHIVED'. Activating requires confirmation-level validation. start_time: New start time (ISO 8601 format). end_time: New end time / stop_time (ISO 8601 format). special_ad_categories: Comma-separated categories or empty string to clear.

    Clean
    meta_ads_mcp/core/campaigns.py

    update_product_set

    Update a product set name or filter rules. Args: product_set_id: Product set ID to update. name: New name. filter_json: New filter rules as JSON string.

    Clean
    meta_ads_mcp/core/catalogs.py

    upload_ad_image

    Upload an image from URL into Meta ad images library. Downloads the image from the provided URL, then uploads it to Meta via multipart form upload. Returns the image hash needed for creative creation (create_ad_creative, create_multi_asset_ad) and ad building. Supported formats: JPG, PNG. Max size: 30MB. Args: account_id: Ad account ID (e.g., 'act_123456789'). image_url: Public URL of the image to upload. name: Optional name for the image in the library. Defaults to filename from URL.

    Clean
    meta_ads_mcp/core/images.py

    upload_video_asset

    Upload a local video file to a Meta ad account. Validates the file, uploads via simple upload (for files < 1GB), and returns the meta_video_id for use in ad creation. The video enters processing after upload - use poll_video_processing to check when it's ready. Args: account_id: Ad account ID (e.g., 'act_123456789'). video_path: Local filesystem path to the video file (.mp4 or .mov). title: Optional title for the video in Meta. description: Optional description.

    Clean
    meta_ads_mcp/core/video.py

    upload_video_resumable

    Upload a video file using resumable upload (supports files >100MB up to 4GB). Use this for large files that fail with upload_video_asset. Automatically chunks the file and uploads sequentially. Args: account_id: Ad account ID. video_path: Local path to .mp4 or .mov file. title: Optional title (defaults to filename). chunk_size_mb: Chunk size in MB (default 20).

    Clean
    meta_ads_mcp/core/ops.py

    validate_catalog_connections

    Validate the catalog-pixel-account-page connection chain and run diagnostic health assessment. For DPA (Dynamic Product Ads) to work, the full chain must be connected: Catalog -> Pixel -> Ad Account -> Page Args: catalog_id: Product catalog ID. account_id: Optional ad account ID to verify connection. pixel_id: Optional pixel ID to verify catalog-pixel link. page_id: Optional page ID to verify catalog-page link.

    Clean
    meta_ads_mcp/core/catalogs.py

    Versions

    1
    • 2.0.0
      Scanned Nov 19, 2026, 11:22 PMHigh