Skip to main content
Meta Ads is a read + guardrailed write connector, called via tools/call over POST /meta-ads/mcp. The connector is connected through OAuth (Facebook Login; see Forbind Meta Ads).
Endpoint: https://mcp.consile.ai/meta-ads/mcp. Meta Ads is its own named connector with only its own tools.
Meta issues long-lived access tokens (~60-day expiry) via fb_exchange_token. There is no refresh_token. When the token expires, reconnect is required. Use list_ad_accounts as a lightweight connectivity test; a 401 from Meta surfaces as AccessTokenExpiredError. See Errors & limits.

​
Write safety: guardrail model

The five write tools (create_campaign, create_ad_set, create_ad, update_status, update_budget) share a connector-local guardrail:
  1. New objects are always created PAUSED. Nothing spends until you explicitly activate. Pass status: "ACTIVE" only when you are ready to launch, and always with confirm: true.
  2. Spend, budget, and archival actions require confirm: true. These are: setting status to ACTIVE (spend starts), setting status to ARCHIVED (permanent disable), and any budget change. Without confirm: true, the tool returns a WritePreview dry-run and calls no Meta API.
  3. Pausing is always safe. Setting status: "PAUSED" does not require confirmation.
  4. There is no hard-delete. Removal is archival (status: "ARCHIVED").
This is a designed-in safety default (connector-local application logic), not an unbreakable platform gate. See Handlinger & guardrails for the full cross-connector policy.

​
WritePreview shape

When a write action requires confirmation but confirm is omitted or false, every write tool returns this shape instead of calling Meta: 
{
  "preview": {
    "action": "create_campaign",
    "summary": "Create campaign \"Summer Sale\" (objective OUTCOME_TRAFFIC) as PAUSED.",
    "request": {
      "method": "POST",
      "path": "act_1234567890/campaigns",
      "body": {
        "name": "Summer Sale",
        "objective": "OUTCOME_TRAFFIC",
        "status": "PAUSED",
        "special_ad_categories": "[]"
      }
    },
    "confirmHint": "Re-run the same call with confirm: true to apply this change."
  }
}
To apply, re-run the identical call with confirm: true added.

​
CREATE_DEFAULT_STATUS

The default initial status for all create tools is PAUSED. The connector enforces this as a defense-in-depth fallback even if status is absent in the call.

​
Shared parameters

​
Ad account id

All account-scoped tools accept adAccountId in either the act_<digits> form or as bare digits. The connector normalizes to act_<digits> before calling the Graph API.

​
Date window / preset

The insights tools accept either an explicit date range or a preset:
​
fromDate
string (YYYY-MM-DD)
Start of an explicit window. Must be paired with toDate.
​
toDate
string (YYYY-MM-DD)
End of the window.
​
datePreset
string
default:"last_30d"
A Meta date preset, used when fromDate/toDate are omitted. Allowed values: today, yesterday, last_7d, last_14d, last_28d, last_30d, last_90d, this_week_mon_sun, last_week_mon_sun, this_month, last_month, this_quarter, maximum.

​
limit

​
limit
integer
default:"100"
Maximum rows to return. The client paginates internally (cursor-based, up to 25 pages) and caps at 5000. Default 100.

​
Money fields (minor units)

Budget and bid arguments on the write tools use minor units of the account currency (e.g. 5000 = 50.00 DKK/EUR/USD). Insights money fields (spend, cpc, cpm) are returned as Meta delivers them: decimal strings in the account currency’s major unit.

​
Read tools: accounts & structure (34 total)

​
list_ad_accounts

List the Meta ad accounts the connected login can access. Use this as the first call to discover the act_<id> required by all other tools.
​
limit
integer
default:"100"
Returns: count, data[] with account_id, id, name, account_status, currency, timezone_name, business.

​
get_account_info

