Meta Ads: MCP tool reference

The Valkiria MCP server at https://valkiria.pro/mcp gives a connected assistant 28 tools for ad accounts, campaigns, ad sets, ads and budgets on Facebook and Instagram. 12 of them only read. The assistant picks the tool itself; this page lists what exists, under the names it reports in its tool calls.

Checked:

01

Tools that read (12)

These only return data. They are not counted against the monthly allowance.

  • meta_campaign_details: One Meta campaign read live from Meta: status, objective, budget, and its ad sets (optimization, budget, targeting summary, learning stage) with their ads (status, copy, link, review feedback). Budgets are in the ad account currency. Read-only.
  • meta_list_ad_sets: Ad sets of one Meta campaign, live: status, optimization goal, billing event, bid strategy, daily/lifetime budget (account currency), schedule, learning stage and the full targeting spec as Meta stores it (use it as the base for meta_update_ad_set_targeting). Read-only.
  • meta_list_ads: Ads of one Meta ad set or campaign, live: status, effective status and a creative summary (primary texts, headlines, descriptions, destination link, whether it promotes an existing post). Pass exactly one of adSetId or campaignId. Read-only.
  • meta_ad_performance: Per-ad performance from Meta Insights for an ad account, campaign or ad set: spend, impressions, clicks, CTR, CPC, CPM, reach, frequency and conversion-type actions, in the account currency. A null or missing metric means Meta did not report it, not zero. Read-only.
  • meta_wasted_spend: Ads that spent money without a single conversion-type action (lead, purchase, registration, contact…) in the period, from Meta Insights, with each ad's share of the scope's spend. minSpend filters noise (account currency, default 0). A zero only means Meta attributed no conversion: check tracking before pausing. A null or missing metric means Meta did not report it, not zero. Read-only.
  • meta_creative_fatigue: Ads whose audience is tiring: week over week (last 14 or 30 days) frequency rose by 15% or more to at least 2 while CTR fell by 15% or more, on at least 500 impressions per week. Returns the weekly numbers behind each verdict; an empty list means no ad met the rule, not that every creative is fresh. Read-only.
  • meta_placement_breakdown: Spend and results by placement (publisher platform / position, e.g. "instagram / instagram_stories") for an ad account, campaign or ad set, from Meta Insights, in the account currency. Use it before meta_update_placements. A null or missing metric means Meta did not report it, not zero. Read-only.
  • meta_delivery_status: Why ads are or are not delivering, live from Meta: effective status per ad, Meta's own rejection reasons (ad_review_feedback, per policy and placement) and delivery issues (issues_info) exactly as Meta words them. By default only ads that are disapproved, with issues or in review; set all=true for every ad. Pass exactly one of accountId, campaignId or adSetId. Read-only.
  • meta_list_audiences: Custom and lookalike audiences of one Meta ad account, live: type, approximate size range as Meta reports it, delivery and operation status, retention. Sizes are Meta's estimates; a missing size means Meta withheld it. Read-only.
  • meta_list_pixels: Pixels (datasets) of one Meta ad account, live, with the time Meta last received an event from each. A pixel that never fired has lastFiredTime null. Read-only.
  • meta_list_pages: Facebook Pages the connected Meta login can advertise from and, when accountId is given, the Instagram accounts attached to that ad account. Use a page id for new ads (meta_add_ad, meta_promote_post). Read-only.
  • meta_targeting_search: Search Meta's own targeting catalogue: interests, behaviors, locations, locales, employers, schools. Returns Meta ids and Meta's audience size figures (never estimates of ours) to use in meta_update_ad_set_targeting or meta_add_ad_set. Read-only.

02

Tools that change or generate (16)

