Ads Uploader: Meta Ads MCP
Server Details
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.
- Status
- Healthy
- Uptime
- 100.0% over the last 24 hours
- OAuth
- Works in Glama
- Last Tested
- Transport
- Streamable HTTP · MCP 2025-06-18
- URL
- Repository
- adsuploader/meta-ads-mcp
- GitHub Stars
- 1
- Server Listing
- Ads Uploader: Meta Ads MCP
- ChatGPT
- –
- Claude
- –
TDQS
Scored across 60 tools
Most tools have a clearly distinct resource+action (ads_get_ad vs ads_list_ads, ads_edit_preview vs ads_edit_apply, ads_upload vs ads_upload_finalize), and the preview/execute pairing is intentionally symmetrical and well documented. However, the four history tools (ads_list_history, ads_list_change_history, ads_list_inbox_history, ads_list_edits) plus ads_list_edit_reviews overlap enough that an agent must read carefully to pick the right one, and ads_campaign_health vs ads_query_insights / ads_estimate_delivery require close reading of descriptions to separate.
The surface follows a predictable ads_verb_noun pattern (ads_list_campaigns, ads_create_campaign-like operations, ads_get_build, ads_save_preset, ads_delete_build) with consistent snake_case throughout. Minor deviations exist: ads_whoami has no noun separator, ads_preview/ads_create/ads_duplicate omit the object noun, and ads_upload_finalize/ads_upload_refresh_urls put the verb last, but these are readable and few.
60 tools is far above a comfortable agent-facing surface, even for a domain as broad as Meta ads; the set spans campaigns, ad sets, ads, media upload, saved builds, presets, edits, duplications, insights, targeting, catalogs, pages, posts, conversions, inbox and history. Many capabilities are granular variants (four duplicate tools, four history tools, four upload tools) where a smaller, more composable set would likely serve agents better.
The lifecycle is well covered: media ingest with polling and cancellation, build/preset persistence with update and delete, creation with preview and approval gating, editing with undo, duplication with social-proof variants, insights querying, and history/inbox review, plus issue and feature-report escape hatches. Remaining gaps are modest — no direct audience creation (audiences are read-only via ads_list_audiences) and no standalone campaign/ad set creation outside the AdSpec/build path.
Available Tools
60 toolsads_campaign_healthCampaign HealthARead-onlyIdempotentInspect
Answer “how is campaign X doing”: campaign performance, native optimization results, status, budgets, issues and bounded ad set learning counts. Use ads_query_insights for custom analysis. Result indicators and attribution windows stay separate. A 429 carries Retry-After. ROW_QUOTA_EXCEEDED carries the time the quota resets (meta.quota.resetsAt).
Inputs: accountId (required), after, fresh, limit, +3 more.
ads_cancel_jobCancel JobBDestructiveIdempotentInspect
Cancel a running ad creation job or media ingest job.
Inputs: jobId (required).
ads_createCreate Meta AdsADestructiveInspect
Create Meta ads in an ad account from a v1 AdSpec request body or a saved build (buildId). Media comes from an upload batch (uploadId), saved-build mediaItems, copyFromAd or a preset. Existing destinations take campaign.id and adSet.id; campaign.name and adSet.name create new ones. Ad text goes in texts.common or texts.perAd, keyed by file name, as headlines arrays plus bodies and descriptions; CTA fields use Meta enum values such as SHOP_NOW. Supports standard, carousel, flexible and Multi Media ads, partnership ads on uploaded media, Instagram existing-post partnership ads and Product Showcase. ads_preview returns the plan, launch.mode and warnings for the same request, including LAUNCH_GOES_LIVE when create would go straight to Meta. When the account's Launch permission is Allowed, create sends the objects to Meta with the requested status; the hosted tool watches the job for about 40 seconds, then returns status "still_running" with a jobId that ads_get_job reads until complete is true. When Launch is Approval, nothing is created: it returns status "approval_required" with a url and buildId, and the launch waits in the Agent Inbox, where runTitle, reviewId and reason place it in an Agent Inbox run. They only take effect when Launch is Approval; with Allowed they are ignored and listed in an IGNORED_FIELD warning. A repeat with the exact same arguments within 10 minutes returns the existing job instead of creating duplicates (the same idempotencyKey extends this to 24 hours); options.allowRepeatLaunch creates the same ads again, and ads_list_history shows what was launched. New campaigns and ad sets with a lifetime budget need an end time at least 24 hours after the start (LIFETIME_BUDGET_END_* otherwise). adSet.advertiser sets EU names (eu) and verified IDs (verified.fromAdSetId or advertiserId) on new ad sets; Singapore/Taiwan needs a verified advertiser; preview reports newAdSets[].advertiser and VERIFIED_ADVERTISER_MISSING.
Inputs: cta, adSet, texts, reason, +26 more.
ads_delete_buildDelete Saved BuildCDestructiveIdempotentInspect
Delete one saved build by ID.
Inputs: buildId (required).
ads_discard_launchDiscard a Waiting LaunchADestructiveIdempotentInspect
Discard a launch waiting in the Agent Inbox, like its Discard button. Nothing is created in Meta. The saved build stays (ads_delete_build removes it). Launches that already started cannot be discarded. ads_edit_cancel handles edit suggestions.
Inputs: buildId (required), accountId (required).
ads_duplicateDuplicate Campaigns, Ad Sets or AdsADestructiveInspect
Copy campaigns, ad sets or ads in Ads Uploader, with previews, destination settings and account approvals. Copies stay within one ad account. A deep copy includes children; deepCopy: false copies only the root. Ad sets default to their source campaign and ads to their source ad set. rename supports {name}, {date} (UTC) and {index}; only roots are renamed unless renameChildren is true. Copy roots are PAUSED by default and children keep their source status unless childStatus:PAUSED. overrides change targeting, schedule, budget, bid and ad set settings on the copies. EU-targeted ad set copies need dsa_beneficiary and dsa_payor on the source ad set: Meta checks them at copy time, before overrides apply, and preview warns DSA_PAYOR_REQUIRED when they are missing. ads_duplicate_preview returns the full tree, skipped objects, warnings, executionPlan call counts and a resolvedRequest with a sourceFingerprint; ads_duplicate takes that resolvedRequest. Copies run serially, object by object, so Meta deep-copy child limits (3 synchronous / 51 async) do not apply. Copies follow the account's Agent Launch setting on the Account Permissions page, like launches; Agent Edit does not apply. Allowed starts a job (the hosted tool watches it for about 40 seconds, then returns still_running with a nextStep for ads_get_duplication), Approval returns status "pending_approval" with a reviewUrl and nothing is copied until it is approved in the Agent Inbox, and Off returns AGENT_LAUNCH_DISABLED. acknowledgeWarnings records review of that preview's warnings; ACTIVE copies need confirmSpend:true unless the account approval rule is none. SOURCE_CHANGED means the source, destination or copy intent changed since the preview; SOURCE_GONE and DESTINATION_GONE mean one is missing, deleted or archived. Running ads_duplicate again with the same request creates a second copy. Partial means some objects were created before a later step failed; each failure has stage, error and retry information. reason and runTitle label the copy in the Agent Inbox and reviewId adds it to an existing review. ads_duplicate_by_post reuses the existing Page post to keep its likes, comments and shares (social proof).
Inputs: ids (required), level (required), accountId (required), reason, +14 more.
ads_duplicate_by_postDuplicate Ads by PostADestructiveInspect
Duplicate ads while keeping their social proof (likes, comments, shares) by reusing the same Page post; for regular duplication use ads_duplicate. Copies go into an existing ad set (adSetId) or into new ad sets: newAdSet and newAdSetPerAd copy the ad set given in adSetId, which must already be in the destination campaign and may be empty (it needs no ads). For a brand-new empty campaign, first put one ad set in it with no ads (for example ads_duplicate of an ad set with deepCopy:false) and pass that adSetId with newAdSet or newAdSetPerAd, so the ads and their new ad sets are created in the by-post step; the template ad set itself receives no ads. Select ads by Page post ID. Use postIds for discovery or adIds for exact selection, never both. The preview returns sourceCandidates and a pinned resolvedRequest; a post that matches several ads needs adIds, and warned runs need acknowledgeWarnings: true or useCreativeId: true. Copies follow the account's Agent Launch setting on the Account Permissions page, like launches; Agent Edit does not apply. Allowed starts the job, Approval returns status "pending_approval" with a reviewUrl and nothing is copied until it is approved in the Agent Inbox, and Off returns AGENT_LAUNCH_DISABLED. Post-ID copies never require confirmSpend (it is accepted and ignored). reason and runTitle label the copy in the Agent Inbox and reviewId adds it to an existing review. Running it again creates the copies again. The hosted tool watches the job for about 40 seconds, then returns status "still_running" with a jobId that ads_get_duplication reads until complete is true.
Inputs: accountId (required), adIds, paused, reason, +11 more.
ads_duplicate_by_post_previewPreview Duplication by PostARead-onlyIdempotentInspect
Duplicate ads while keeping their social proof (likes, comments, shares) by reusing the same Page post; for regular duplication use ads_duplicate. Previews the copy without creating anything: returns sourceCandidates, a pinned resolvedRequest and a cleaned source-to-destination plan. Select ads by Page post ID. Use postIds for discovery or adIds for exact selection, never both; a post that matches several ads needs adIds.
Inputs: accountId (required), adIds, paused, reason, +11 more.
ads_duplicate_previewPreview DuplicationARead-onlyIdempotentInspect
Copy campaigns, ad sets or ads in Ads Uploader, with previews, destination settings and account approvals. Copies stay within one ad account. A deep copy includes children; deepCopy: false copies only the root. Ad sets default to their source campaign and ads to their source ad set. rename supports {name}, {date} (UTC) and {index}; only roots are renamed unless renameChildren is true. Copy roots are PAUSED by default and children keep their source status unless childStatus:PAUSED. overrides change targeting, schedule, budget, bid and ad set settings on the copies. EU-targeted ad set copies need dsa_beneficiary and dsa_payor on the source ad set: Meta checks them at copy time, before overrides apply, and preview warns DSA_PAYOR_REQUIRED when they are missing. ads_duplicate_preview returns the full tree, skipped objects, warnings, executionPlan call counts and a resolvedRequest with a sourceFingerprint; ads_duplicate takes that resolvedRequest. Copies run serially, object by object, so Meta deep-copy child limits (3 synchronous / 51 async) do not apply. Copies follow the account's Agent Launch setting on the Account Permissions page, like launches; Agent Edit does not apply. Allowed starts a job (the hosted tool watches it for about 40 seconds, then returns still_running with a nextStep for ads_get_duplication), Approval returns status "pending_approval" with a reviewUrl and nothing is copied until it is approved in the Agent Inbox, and Off returns AGENT_LAUNCH_DISABLED. acknowledgeWarnings records review of that preview's warnings; ACTIVE copies need confirmSpend:true unless the account approval rule is none. SOURCE_CHANGED means the source, destination or copy intent changed since the preview; SOURCE_GONE and DESTINATION_GONE mean one is missing, deleted or archived. Running ads_duplicate again with the same request creates a second copy. Partial means some objects were created before a later step failed; each failure has stage, error and retry information. reason and runTitle label the copy in the Agent Inbox and reviewId adds it to an existing review. ads_duplicate_by_post reuses the existing Page post to keep its likes, comments and shares (social proof).
Inputs: ids (required), level (required), accountId (required), reason, +14 more.
ads_edit_applyApply Meta EditsADestructiveInspect
Apply a preview plan to existing Meta objects. Takes the planId from ads_edit_preview (valid for 15 minutes) and the confirm flags named in that preview's requiredConfirmations. Returns a result per change: applied, failed, skipped or pending. Pending means not sent yet and still waiting in its review. Applying the same planId again returns the first result and changes nothing more. Archive and delete cannot be undone. Accounts in review mode return EDITS_REVIEW_REQUIRED with a reviewUrl; those changes are approved in the Agent Inbox.
Inputs: planId (required), accountId (required), confirmSpend, allowLargeChange, +2 more.
ads_edit_cancelCancel Edit ProposalsADestructiveInspect
Cancel pending edit suggestions so they leave the Agent Inbox. Nothing changes in Meta. Pending suggestions only; returns a result per suggestion. With the older reviewId and duplicatesOnly: true it removes a suggestion that is pending in two reviews.
Inputs: reviewId (required), accountId (required), proposalIds, duplicatesOnly.
ads_edit_previewPreview Meta EditsAInspect
Preview edits to existing Meta campaigns, ad sets and ads without changing Meta: status, archive, delete, name, budget, bid (including minimum ROAS), schedule, spend limit, targeting, ad set settings and set_creative (ad text, links and call to action). At most 10 creative edits per plan. Targeting is patched; ads_search_targeting finds IDs and detail: full returns the full resulting audience. set_creative covers standard, placement-customised, multi-media and carousel creatives, with per-card headline, description and link through cards[{card, headline, description, link}]; per-card links are refused on placement-customised carousels. Flexible, catalog, partnership, language and segment customisations are refused with a reason. To change an image or video, create a new ad in the Uploader. Returns the planned changes, warnings (for example ENGAGEMENT_RESET when likes, comments and shares stay with the old post, or NO_CHANGE when a value already matches Meta), requiredConfirmations and settings: the account's edit mode and approval rule, with settings.launch as the separate permission for new-ad launches. In Apply Directly mode it returns a planId that ads_edit_apply takes for 15 minutes. In review mode it queues the changes in the Agent Inbox and returns reviewId and reviewUrl with no plan; the changes are applied when approved there, and nothingQueued: true means every change already matched. reason and runTitle label the suggestions in the Agent Inbox, and a per-operation reason overrides the top-level reason; reviewId adds them to an existing review, moving identical pending suggestions into it, and without reviewId identical pending suggestions are reused instead of queued twice. idempotencyKey makes a repeated request return the same preview (PREVIEW_IN_PROGRESS while the first is still running). Reviews stay readable for seven days after their last update; ads_list_inbox_history keeps 90 days.
Inputs: accountId (required), operations (required), detail, reason, +3 more.
ads_edit_undoPreview an UndoADestructiveInspect
Create a new preview that restores the applied, reversible changes of one edit. It does not apply the undo; the result works like any ads_edit_preview result. Archive and delete return not_reversible. In review mode the undo keeps the original run title and note with an "Undo:" prefix unless runTitle or reason is passed; reviewId adds it to an existing review.
Inputs: editId (required), accountId (required), reason, reviewId, +1 more.
ads_estimate_deliveryEstimate Audience and DeliveryARead-onlyIdempotentInspect
Answer “how big is this audience”: read Meta reach and delivery estimates for AdSpec targeting and an optimization goal. Does not create ads. Estimates are predictions, not guaranteed delivery. A 429 carries Retry-After. ROW_QUOTA_EXCEEDED carries the time the quota resets (meta.quota.resetsAt).
Inputs: accountId (required), targeting (required), optimizationGoal (required), fresh, +1 more.
ads_fork_buildFork Saved BuildAInspect
Fork a saved build into a new autosaved draft: a variant with its own build ID, preserving the original build. The fork copies the uploader configuration and media references and can be edited independently. Returns the source build ID and the new build with its url. Each call creates another fork.
Inputs: buildId (required).
ads_get_accountRead Account DetailsARead-onlyIdempotentInspect
Read an owned Meta ad account’s status, currency, timezone, spend and funding display. Money includes major amounts and raw minor-unit strings. Includes the read-only metaEdits enabled setting and approval rule, plus permissions (visible, read, launch and edit as off, approval or allowed, approvalRule) from the Account Permissions page; CLI/MCP cannot change them. A 429 carries Retry-After. ROW_QUOTA_EXCEEDED carries the time the quota resets (meta.quota.resetsAt).
Inputs: accountId (required), fresh.
ads_get_adGet Ad DetailsARead-onlyIdempotentInspect
Get creative details for ONE Meta ad ID. To read several ads, use ads_list_ads. For a DISAPPROVED or WITH_ISSUES ad it also returns reviewFeedback (Meta's rejection reasons: global and placementSpecific lists of policy and reason) and issues (errorCode, errorSummary, errorMessage, level), which explain why it is not delivering; null means Meta's reasons could not be read.
Inputs: adId (required), accountId (required).
ads_get_adsetGet Ad Set DetailsARead-onlyIdempotentInspect
Read ONE Meta ad set's settings and full targeting, including included and excluded custom audiences. Read before copying or duplicating an ad set.
Inputs: adSetId (required), accountId (required).
ads_get_buildGet Saved BuildARead-onlyIdempotentInspect
Get one saved build by ID with its full spec. The opaque web uploader snapshot webState is included by default; include: ["-webState"] omits it. Other metadata is trimmed for display.
Inputs: buildId (required), include.
ads_get_duplicationGet Duplication StatusARead-onlyIdempotentInspect
Get a regular duplicate or duplicate-by-post job by jobId. Returns complete plus the created, failed and skipped objects. A partial job has created objects: created carries newId and the current name, failed carries stage and error.message, and retryable marks a step that can be retried from the Agent Inbox. Pending approvals have no job until they are approved in the Agent Inbox.
Inputs: jobId (required).
ads_get_editRead Edit ResultsBRead-onlyIdempotentInspect
Read an owned edit and its applied, failed, skipped and pending changes. Pending means not sent yet and still waiting in its review.
Inputs: editId (required), accountId (required).
ads_get_edit_reviewRead an Edit ReviewARead-onlyIdempotentInspect
Read one owned review with compact proposal rows, statuses and edit IDs. Rows with the same operationGroup came from one operation; they are approved, cancelled and fail together. A suggestion shows applying while an approved change is being sent to Meta, then applied or failed. Each row has userEdited {value, note}; when the user changed a suggestion before approving it, suggestedAfter and suggestedReason hold the original suggestion and after and reason hold what the user chose. revisions[] lists each change with who made it, before and after, and restored_to_agent when the original was put back. Duplications include copies[].status (pending, approved, made, partial, failed, rejected), group for split post requests, and summary.copies totals. A partial copy already exists in Meta; its row carries id, currentName, failedStep, a plain error and retry (available, how). Returns 50 proposals by default; paging.after continues and detail: full returns full proposal data.
Inputs: reviewId (required), accountId (required), after, limit, +1 more.
ads_get_insights_jobGet Insights Report JobARead-onlyIdempotentInspect
Read an Insights report job started by ads_query_insights, by job.id and the same accountId. A running result includes progress and pollAfterSeconds. A completed result is one bounded page; paging.after with this tool returns more rows. A 429 carries Retry-After. ROW_QUOTA_EXCEEDED carries the time the quota resets (meta.quota.resetsAt).
Inputs: jobId (required), accountId (required), after, limit, +2 more.
ads_get_jobGet Job StatusARead-onlyIdempotentInspect
Get an ad creation job by jobId. Returns the full result and stage progress by default; compact: true returns an ads summary with created, failed and total counts and progress measured in ads. Includes the last 20 progress.operations (operations: "full" returns all retained ones). A job that is still running has complete: false, and compact running jobs include a nextStep hint.
Inputs: jobId (required), compact, operations.
ads_get_launchRead Launch DetailsARead-onlyIdempotentInspect
Read one Ads Uploader launch: one row per ad with its ID, name, status, ad set, campaign, result and error, plus totals and failures. Use a launchId from ads_list_history rows. detail: 'full' adds targeting, budgets, schedule, creative settings and media.
Inputs: launchId (required), accountId (required), detail.
ads_get_presetGet PresetBRead-onlyIdempotentInspect
Get one saved preset by ID.
Inputs: presetId (required), accountId (required).
ads_get_product_showcase_recommendationGet Product Showcase RecommendationBRead-onlyIdempotentInspect
Read Meta’s Product Showcase recommendation for a Sales campaign destination: products from a catalog shown under a single image or video ad. MUST_PICK requires an explicit productSetId; MANUAL requires catalog and set selection.
Inputs: adUrl (required), accountId (required), pageId, pixelId.
ads_get_uploadGet Upload StatusARead-onlyIdempotentInspect
Get a completed upload batch by batchId (or its alias uploadId), or poll a background media-ingest job by jobId until complete is true. Job polls return the full result, progress and file list by default; pass compact:true for counts and failed files only.
Inputs: jobId, batchId, compact, uploadId, +1 more.
ads_list_accountsList Ad AccountsARead-onlyIdempotentInspect
List Meta ad accounts available to the authenticated Ads Uploader user. Use refresh to re-check Meta for reinstated/changed accounts (rate limited).
Inputs: refresh.
ads_list_adsList AdsARead-onlyIdempotentInspect
List ads in an ad set, or across the whole ad account when adSetId is omitted. To find ads by name without knowing their ad set, omit adSetId and pass search (name contains); each row then includes adsetId, adsetName, campaignId and campaignName. status defaults to 'active', so pass 'all' to include paused ads. To see why ads were rejected or have delivery issues, add reviewFeedback and/or issues to fields (Meta's policy reasons and issues_info); they are read only when named in fields. Returns one bounded page; follow paging.after for more. Use fields to return only the columns you need; large pages are trimmed to fit the output budget.
Inputs: accountId (required), after, fresh, limit, +5 more.
ads_list_adsetsList Ad SetsARead-onlyIdempotentInspect
List ad sets in a campaign, or across the whole ad account when campaignId is omitted. To find ad sets by name without knowing their campaign, omit campaignId and pass search (name contains); each row then includes campaignId and campaignName. Request regionalRegulationIdentities, regionalRegulatedCategories, dsaBeneficiary or dsaPayor in fields for advertiser details. Identities also return regionalRegulationIdentityNames with Meta names or null. status defaults to 'active', so pass 'all' to include paused ad sets. Returns one bounded page; follow paging.after for more. Use fields to return only the columns you need; large pages are trimmed to fit the output budget.
Inputs: accountId (required), after, fresh, limit, +5 more.
ads_list_audiencesList AudiencesARead-onlyIdempotentInspect
List Meta custom, lookalike and saved audiences, size bounds and safe targeting summaries. One cursor page across sources. A 429 carries Retry-After. ROW_QUOTA_EXCEEDED carries the time the quota resets (meta.quota.resetsAt).
Inputs: accountId (required), type, after, fresh, +2 more.
ads_list_buildsList Saved BuildsARead-onlyIdempotentInspect
List saved uploader build summaries for the authenticated user, optionally filtered by ad account. Returns metadata, warning codes, totalAdSets/totalAds/complete from display, and mediaCount. Use ads_get_build for full detail.
Inputs: limit, offset, accountId.
ads_list_campaignsList CampaignsARead-onlyIdempotentInspect
List campaigns in an ad account, optionally filtered by name search and status. Search matches campaign names only; to find ad sets or ads by name, call ads_list_adsets or ads_list_ads without a parent ID. Use fields to return only the columns you need; large pages are trimmed to fit the output budget.
Inputs: accountId (required), after, fresh, limit, +4 more.
ads_list_catalogsList CatalogsBRead-onlyIdempotentInspect
List catalogs this ad account can advertise for Product Showcase: products from a catalog shown under a single image or video ad. Full catalog (dynamic) ads are not supported yet.
Inputs: accountId (required).
ads_list_change_historyRead Meta Change HistoryARead-onlyIdempotentInspect
Meta ad account activity log, including edits made in Ads Manager and other tools. Use ads_list_history for launches and changes made through Ads Uploader. Defaults to the last 7 days; maximum span 90 days. Rows carry objectType AD/AD_SET/CAMPAIGN/AUDIENCE/ACCOUNT plus adSetId/campaignId/audienceId; metaObjectType and extra_data keep Meta’s legacy names (extra_data.campaign_id on an ad is its ad set). A 429 carries Retry-After. ROW_QUOTA_EXCEEDED carries the time the quota resets (meta.quota.resetsAt).
Inputs: accountId (required), after, fresh, limit, +3 more.
ads_list_conversionsList Conversion DefinitionsARead-onlyIdempotentInspect
Read pixels, custom conversion definitions and standard event names. This describes available events, not measured conversion totals. Pixels and custom conversions share one bounded cursor page. A 429 carries Retry-After. ROW_QUOTA_EXCEEDED carries the time the quota resets (meta.quota.resetsAt).
Inputs: accountId (required), after, fresh, limit.
ads_list_edit_reviewsList Edit ReviewsBRead-onlyIdempotentInspect
Read compact account-scoped Edit Review counts, including reviews still being built. Proposals are omitted unless include: proposals.
Inputs: accountId (required), after, limit, include.
ads_list_editsList Edit HistoryARead-onlyIdempotentInspect
Deprecated: use ads_list_history with type changes. Reads one account-scoped cursor page of Ads Uploader edit history.
Inputs: accountId (required), after, limit.
ads_list_historyRead Ads Uploader HistoryBRead-onlyIdempotentInspect
Ads Uploader History: launches and changes made through Ads Uploader (web Uploader, Duplicator, AI Edits, CLI, MCP, API) on one ad account, newest first: the same list as the History page. Duplicator copies read type Duplicate, with duplicate: copy or post. Not Meta's activity log.
Inputs: accountId (required), q, days, type, +4 more.
ads_list_inbox_historyRead Agent Inbox HistoryARead-onlyIdempotentInspect
Read retained Agent Inbox suggestions and direct edit outcomes over the last 90 days, newest first. Includes reason, reasonEdited, runTitle, clientName, before/after, outcome and a plain error, plus userEdited {value, note} with the agent’s own suggestedAfter and suggestedReason when the user changed them (for example, you suggested 6000 and the user changed it to 6100), and revisions[]: every later change, oldest first, with at, by (user or agent, plus source and clientName), kind (value or note), action (edited, or restored_to_agent when your original was put back), field, before and after; revisedAt is the latest. Partial duplicates also include failedStep. Filter by accountId, campaignId, since/until, reviewId (run), status, kind or action; use paging.cursor with the same filters for more. Time is resolution time when present, otherwise suggestion creation time. waiting includes applying; failed includes partial outcomes. Direct edit campaign filters match campaign IDs recorded with those edits. Read permission is required and hidden accounts are excluded. Does not call Meta or change anything.
Inputs: kind, limit, since, until, +6 more.
ads_list_insight_fieldsList Insight FieldsARead-onlyIdempotentInspect
Discover Ads Insights fields by search, group or ids. Without filters, returns a compact group index and recommended fields. accountId adds the custom conversions of that account. Breakdown IDs belong in ads_query_insights.breakdowns, not fields. A 429 carries Retry-After. ROW_QUOTA_EXCEEDED carries the time the quota resets (meta.quota.resetsAt).
Inputs: ids, kind, group, limit, +4 more.
ads_list_library_mediaList Meta Library MediaARead-onlyIdempotentInspect
Read images or videos in the Meta ad account library, separate from Ads Uploader uploads. Returns one cursor page. A 429 carries Retry-After. ROW_QUOTA_EXCEEDED carries the time the quota resets (meta.quota.resetsAt).
Inputs: type (required), accountId (required), after, fresh, +1 more.
ads_list_pagesList Facebook PagesARead-onlyIdempotentInspect
List Facebook Pages (with their connected Instagram accounts) available for profile overrides in an ad account.
Inputs: accountId (required), limit, offset.
ads_list_postsList Promotable PostsARead-onlyIdempotentInspect
Read accessible Facebook Page promotable posts or media for a connected Instagram professional account. Supply exactly one of pageId or igUserId. Messages are limited to 500 characters. A 429 carries Retry-After. ROW_QUOTA_EXCEEDED carries the time the quota resets (meta.quota.resetsAt).
Inputs: accountId (required), after, fresh, limit, +2 more.
ads_list_presetsList PresetsBRead-onlyIdempotentInspect
List saved API or ad text presets for an ad account.
Inputs: accountId (required), type, limit, offset.
ads_list_product_setsList Product SetsBRead-onlyIdempotentInspect
List product sets and sample products for Product Showcase: products from a catalog shown under a single image or video ad. Optionally select one product set.
Inputs: accountId (required), catalogId (required), productSetId.
ads_list_uploadsList Upload BatchesBRead-onlyIdempotentInspect
List recent media upload batches for an ad account.
Inputs: accountId (required), limit, offset.
ads_previewPreview Ad CreationAIdempotentInspect
Preview what ads_create would do for a v1 AdSpec request or saved build, without creating ads. Takes the same inputs as ads_create: existing destinations take campaign.id and adSet.id, and ad text takes headlines arrays. Returns the planned campaigns, ad sets and ads, newAdSets with the exact settings each new ad set would get (targeting, placements, attribution, optimization, pixel and event, bid, budget), warnings (blocking: true marks the ones create rejects), lifetimeBudget when it applies, a resolvedSpec and launch.mode. launch.mode allowed means create sends objects straight to Meta, and the preview then carries a LAUNCH_GOES_LIVE warning; approval means create is held in the Agent Inbox. On ads_create, reviewId, runTitle and reason only take effect when Launch is Approval. For partnership ads it resolves posts and checks Meta permissions with read and validate-only calls and returns per-ad creators, sponsors and authorization status; ad codes are not stored, so create takes them again. Preset-only requests reuse the preset's campaign and ad set and carry a PRESET_DESTINATION_USED warning. productShowcase previews return the selected catalog and product set. adSet.advertiser sets EU names (eu) and verified IDs (verified.fromAdSetId or advertiserId) on new ad sets; Singapore/Taiwan needs a verified advertiser; preview reports newAdSets[].advertiser and VERIFIED_ADVERTISER_MISSING. Uploaded media accepts texts.common.multiAdvertiserAds only (boolean); omit to copy the source, which is off when the source ad does not say. True is refused while site links remain. Imported posts keep per-row choices. Website highlights is copied from the source and cannot be changed; none, all off and empty features never change it. Preview and saved display report both settings separately. video_uncrop and translate_voiceover require source OPT_IN.
Inputs: cta, adSet, texts, adNames, +23 more.
ads_query_insightsQuery Ad Performance InsightsAIdempotentInspect
Query Ads Insights for one account, or 2 to 5 accountIds, one bounded page per account, as table rows by default. Friendly metrics such as leads, purchases, roas, results and cost_per_result cover business questions at campaign, ad set or ad level; ads_list_insight_fields finds other fields. Supports date presets and ranges, timeIncrement, breakdowns (asset, media and hourly breakdowns each alone) and filters. Use compare for vs last period or previous-year questions. Use include for status, budget, targeting or creative context instead of separate list calls. On rows with delivery, omitted counts and values are 0; without delivery they are null, and cost per result stays null for zero results. For audience segment mix (prospecting / engaged / existing customers) use breakdowns: [user_segment_key] alone, with timeIncrement weekly or monthly for share of spend over time. For partnership ads results by creator use breakdowns: [pa_creator_ig_handle] alone with impressions, reach, inline_link_clicks or video_p*_watched_actions; spend, cost and conversions are not available with it. Reach, frequency and CTR are non-additive across rows. Use accountIds for cross-account views; never add totals across accounts. Zero-impression rows are excluded unless excludeZeroImpressions is false, and an empty result is a success. A large report returns status: pending; read it through ads_get_insights_job with job.id. Cached results carry meta.cache.ageSeconds; fresh skips the cache read. paging.after continues a page (paging.byAccount for several accounts). A 429 carries Retry-After. ROW_QUOTA_EXCEEDED carries the time the quota resets (meta.quota.resetsAt).
Inputs: mode, sort, after, fresh, +18 more.
ads_report_issueReport Tool IssueAInspect
Record a problem with these tools for the Ads Uploader team: results that contradict each other, a field that was silently ignored, a saved build display that differs from its preview, or a tool that does not do what its description says. Sends the summary, the expected and actual results and any IDs supplied, not names, emails, ad copy, tokens or other personal data; the server also redacts sensitive text. Returns { reported: true, reference, status: 'queued' }. Each call queues one report; limited to 10 reports per user per hour.
Inputs: tool (required), actual (required), expected (required), adIds, +5 more.
ads_request_featureRequest a Missing CapabilityAInspect
Record a capability these tools do not offer, for the Ads Uploader team: a missing tool, field, filter, action or level. Sends the goal, the missing capability, the tools tried and any IDs supplied, not names, emails, ad copy, tokens or other personal data. Similar requests are grouped and counted. ads_report_issue records problems with existing tools. Returns { requested: true, reference, status: 'recorded' }. Limited to 20 requests per user per hour.
Inputs: goal (required), missingCapability (required), level, accountId, +2 more.
ads_save_buildSave BuildAInspect
Save a durable build: a launch configuration the web uploader can open and ads_create can launch by buildId. A spec-only build is the supported shape for agent-created configurations; the web uploader generates its own webState when it opens the build, and webState is only accepted unchanged from a build that was read. accountId can be omitted when the spec or webState carries it. Returns the build metadata with its url, launchable and launchBlockers, and display: totalAdSets, totalAds and the ads in each ad set as the web uploader renders them (display.complete false carries a reason, and display.inheritedFromSource lists fields that come from the source ad or preset). launchable describes headless ads_create launches only; any build opens in the web uploader. A saved build uses the campaign and ad set of its template ad, or new ones. Video items take the numeric Facebook video id (videoId in the upload result) as mediaId. Each call saves a new build; ads_update_build changes an existing one. Uploaded media accepts texts.common.multiAdvertiserAds only (boolean); omit to copy the source, which is off when the source ad does not say. True is refused while site links remain. Imported posts keep per-row choices. Website highlights is copied from the source and cannot be changed; none, all off and empty features never change it. Preview and saved display report both settings separately. video_uncrop and translate_voiceover require source OPT_IN.
Inputs: name, spec, notes, webState, +1 more.
ads_save_presetSave PresetAInspect
Save an existing ad as a reusable API preset. A preset name that already exists on the account is refused.
Inputs: name (required), fromAdId (required), accountId (required), shareWithTeam.
ads_search_targetingSearch Targeting OptionsARead-onlyIdempotentInspect
Search Meta targeting values for ads_create, a saved build spec, or set_targeting in ads_edit_preview. Use type=city to find targeting.cities[].key values, type=zip to find targeting.zips[].key values, or type=detailed for {id,name,type} entries. Builds use targeting.detailedTargetingGroups; edits use add/remove with the returned type and {id}. IDs must never be guessed; use this tool to discover them.
Inputs: type (required), query (required), accountId (required), limit.
ads_update_buildUpdate Saved BuildADestructiveIdempotentInspect
Update one saved build by ID: rename it, edit notes, patch its portable spec with specPatch, or replace the full spec. specPatch merges field by field: omitted fields survive, nested text entries merge, supplied arrays replace and null removes a field. It needs expectedRevision, the revision from ads_get_build. Changes to spec, webState, mediaItems or uploadBatchId bump the revision. A rename or notes-only update does not bump it. Parallel updates to one build collide on the revision: a stale expectedRevision returns "Build changed since it was read" (HTTP 409), and ads_get_build returns the current revision. spec replaces the whole portable spec. webState is only accepted unchanged from a build that was read; the web uploader regenerates it when it next opens the build, and webStateStale: true until then is normal. Setting a name turns an autosaved build into a kept, named build. An open uploader tab picks up the update automatically. Returns updated metadata and display: totalAdSets, totalAds and the ads in each ad set as the web uploader renders them (display.complete false carries a reason, and display.inheritedFromSource lists fields that come from the source ad or preset); ads_get_build returns the stored state. Uploaded-media texts.perAd keys are file names or media:. CTA fields take Meta enum values such as SHOP_NOW. Uploaded media accepts texts.common.multiAdvertiserAds only (boolean); omit to copy the source, which is off when the source ad does not say. True is refused while site links remain. Imported posts keep per-row choices. Website highlights is copied from the source and cannot be changed; none, all off and empty features never change it. Preview and saved display report both settings separately. video_uncrop and translate_voiceover require source OPT_IN.
Inputs: buildId (required), name, spec, notes, +3 more.
ads_uploadUpload MediaAInspect
Upload media to an ad account. PREFER public HTTPS URLs or a public Google Drive folder link: Ads Uploader downloads each file server-side, processes the batch in the background, and returns a jobId immediately. Poll ads_get_upload with that jobId until complete=true; cancel it with ads_cancel_job if needed. Each call starts a new batch. Google Drive file links are detected automatically. Use inline base64 only for a couple of small images; presigned:true is only for environments that can PUT bytes themselves. In presigned mode, script:true is recommended for agents with a shell.
Inputs: accountId (required), files, script, batchId, +3 more.
ads_upload_finalizeFinalize Media UploadAInspect
Finalize a presigned upload batch after the client has PUT each file. Hosted calls return a background ingest jobId that ads_get_upload reads.
Inputs: batchId (required), accountId (required), files, thumbnailMap.
ads_upload_refresh_urlsRefresh Upload LinksAIdempotentInspect
Refresh expired upload links for selected files or multipart part numbers in the same batch. Files already uploaded are kept. Single-PUT file keys may change; the returned keys are the ones ads_upload_finalize takes.
Inputs: files (required), batchId (required), accountId (required).
ads_whoamiShow Authenticated UserARead-onlyIdempotentInspect
Show which Ads Uploader user this session is signed in as (email, name, user ID) and the API host it talks to.
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Related MCP Connectors
The simplest way to manage your Meta (Facebook and Instagram) ad accounts with your AI agent.
Run Facebook, Instagram and Google ads from Claude, ChatGPT, Grok or Cursor, in plain English.
Create, launch, and manage Meta + Google ads from Claude and ChatGPT.
Manage and optimize your ads on Meta, Google, TikTok, X, ChatGPT Ads, Reddit and LinkedIn from chat.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to run Meta (Facebook and Instagram) advertising: pull spend, CPA, ROAS and breakdown reports, audit account health, build and boost campaigns, ad sets and ads, and pause or adjust budgets, all starting paused until the user approves going live. Also supports brand memory, change logs and an optional daily spend cap.MIT
- FlicenseNot gradedqualityCmaintenanceCreate and manage Facebook & Instagram (Meta) ad campaigns from Claude, ChatGPT & Cursor — bulk creation, multi-account, and spend guardrails. Hosted, Meta Verified Tech Provider.3-
- AlicenseAqualityCmaintenanceEnables users to create, manage, and monitor Meta (Facebook/Instagram) ad campaigns directly from Claude using natural language.13137 PyPI17MIT
- FlicenseNot gradedqualityCmaintenanceEnables users to build, edit, transfer, report on, and monitor ad campaigns across Meta, Google, TikTok, Snapchat, and other connected ad platforms from Claude, ChatGPT, and other MCP clients.-
Glama MCP Gateway
Add one secure layer between your agents and this server.