Read one ad account’s profile.
​
adAccountId
string
required
Meta ad account id (act_<digits> or bare digits).
Returns: account_id, name, account_status, currency, timezone_name, amount_spent, spend_cap, balance, business.

​
get_account_billing_summary

Spend posture for one account: caps, balances, prepay status, and disable reason. Does not include payment-instrument data.
​
adAccountId
string
required
Returns: spend_cap, amount_spent, balance, currency, is_prepay_account, account_status, disable_reason, min_daily_budget.

​
list_campaigns

List campaigns with status, objective, budgets and schedule.
​
adAccountId
string
required
​
effectiveStatus
string[]
Filter by effective_status. Allowed values: ACTIVE, PAUSED, DELETED, ARCHIVED, IN_PROCESS, WITH_ISSUES.
​
limit
integer
default:"100"
Returns: id, name, objective, status, effective_status, buying_type, daily_budget, lifetime_budget, bid_strategy, start_time, stop_time, special_ad_categories, created_time, updated_time.

​
list_ad_sets

List ad sets. Optionally scope to one campaign.
​
adAccountId
string
required
​
campaignId
string
Scope to one campaign id (bare digits).
​
limit
integer
default:"100"
Returns: id, name, campaign_id, status, effective_status, optimization_goal, billing_event, bid_strategy, bid_amount, daily_budget, lifetime_budget, start_time, end_time.

​
list_ads

List ads. Optionally scope to one ad set.
​
adAccountId
string
required
​
adSetId
string
Scope to one ad set id.
​
limit
integer
default:"100"
Returns: id, name, adset_id, campaign_id, status, effective_status, creative{id}, created_time, updated_time.

​
Read tools: creatives & assets

​
list_creatives

List ad creatives (identity-level) for the account.
​
adAccountId
string
required
​
limit
integer
default:"100"
Returns: id, name, title, body, object_type, call_to_action_type, thumbnail_url, image_url, instagram_permalink_url, effective_object_story_id.

​
list_ad_creatives_detail

Every creative with fully hydrated content (object_story_spec, CTA, image_url, video_id, link_url, url_tags) for messaging and UTM audits.
​
adAccountId
string
required
​
limit
integer
default:"100"
Returns: All fields of list_creatives plus object_story_id, object_story_spec, image_hash, video_id, link_url, url_tags.

​
get_ad_creative

Full creative detail for one creative id: what does this ad actually say, show, or link to.
​
creativeId
string
required
Numeric Graph creative id (bare digits).
Returns: Full hydrated creative including object_story_spec, CTA, image_url, image_hash, video_id, url_tags, page and Instagram ids.

​
get_ad_creative_asset_feed_spec

The asset_feed_spec of a Dynamic or Advantage+ creative: candidate images, videos, bodies, titles, descriptions, link URLs, CTA options and customization rules. For dynamic ads the flat fields are empty; this is the only read of the variants.
​
creativeId
string
required
Returns: id, name, asset_feed_spec, degrees_of_freedom_spec, object_type.

​
get_ad_preview

Render a placement preview of an existing ad (same render as Ads Manager).
​
adId
string
required
Numeric Graph ad id.
​
adFormat
string
default:"MOBILE_FEED_STANDARD"
A Meta ad_format enum, e.g. MOBILE_FEED_STANDARD, INSTAGRAM_STORY, FACEBOOK_REELS_MOBILE, DESKTOP_FEED_STANDARD.
Returns: An array of preview iframe bodies from the Graph /previews edge.

​
list_ad_images

Account image library with viewable URLs. Resolves a creative’s image_hash.
​
adAccountId
string
required
​
limit
integer
default:"100"
Returns: hash, name, url, url_128, permalink_url, width, height, status, created_time.

​
Read tools: insights & performance

All insights tools accept the shared date window / preset and limit parameters.

​
account_insights

Account-level performance headline: impressions, reach, clicks, spend, CTR, CPC, CPM, frequency, actions.
​
adAccountId
string
required
​
fromDate
string
​
toDate
string
​
datePreset
string
default:"last_30d"
​
limit
integer
default:"100"

