Check Meta API token health, permissions, and rate limit status.

Returns token validity, granted permissions, missing permissions, and current rate limit usage percentage.

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

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').

List Facebook Pages available for ads on a specific ad account.

Args: account_id: Ad account ID (e.g., 'act_123456789').

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').

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.

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

Get detailed information about a specific campaign including budget, objective, bid strategy, special categories, and issues.

Args: campaign_id: Campaign ID (numeric string).

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.

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.

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

Get detailed ad set information including targeting, optimization, learning stage, frequency caps, and attribution settings.

Args: adset_id: Ad set ID (numeric string).

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.

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

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

Get detailed ad information including creative reference, tracking specs, conversion specs, issues, and recommendations.

Args: ad_id: Ad ID (numeric string).

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.

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').

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

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.

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.

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.

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

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

Get pixel status, connections, last fired time, and availability.

Args: pixel_id: Pixel ID (numeric string).

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

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

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"}').

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.

Get catalog details including product count, vertical, name, and connected event sources (pixels).

Args: catalog_id: Product catalog ID (numeric string).

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

List product sets in a catalog with product counts and filter rules.

Args: catalog_id: Product catalog ID.

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.

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

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.

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

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

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

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

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

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

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}'

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.

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.

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.

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

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.

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.

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

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'}, ...]

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.

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.

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.

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.

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.

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.

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.