A change requested through these tools follows the safety rules below: it is a proposal unless the write policy you set for the account allows it.

  • meta_pause_campaign: Propose pausing a Meta campaign. Pausing stops its spend and can be undone. Nothing changes in the ad account: this creates a proposal with a before-snapshot and returns proposal_id and approval_url; the owner approves or rejects it in Valkiria.
  • meta_resume_campaign: Propose resuming a paused Meta campaign. Resuming starts spend again, so it always waits for the owner. Nothing changes in the ad account: this creates a proposal with a before-snapshot and returns proposal_id and approval_url; the owner approves or rejects it in Valkiria.
  • meta_pause_ad_set: Propose pausing a Meta ad set. Pausing stops its spend and can be undone. Nothing changes in the ad account: this creates a proposal with a before-snapshot and returns proposal_id and approval_url; the owner approves or rejects it in Valkiria.
  • meta_resume_ad_set: Propose resuming a paused Meta ad set. Resuming starts spend again, so it always waits for the owner. Nothing changes in the ad account: this creates a proposal with a before-snapshot and returns proposal_id and approval_url; the owner approves or rejects it in Valkiria.
  • meta_pause_ad: Propose pausing a Meta ad. Pausing stops its spend and can be undone. Nothing changes in the ad account: this creates a proposal with a before-snapshot and returns proposal_id and approval_url; the owner approves or rejects it in Valkiria.
  • meta_resume_ad: Propose resuming a paused Meta ad. Resuming starts spend again, so it always waits for the owner. Nothing changes in the ad account: this creates a proposal with a before-snapshot and returns proposal_id and approval_url; the owner approves or rejects it in Valkiria.
  • meta_update_campaign_budget: Propose a new daily or lifetime budget for a Meta campaign that holds its budget at campaign level. The amount is in the account currency in normal units; zero-decimal currencies (JPY, KRW, VND, CLP…) take whole amounts and are sent to Meta without the x100 other currencies need. Nothing changes in the ad account: this creates a proposal with a before-snapshot and returns proposal_id and approval_url; the owner approves or rejects it in Valkiria.
  • meta_update_ad_set_budget: Propose a new daily or lifetime budget for a Meta ad set that holds its own budget. The amount is in the account currency in normal units; zero-decimal currencies (JPY, KRW, VND, CLP…) take whole amounts and are sent to Meta without the x100 other currencies need. Nothing changes in the ad account: this creates a proposal with a before-snapshot and returns proposal_id and approval_url; the owner approves or rejects it in Valkiria.
  • meta_update_ad_set_targeting: Propose a targeting change for a Meta ad set as a patch in Meta's targeting-spec format. Each top-level key you pass (age_min, age_max, genders, geo_locations, flexible_spec, custom_audiences, excluded_custom_audiences, locales…) replaces that key; null removes it; every key you do not pass is kept. The patch is merged onto the targeting the ad set has at approval time, so nothing else is wiped. Read the current spec with meta_list_ad_sets; find ids with meta_targeting_search. For placements use meta_update_placements. Nothing changes in the ad account: this creates a proposal with a before-snapshot and returns proposal_id and approval_url; the owner approves or rejects it in Valkiria.
  • meta_update_placements: Propose where a Meta ad set delivers. Either automatic=true (Advantage+ placements: all manual placement keys are removed) or publisherPlatforms with optional positions per platform; positions of a platform left out are removed with it. Audience, locations and every other targeting field are kept. See meta_placement_breakdown for what each placement brings. Nothing changes in the ad account: this creates a proposal with a before-snapshot and returns proposal_id and approval_url; the owner approves or rejects it in Valkiria.
  • meta_update_ad_set_schedule: Propose a new start and/or end time for a Meta ad set. endTime=null removes the end date (not allowed with a lifetime budget). Meta refuses a new start time once an ad set has started delivering; its answer is reported as is. Nothing changes in the ad account: this creates a proposal with a before-snapshot and returns proposal_id and approval_url; the owner approves or rejects it in Valkiria.
  • meta_add_ad_set: Propose a new ad set in an existing Meta campaign. It is always created PAUSED. targeting is a Meta targeting spec and must contain geo_locations; Audience Network is off unless publisher_platforms names it. Give a budget only when the campaign does not hold the budget itself; amounts are in the account currency in normal units (whole amounts for JPY, KRW, VND, CLP…). Without optimizationGoal/billingEvent the campaign's existing ad sets are used as the model. Nothing changes in the ad account: this creates a proposal with a before-snapshot and returns proposal_id and approval_url; the owner approves or rejects it in Valkiria.
  • meta_add_ad: Propose a new ad in an existing Meta ad set from media that already exists at a public https URL: one image, one video, or a carousel of 2-10 image cards. It is always created PAUSED. Image and video need mediaUrl; a carousel needs cards and pageId (meta_list_pages). Meta requires pixel tracking by platform rule: without a pixel on the account, set noPixelAcknowledged=true to accept worse conversion tracking. Nothing changes in the ad account: this creates a proposal with a before-snapshot and returns proposal_id and approval_url; the owner approves or rejects it in Valkiria.
  • meta_update_ad_copy: Propose new primary text, headline and/or destination link for a Meta ad. Meta creatives are immutable, so on approval a copy of the creative is made with the new text and the ad is switched to it; the ad goes through Meta review again and loses likes and comments gathered on the old creative. Undo switches the ad back to the previous creative. Ads that promote an existing post or use a dynamic creative cannot be edited this way. Nothing changes in the ad account: this creates a proposal with a before-snapshot and returns proposal_id and approval_url; the owner approves or rejects it in Valkiria.
  • meta_duplicate_campaign: Propose a PAUSED copy of a Meta campaign in the same ad account: name with "(Copy)", same objective and campaign budget. Ad sets and ads are not copied; add them with meta_add_ad_set and meta_add_ad. Nothing changes in the ad account: this creates a proposal with a before-snapshot and returns proposal_id and approval_url; the owner approves or rejects it in Valkiria.
  • meta_promote_post: Propose an ad that promotes an existing Facebook Page post (keeping its likes and comments) in an existing Meta ad set. The ad is always created PAUSED. pageId comes from meta_list_pages; postId is the post id on that Page. Without a pixel on the account set noPixelAcknowledged=true. Nothing changes in the ad account: this creates a proposal with a before-snapshot and returns proposal_id and approval_url; the owner approves or rejects it in Valkiria.

03

How changes stay safe

  • Two scopes, chosen by you at sign-in: read, and propose. With read alone the assistant cannot request any change.
  • A change requested from an assistant is a proposal. It waits in Approvals in Valkiria until the account owner approves it, unless the write policy you set for that account allows that kind of change by itself.
  • New campaigns are created paused. Starting new spend and deleting always wait for a person.
  • The assistant can list what is waiting for approval and reject a proposal. It cannot approve one: approval stays with the owner in Valkiria.
  • The change history shows who or what made each change and the value before and after, with Undo where the change can be reversed.
  • You can disconnect an assistant at any time on the Connect AI page; a developer API key can be deleted the same way.

04

Limits

  • The assistant sees only your own Valkiria workspace, and only the ad accounts connected there.
  • Numbers are as fresh as the last sync or import; the assistant can tell you when that was.
  • Money stays in each account's own currency. Different currencies are not converted or added up.
  • Reading data is not counted against the monthly allowance; changes and AI generations are. Allowances per plan are on the pricing page.

05

FAQ

Connect an assistant and call the first tool

Create a free account, connect an ad account and add the connector. The first pass only reads.

Drag to move. Alt + arrow keys move the button; Alt + Home resets its position.

Cookie Preferences

We use cookies to enhance your experience. Essential cookies are always active. You can manage optional cookies below.

Essential
Analytics
Marketing
Third-Party