​
campaign_insights

Per-campaign performance. Optionally scope to one campaign.
​
adAccountId
string
required
​
campaignId
string
Scope to one campaign id.
​
fromDate
string
​
toDate
string
​
datePreset
string
default:"last_30d"
​
limit
integer
default:"100"

​
ad_set_insights

Per-ad-set performance. Optionally scope to one ad set.
​
adAccountId
string
required
​
adSetId
string
Scope to one ad set id.
​
fromDate
string
​
toDate
string
​
datePreset
string
default:"last_30d"
​
limit
integer
default:"100"

​
ad_insights

Per-ad (finest granularity) performance. Optionally scope to one ad.
​
adAccountId
string
required
​
adId
string
Scope to one ad id.
​
fromDate
string
​
toDate
string
​
datePreset
string
default:"last_30d"
​
limit
integer
default:"100"

​
insights_by_breakdown

Performance split by a demographic, geographic or delivery dimension.
​
adAccountId
string
required
​
breakdown
string
required
One of: age, gender, country, region, dma, publisher_platform, platform_position, impression_device, device_platform.
​
level
string
default:"account"
Aggregation level: account, campaign, adset, or ad.
​
fromDate
string
​
toDate
string
​
datePreset
string
default:"last_30d"
​
limit
integer
default:"100"

​
get_conversion_actions

Conversions broken out by action_type (purchase, lead, add_to_cart, registration, landing_page_view) with cost_per_action_type, conversions, conversion_values, cost_per_conversion: how many leads/purchases and what did each cost.
​
adAccountId
string
required
​
level
string
default:"account"
​
fromDate
string
​
toDate
string
​
datePreset
string
default:"last_30d"
​
limit
integer
default:"100"

​
get_reach_and_frequency

Deduplicated audience view: reach, frequency, unique clicks, unique CTR, cost_per_unique_click. Optional daily time series.
​
adAccountId
string
required
​
level
string
default:"account"
​
daily
boolean
If true, return a per-day time series (time_increment=1).
​
fromDate
string
​
toDate
string
​
datePreset
string
default:"last_30d"
​
limit
integer
default:"100"

​
get_video_metrics

Video-engagement funnel: plays, % watched (25/50/75/95/100), ThruPlay, 30-sec, average time watched, cost_per_thruplay.
​
adAccountId
string
required
​
level
string
default:"account"
​
fromDate
string
​
toDate
string
​
datePreset
string
default:"last_30d"
​
limit
integer
default:"100"

​
creative_asset_insights_breakdown

Per-asset performance inside a Dynamic or Advantage+ ad: which image, video, headline, body, description, or CTA variant drives results. Ad-level only.
​
adId
string
required
A single ad id (bare digits).
​
fromDate
string
​
toDate
string
​
datePreset
string
default:"last_30d"
​
limit
integer
default:"100"

​
Read tools: tracking config

​
list_pixels

Meta Pixels/datasets with health metadata. Returns metadata only (no event payloads).
​
adAccountId
string
required
​
limit
integer
default:"100"
Returns: id, name, last_fired_time, data_use_setting, enable_automatic_matching, is_unavailable, creation_time.

​
list_custom_conversions

Custom conversions and their configuration: source pixel, rule, event type, default value, archive status.
​
adAccountId
string
required
​
limit
integer
default:"100"
Returns: id, name, pixel, rule, custom_event_type, default_conversion_value, is_archived, creation_time.

​
Read tools: audiences & planning

​
list_custom_audiences

Custom Audiences metadata only (Meta stores only hashes; no member data is ever returned): name, subtype, approximate size bounds, operation/delivery status.
​
adAccountId
string
required
​
limit
integer
default:"100"
Returns: id, name, subtype, description, approximate_count_lower_bound, approximate_count_upper_bound, operation_status, delivery_status, retention_days, data_source, is_value_based.

