konquest-meta-ads-mcp
Provides a comprehensive toolset for managing Meta Ads via the Marketing API, including full CRUD operations for campaigns, ad sets, and ads, multi-asset creative management, performance insights, pixel diagnostics, and catalog support.
KonQuest Meta Ads MCP
Supervised Meta Ads Operating System for Claude Code. You can find the premium version here: https://farasokster.gumroad.com/l/konquest-meta-ads-mcp-premium
Open-Core Model
KonQuest Meta Ads MCP uses an open-core model:
Public (this repo) - 57 tools, MIT license:
Full CRUD for campaigns, ad sets, and ads
Multi-asset ad creation (video + static image, multi-dimension)
Image upload and retrieval
Campaign and ad set duplication
Insights and bulk cross-account analytics
Pixel and tracking diagnostics (5 tools)
Catalog and DPA support (6 tools, including product set create/update)
Full targeting toolkit (6 tools)
Setup readiness checker (42+ checks with fix instructions)
Validation pipeline, naming enforcement, post-write verification
Safety tiers, rate limiting, rollback references
215 automated tests
Premium bundle - adds 41 tools:
Advisory optimization engine (review queues, learning, experiments, budget governor, creative rotation)
Vault intelligence and copy generation (brand voice, ICP targeting, concept selection)
Greek language QA (Greeklish detection, orthography checks)
Automation suite (diagnostics, bulk operations, account audit)
Vault bootstrap (15 template files per client)
Premium tests and evaluations
Premium bundle available separately. Public tools work fully without it.
Related MCP server: meta-ads-manager-mcp
What Makes This Different
Production-tested across 37+ client campaigns with real budgets and real edge cases
Not a wrapper - includes optimization engine, safety gates, validators, and rollback
Vault-integrated - reads client intelligence (ICPs, brand voice, angles) to generate better ads
Greek language QA built in (adaptable to any language validation)
All ads created PAUSED - nothing goes live without explicit operator approval
Supervised, not autonomous - operator confirms every write, every activation, every budget change
Tool Classification
Classification | Count | Description |
production-safe | 38 | Read-only data access. No API writes, no local state changes. |
supervised-only | 29 | Write/delete operations requiring operator approval before execution. |
advisory-only | 31 | Generate recommendations, plans, copy, diagnostics. No Meta API writes. May write local files. |
Total: 98 registered |
Architecture
meta_ads_mcp/
core/ # 66 tools - API read/write operations
engine/ # 32 tools - optimization, review, learning, experiments
validators/ # Quality gates (compliance, creative specs, tracking, structure)
safety/ # Rate limiting, rollback, duplicate checking, file locks, tier access
ingestion/ # Internal: video manifest management
reporting/ # Internal: not currently active (see Non-Shipped Code)Tool Categories
Category | Tools | Description |
Account Management | 6 | Token health, ad accounts, pages, IG identity, discovery |
Campaigns | 4 | Create, read, update campaigns |
Ad Sets | 4 | Create, read, update ad sets with targeting |
Ads | 4 | Create, read, update ads |
Creatives | 3 | Create, read ad creatives |
Insights & Analytics | 1 | Performance data with archetype-aware normalization |
Pixels & Tracking | 5 | Pixel health, event diagnostics, test events, CAPI |
Catalogs & DPA | 6 | Product catalogs, feeds, product sets, validation |
Audiences | 1 | Custom audience listing |
Targeting | 3 | Interest, behavior, and geo search |
Video Management | 3 | Upload (simple + resumable) and processing status |
Ad Builder | 1 | Multi-asset ad creation with IG gate enforcement |
Copy Engine | 2 | Vault-driven ad copy generation and validation |
Naming Convention | 1 | Enforced naming schema for all objects |
Automation & Diagnostics | 6 | Greek QA, full diagnostic, bulk ops, account audit |
Vault & Intelligence | 2 | Client vault reader, concept selection |
Optimization Engine | 4 | Optimization cycles, launch planning, execution packs |
Mutation Corridor | 2 | Budget/targeting changes with verification |
Activation & Rollback | 4 | Status changes and undo with preflight checks |
Review Queue | 7 | Operator review queue, outcome snapshots, digests |
Learning Layer | 5 | Policy memory, outcome evaluation, learning cycles |
Experiments | 7 | A/B testing, budget governor, creative rotation, scaling |
Copy Generation | 2 | Auto copy chain, vault-grounded Greek copy |
Engine Features
Optimization loops - automated budget shifting based on performance signals
Experiment management - A/B test tracking with statistical significance
Budget governors - prevent overspend with configurable daily/lifetime limits
Creative rotation - fatigue detection and automatic creative refresh triggers
Policy learning - tracks action outcomes and adapts confidence over time
Naming gate - hard enforcement of naming conventions before any API write
Safety Features
Rate limiting - respects Meta API rate limits with backoff
Rollback - undo recent changes with execution journal
Duplicate checking - prevents accidental duplicate campaigns/ads
File locks - safe concurrent access to vault storage
Tier-based access - safety tiers per account (sandbox, standard, production)
Validator Suite
Compliance validator - Meta ad policy pre-check
Creative spec validator - image/video dimension and format validation
Tracking validator - pixel and event verification before launch
Structure validator - campaign structure consistency checks
Operational validator - budget, schedule, and targeting sanity checks
Non-Shipped Code
Code that exists in the repository but is NOT part of the active tool surface:
reporting/templates.py, reporting/formatter.py - not imported at runtime, no active report generation
evals/ - internal evaluation stubs, not operator-facing
Internal helpers (not MCP tools): identity.py (IG resolution), api.py (HTTP client), auth.py (token verification), utils.py (format helpers), safety/ (rate limiter, rollback, dedup), validators/ (pre-write validation pipeline)
Setup
1. Install
cd meta-ads-mcp
uv sync2. Environment Variables
Copy .env.example to .env and fill in your values:
cp .env.example .envRequired:
META_ACCESS_TOKEN- Meta Marketing API access token (system user token recommended)
Optional:
META_APP_SECRET- for appsecret_proof (recommended for production)META_APP_ID- Meta app IDVAULT_PATH- path to your marketing vault directory (defaults to~/marketing-vault)
3. MCP Configuration
Add to your Claude Code MCP config (.mcp.json):
{
"mcpServers": {
"meta-ads": {
"command": "uv",
"args": ["--directory", "/path/to/meta-ads-mcp", "run", "python", "-m", "meta_ads_mcp"],
"env": {
"META_ACCESS_TOKEN": "your_token_here",
"VAULT_PATH": "/path/to/your/marketing-vault"
}
}
}
}4. Vault Structure (Optional)
If using the vault integration for client intelligence:
your-vault/
01_CLIENTS/{client-slug}/
00-profile.md # Account IDs, pixel, page, IG
02-icp-personas.md # Target audience profiles
04-brand-voice.md # Tone, language, style rules
05-messaging-house.md # Angles, value props
08-objections.md # Objections + bias deployment
matrix.md # Decision Matrix
02_COMPETITORS/{slug}/
landscape.md # Competitive landscapeTesting
uv run --extra dev python -m pytest tests/ -v
# Public package: 215 passed | Full (with premium): 246 passedLicense
MIT - see LICENSE.
Available Tools
57 toolsbulk_rename_objectsA
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'}, ...]
Inputs: renames_json (required).
check_token_statusA
Check Meta API token health, permissions, and rate limit status.
Returns token validity, granted permissions, missing permissions, and current rate limit usage percentage.
Inputs: no named parameters.
create_ad_creativeA
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.
Inputs: account_id (required), page_id (required), image_hash (required), link_url (required), +5 more.
create_ad_from_manifestA
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.
Inputs: account_id (required), adset_id (required), logical_creative_id (required), manifest_json (required), +19 more.
create_adsetA
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.
Inputs: account_id (required), campaign_id (required), name (required), optimization_goal (required), +16 more.
create_campaignA
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.
Inputs: account_id (required), name (required), objective (required), special_ad_categories, +3 more.
create_multi_asset_adA
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.
Inputs: account_id (required), adset_id (required), page_id (required), ad_name (required), +15 more.
create_product_setA
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"}}'
Inputs: catalog_id (required), name (required), filter_json (required).
delete_campaign_structureA
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.
Inputs: account_id (required), campaign_ids_json, delete_all_active, confirm.
diagnose_pixel_on_siteA
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.
Inputs: url (required), pixel_id.
discover_all_accountsA
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.
Inputs: no named parameters.
duplicate_adsetA
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.
Inputs: adset_id (required), target_campaign_id (required), account_id (required), name_suffix, +1 more.
duplicate_campaignA
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.
Inputs: campaign_id (required), account_id (required), name_suffix, include_adsets, +2 more.
estimate_audience_sizeA
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}'
Inputs: account_id (required), targeting_json (required).
generate_namesA
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.
Inputs: object_type (required), objective, product, funnel, +8 more.
get_account_infoA
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').
Inputs: account_id (required).
get_account_pagesA
List Facebook Pages available for ads on a specific ad account.
Args: account_id: Ad account ID (e.g., 'act_123456789').
Inputs: account_id (required).
get_ad_accountsA
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).
Inputs: limit.
get_ad_creativesA
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).
Inputs: account_id (required), ad_id, limit.
get_ad_detailsC
Get detailed ad information including creative reference, tracking specs, conversion specs, issues, and recommendations.
Args: ad_id: Ad ID (numeric string).
Inputs: ad_id (required).
get_ad_imageA
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.
Inputs: account_id (required), image_hash (required).
get_adsA
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).
Inputs: account_id (required), campaign_id, adset_id, status_filter, +1 more.
get_adset_detailsA
Get detailed ad set information including targeting, optimization, learning stage, frequency caps, and attribution settings.
Args: adset_id: Ad set ID (numeric string).
Inputs: adset_id (required).
get_adsetsA
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).
Inputs: account_id (required), campaign_id, status_filter, limit.
get_bulk_insightsA
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).
Inputs: time_range, level, limit_accounts.
get_campaign_detailsA
Get detailed information about a specific campaign including budget, objective, bid strategy, special categories, and issues.
Args: campaign_id: Campaign ID (numeric string).
Inputs: campaign_id (required).
get_campaignsA
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).
Inputs: account_id (required), status_filter, limit.
get_catalog_infoA
Get catalog details including product count, vertical, name, and connected event sources (pixels).
Args: catalog_id: Product catalog ID (numeric string).
Inputs: catalog_id (required).
get_catalog_productsA
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'.
Inputs: catalog_id (required), limit, filter_availability.
get_creative_detailsB
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.
Inputs: creative_id (required), account_id.
get_event_statsA
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'.
Inputs: pixel_id (required), archetype.
get_insightsA
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).
Inputs: object_id (required), time_range, breakdowns, level, +3 more.
get_instagram_identitiesA
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').
Inputs: account_id (required).
get_interest_suggestionsA
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).
Inputs: interest_list (required), limit.
get_pixel_eventsA
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).
Inputs: pixel_id (required).
get_pixel_infoA
Get pixel status, connections, last fired time, and availability.
Args: pixel_id: Pixel ID (numeric string).
Inputs: pixel_id (required).
get_product_setsC
List product sets in a catalog with product counts and filter rules.
Args: catalog_id: Product catalog ID.
Inputs: catalog_id (required).
list_custom_audiencesA
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).
Inputs: account_id (required), limit.
poll_video_processingA
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).
Inputs: video_id (required), max_attempts, poll_interval_seconds.
read_client_vaultA
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.
Inputs: account_id (required), include_context.
resolve_page_identityB
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.
Inputs: page_id (required), account_id.
run_setup_checkA
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.
Inputs: no named parameters.
run_tracking_diagnosticB
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.
Inputs: account_id (required), archetype.
search_behaviorsA
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).
Inputs: query, limit.
search_demographicsA
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).
Inputs: query, limit.
search_geo_locationsB
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).
Inputs: query (required), location_type, limit.
search_interestsA
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).
Inputs: query (required), limit.
send_test_eventA
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"}').
Inputs: pixel_id (required), event_name, test_event_code, custom_data.
update_adA
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').
Inputs: ad_id (required), name, status, creative_id.
update_ad_creativeA
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.
Inputs: creative_id (required), name.
update_adsetA
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).
Inputs: adset_id (required), name, status, daily_budget, +4 more.
update_campaignA
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.
Inputs: campaign_id (required), name, daily_budget, lifetime_budget, +4 more.
update_product_setB
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.
Inputs: product_set_id (required), name, filter_json.
upload_ad_imageA
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.
Inputs: account_id (required), image_url (required), name.
upload_video_assetA
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.
Inputs: account_id (required), video_path (required), title, description.
upload_video_resumableA
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).
Inputs: account_id (required), video_path (required), title, chunk_size_mb.
validate_catalog_connectionsB
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.
Inputs: catalog_id (required), account_id, pixel_id, page_id.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 57 tools
Most tools target distinct resources with clear get/create/update verbs, but there are overlapping creation paths (create_ad_from_manifest, create_multi_asset_ad, create_ad_creative) and two video upload tools serving the same purpose. Several pixel/tracking diagnostic tools also have blurry boundaries, requiring careful description reading to select correctly.
The overwhelming majority follow a verb_noun snake_case pattern like get_campaigns, create_adset, search_interests, and update_product_set. Minor inconsistencies exist, such as list_custom_audiences where list_ is used instead of get_, and a few longer composite names, but no mixed naming styles or chaotic conventions appear.
With 57 tools, the surface is far beyond the 3-15 range that typically indicates a focused, well-scoped server. The count is somewhat justified by the breadth of Meta Ads (campaigns, creatives, targeting, pixels, catalogs, insights), but it still feels heavy and will burden agent selection.
The core campaign/adset/ad lifecycle is well covered with create, read, and update operations, plus solid supporting tools for creatives, targeting, pixels, catalogs, and insights. Notable gaps include no way to delete a single ad or ad set (only entire campaign structures), no custom audience creation/update/delete, and no ad account update or catalog deletion.
Maintenance
Related MCP Connectors
60+ Meta Ads tools for AI agents: audits, campaign management, audiences and CAPI tracking.
Meta, TikTok, LinkedIn, Snapchat and Reddit ads in Claude. Connect an ad account first.
Analyze, edit and launch Meta (Facebook and Instagram) ads from Claude, ChatGPT, Cursor or Codex. Query insights and campaign health, change budgets, bids, status and targeting with undo, bulk-launch many ads across campaigns and ad sets from a live ad's settings, and duplicate by post to keep social proof. Choose per ad account what the agent may do and what waits in the Agent Inbox for approval. Requires a paid Ads Uploader account with MCP access.
Run Google Ads and Meta Ads from ChatGPT or Claude: audit wasted spend, create and manage campaigns.
Related MCP Servers
- AlicenseAqualityBmaintenanceA Model Context Protocol server that allows AI models to access, analyze, and manage Meta advertising campaigns, enabling LLMs to retrieve performance data, visualize ad creatives, and provide strategic insights for Facebook and Instagram platforms.351,368Business Source 1.1
- AlicenseAqualityCmaintenanceEnables users to create, manage, and monitor Meta (Facebook/Instagram) ad campaigns directly from Claude using natural language.13145 PyPI17MIT
- AlicenseAqualityCmaintenance50 tools for Meta Ads campaign management, creative analysis, audience building, and conversion tracking, accessible to any MCP-compatible AI agent.69110 npm13MIT
- AlicenseNot gradedqualityDmaintenanceManage Facebook and Instagram ad campaigns directly from Claude Code, enabling performance viewing, budget adjustments, and campaign control without opening Ads Manager.MIT