​
list_saved_audiences

Saved (reusable) targeting audiences with their full targeting spec, sentence_lines, and approximate size. Configuration data, not member data.
​
adAccountId
string
required
​
limit
integer
default:"100"
Returns: id, name, description, targeting, approximate_count_lower_bound, approximate_count_upper_bound, run_status, sentence_lines.

​
estimate_reach

Estimated reachable audience size for a targeting spec before spending. Returns an aggregate count (no individuals).
​
adAccountId
string
required
​
targetingSpec
string
required
A Meta targeting_spec as a JSON string, e.g. '{"geo_locations":{"countries":["DK"]}}'.
Returns: users (aggregate estimate), estimate_ready.

​
search_targeting_interests

Search the interest-targeting taxonomy by free text.
​
adAccountId
string
required
​
query
string
required
Free-text interest query, e.g. running shoes.
​
limit
integer
default:"100"
Returns: id, name, type, audience size bounds, path (breadcrumb), topic.

​
Read tools: account audit

​
list_account_activities

Account change log: budget edits, status flips, targeting changes.
​
adAccountId
string
required
​
since
string (YYYY-MM-DD)
Only events on or after this date.
​
until
string (YYYY-MM-DD)
Only events on or before this date.
​
limit
integer
default:"100"
Returns: event_type, translated_event_type, event_time, object_id, object_name, actor_id, actor_name, extra_data.

​
list_automated_rules

Automated ad rules: triggers, filters, scheduled action (pause/scale/etc.). Shows what automation is running and what it would do.
​
adAccountId
string
required
​
limit
integer
default:"100"
Returns: id, name, status, evaluation_spec, execution_spec, schedule_spec, created_by.

​
Read tools: leads & pages

Lead field_data carries personal data (name, email, phone). The platform is read-through only: leads are fetched on demand and returned to your AI assistant; they are never persisted by Consile.

​
list_pages

List the Facebook Pages the connected user manages. The first call for the leads workflow: lead forms live on a Page.
​
limit
integer
default:"100"
Returns: id, name, category, tasks.

​
list_lead_forms

List the Lead-Ads forms on a Page.
​
pageId
string
required
A Page id (from list_pages).
​
limit
integer
default:"100"
Returns: id, name, status, locale, created_time, leads_count.

​
list_leads

Read the leads captured by a lead form.
​
formId
string
required
A lead form id (from list_lead_forms).
​
limit
integer
default:"100"
Returns: id, created_time, ad_id, adset_id, campaign_id, form_id, platform, field_data (submitted answers; may contain personal data).

​
get_lead

Read one lead by id.
​
leadId
string
required
A lead id (from list_leads).
Returns: Same fields as list_leads for the single record.

​
Read tools: advanced / escape hatch

​
query

Advanced read: GET any Graph node or edge with a safelisted set of read parameters. Read-only by construction (GET-only). For the long tail not covered by a dedicated tool.
​
path
string
required
A bare Graph path, e.g. act_1234567890/campaigns or 23847239847. No scheme, no .., no query string.
​
params
object
Read params; only safelisted keys are forwarded (all others are dropped). Allowed keys: fields, time_range, date_preset, level, breakdowns, action_breakdowns, filtering, time_increment, limit, after, sort, effective_status.

​
Write tools (5 guardrailed)

Write tools call the Meta Marketing API. New objects are created PAUSED and never spend until you activate them. Any action that changes spend (→ACTIVE), changes a budget, or archives requires confirm: true. Without it the tool returns a WritePreview and calls no API. See Handlinger & guardrails.

​
create_campaign

Create a new campaign. Created PAUSED by default.
​
adAccountId
string
required
​
name
string
required
Campaign name.
​
objective
string
required
Campaign objective (ODAX). One of: OUTCOME_TRAFFIC, OUTCOME_AWARENESS, OUTCOME_ENGAGEMENT, OUTCOME_LEADS, OUTCOME_SALES, OUTCOME_APP_PROMOTION.
​
status
string
default:"PAUSED"
Initial status. ACTIVE requires confirm: true.
​
specialAdCategories
string[]
default:"[]"
Special ad categories, e.g. HOUSING, EMPLOYMENT, CREDIT, ISSUES_ELECTIONS_POLITICS. Pass [] if none.
​
confirm
boolean
Set true to apply when status is ACTIVE (starts spend) or ARCHIVED. Omit or false to receive a WritePreview.
Requires confirmation: only when status is ACTIVE or ARCHIVED.

​
create_ad_set

Create an ad set under a campaign. Created PAUSED by default.
​
adAccountId
string
required
​
campaignId
string
required
Parent campaign id (bare digits).
​
name
string
required
​
dailyBudgetMinor
integer
Daily budget in minor units (e.g. 5000 = 50.00). Provide daily OR lifetime.
​
lifetimeBudgetMinor
integer
Lifetime budget in minor units.
​
billingEvent
string
required
e.g. IMPRESSIONS, LINK_CLICKS, THRUPLAY, POST_ENGAGEMENT.
​
optimizationGoal
string
required
e.g. LINK_CLICKS, LANDING_PAGE_VIEWS, OFFSITE_CONVERSIONS, REACH, THRUPLAY.
​
targeting
string
required
Meta targeting_spec as a JSON string, e.g. '{"geo_locations":{"countries":["DK"]}}'.
​
bidAmountMinor
integer
Bid cap in minor units (optional).
​
startTime
string
ISO 8601 start time (optional).
​
endTime
string
ISO 8601 end time (optional).
​
status
string
default:"PAUSED"
Initial status. ACTIVE requires confirm: true.
​
confirm
boolean
Requires confirmation: when status is ACTIVE or ARCHIVED.

​
create_ad

Create an ad under an ad set from an existing creative. Created PAUSED by default.
​
adAccountId
string
required
​
adSetId
string
required
Parent ad set id (bare digits).
​
name
string
required
​
creativeId
string
required
An existing ad creative id (from list_creatives). Building creatives from scratch (image/video upload) is not supported by this connector.
​
status
string
default:"PAUSED"
Initial status. ACTIVE requires confirm: true.
​
confirm
boolean
Requires confirmation: when status is ACTIVE or ARCHIVED.

​
update_status

Set a campaign, ad set, or ad to PAUSED, ACTIVE, or ARCHIVED.
​
objectId
string
required
A campaign, ad set, or ad id (bare digits).
​
status
string
required
Target status: ACTIVE, PAUSED, or ARCHIVED.
​
confirm
boolean
Requires confirmation: ACTIVE (spend starts) and ARCHIVED (permanent disable). Pausing (PAUSED) is immediately safe (no confirmation needed).

​
update_budget

Change the daily or lifetime budget of a campaign or ad set. Always requires confirmation (it changes spend).
​
objectId
string
required
A campaign or ad set id (bare digits).
​
dailyBudgetMinor
integer
New daily budget in minor units. Provide daily OR lifetime.
​
lifetimeBudgetMinor
integer
New lifetime budget in minor units.
​
confirm
boolean
required
Must be true to apply. Omit to receive a WritePreview.
Always requires confirmation.

​
Code examples

{
  "name": "meta-ads__list_campaigns",
  "arguments": {
    "adAccountId": "act_1234567890",
    "effectiveStatus": ["ACTIVE"],
    "limit": 50
  }
}
Tool names are namespaced meta-ads__<tool> in Claude/ChatGPT (the AI invokes these automatically). The bare names (e.g. list_campaigns) are used here for readability.
An expired or revoked access token returns AccessTokenExpiredError (“Meta access token has expired; reconnect required”). Reconnect via the portal to issue a new long-lived token. See Errors & limits.