Skip to main content
Glama
Meta Ads MCP Server

Meta Ads MCP Server

by hashcott

Meta Ads MCP Server

Disclaimer: This is an unofficial third-party tool and is not associated with, endorsed by, or affiliated with Meta in any way. This project is maintained independently and uses Meta's public APIs in accordance with their Terms of Service. Meta, Facebook, Instagram, and other Meta brand names are trademarks of their respective owners.


Table of Contents


Related MCP server: ArmaVita Meta Ads MCP

Features

Category

What it does

Accounts

List ad accounts, get account details

Campaigns

Get / list / create / update / pause / resume / delete

Ad Sets

Get / list / batch-fetch / create / update / pause / resume / delete

Ads

Get / list / create / update / pause / resume / delete

Creatives

Get / list, create + update, compute image crops

Media

List ad images, upload images, lookup by hash, get ad previews and videos

Insights

Performance analytics at account, campaign, ad set, and ad level

Targeting

Search interests / behaviors / demographics / geo, audience size estimation

Pages

List Facebook Pages reachable from the token, search by name

Budget Schedules

Schedule temporary budget bumps over a time window

Activities

Change history log for ad accounts and ad sets

Pagination

Utility tool to fetch subsequent pages of results

All mutation tools (create / update / delete / pause / resume / upload / budget schedule) are off by default and only register when you opt in — see Enabling Write Tools.


Requirements

  • Node.js >= 18

  • A Meta User Access Token with the right permissions for what you plan to do — see below.


Installation

# From npm
npx meta-ads-mcp-server --access-token YOUR_META_ACCESS_TOKEN

# From source
git clone https://github.com/hashcott/meta-ads-mcp.git
cd meta-ads-mcp
npm install
npm run build
node dist/index.js --access-token YOUR_META_ACCESS_TOKEN

Obtaining a Meta Access Token

This server uses the Meta Marketing API. You need an access token attached to a Meta App that has the right permissions.

Quick option — Graph API Explorer (read-only experiments)

  1. Open the Graph API Explorer.

  2. Pick your Meta App from the top-right dropdown (create one at developers.facebook.com/apps if you don't have any — choose type "Business").

  3. Click Generate Access Token, then under Permissions add at minimum:

    • ads_read — for all the read tools.

    • ads_management — required for any write tool (create / update / delete / pause / resume / upload / budget schedule).

    • business_management — recommended if you operate via Business Manager.

    • pages_show_list, pages_read_engagement — required for the Pages tools.

  4. Copy the generated token. This is a short-lived token (~1 hour) — fine for testing.

Production option — long-lived User token

Short-lived tokens from the Explorer expire in about an hour. Exchange yours for a 60-day token:

curl -G "https://graph.facebook.com/v22.0/oauth/access_token" \
  --data-urlencode "grant_type=fb_exchange_token" \
  --data-urlencode "client_id=YOUR_APP_ID" \
  --data-urlencode "client_secret=YOUR_APP_SECRET" \
  --data-urlencode "fb_exchange_token=YOUR_SHORT_LIVED_TOKEN"

Response contains "access_token": "..." — that token is valid for ~60 days. Refresh it the same way before it expires, or build a full OAuth flow if you need permanent access.

For unattended production use (no expiry), generate a System User token in Business Manager:

  1. Go to Business Manager → Business Settings → Users → System Users.

  2. Create a system user (or use an existing one), assign the relevant ad account, and grant ads_read / ads_management.

  3. Click Generate New Token → pick your Meta App → select the same permissions → Never for expiration.

System User tokens don't expire and are ideal for backend deployments.

Verifying your token

curl "https://graph.facebook.com/v22.0/me?access_token=YOUR_TOKEN"

Should return your user/system-user object. If it returns an error, double-check the permissions and that the token isn't expired.


Authentication

Pass your Meta access token using either method:

CLI argument (recommended for Cursor / Claude Desktop):

node dist/index.js --access-token YOUR_META_ACCESS_TOKEN

Environment variable:

export META_ADS_ACCESS_TOKEN=YOUR_META_ACCESS_TOKEN
node dist/index.js

The token is held only in memory of the running process — it is never written to disk by this server.


Enabling Write Tools

By default the server registers only the 35 read tools — create / update / delete / pause / resume / upload / budget-schedule tools are not exposed. This is intentional: a mistakenly-issued meta_ads_delete_campaign can permanently remove campaigns and their ads.

To opt in, set:

META_ADS_ENABLE_WRITE_TOOLS=true

Accepted truthy values: true, 1, yes, on (case-insensitive). Anything else (or unset) keeps writes off.

When enabled, the server logs a one-line warning to stderr at startup:

[meta-ads-mcp] WARNING: META_ADS_ENABLE_WRITE_TOOLS is on — create/update/delete/pause/resume tools are EXPOSED. These can permanently delete campaigns/ad sets/ads or change live delivery.

Your access token also needs the ads_management permission for the writes to succeed.

Example Cursor / Claude Desktop configuration with writes enabled:

{
  "mcpServers": {
    "meta-ads": {
      "command": "npx",
      "args": ["-y", "meta-ads-mcp-server"],
      "env": {
        "META_ADS_ACCESS_TOKEN": "YOUR_META_ACCESS_TOKEN",
        "META_ADS_ENABLE_WRITE_TOOLS": "true"
      }
    }
  }
}

Transport Modes

Mode

Use case

How to enable

stdio (default)

Cursor, Claude Desktop, local tools

No configuration needed

http

Claude.ai remote connectors, multi-client setups

Set TRANSPORT=http


Cursor / Claude Desktop Setup

Add one of the following to your MCP client configuration file:

Via npx (recommended — no local install required):

{
  "mcpServers": {
    "meta-ads": {
      "command": "npx",
      "args": ["-y", "meta-ads-mcp-server", "--access-token", "YOUR_META_ACCESS_TOKEN"]
    }
  }
}

Via local build:

{
  "mcpServers": {
    "meta-ads": {
      "command": "node",
      "args": ["/path/to/meta-ads-mcp/dist/index.js", "--access-token", "YOUR_META_ACCESS_TOKEN"]
    }
  }
}

Via environment variable (and opt-in writes):

{
  "mcpServers": {
    "meta-ads": {
      "command": "npx",
      "args": ["-y", "meta-ads-mcp-server"],
      "env": {
        "META_ADS_ACCESS_TOKEN": "YOUR_META_ACCESS_TOKEN",
        "META_ADS_ENABLE_WRITE_TOOLS": "true"
      }
    }
  }
}

Remote HTTP Server

Run as a persistent HTTP server for use with Claude.ai custom connectors or any remote MCP client.

# Start on default port 3000
TRANSPORT=http META_ADS_ACCESS_TOKEN=YOUR_TOKEN node dist/index.js

# Start on a custom port, writes enabled
TRANSPORT=http \
  META_ADS_ACCESS_TOKEN=YOUR_TOKEN \
  META_ADS_ENABLE_WRITE_TOOLS=true \
  PORT=8080 \
  node dist/index.js

Endpoints:

  • POST /mcp — MCP protocol endpoint

  • GET /health — Health check ({"status":"ok"})

Adding to Claude.ai

  1. Go to Settings → Connectors → Add custom connector

  2. Enter your server URL: https://your-domain.com/mcp

  3. Click Add

Local testing with ngrok

# Terminal 1 — start the server
TRANSPORT=http META_ADS_ACCESS_TOKEN=YOUR_TOKEN PORT=8080 node dist/index.js

# Terminal 2 — expose publicly
ngrok http 8080

Use the generated HTTPS URL (e.g. https://xxxx.ngrok-free.app/mcp) as your connector URL.

Deploying to cloud platforms

Set the following environment variables on your hosting provider (Railway, Render, Fly.io, etc.):

Variable

Value

TRANSPORT

http

META_ADS_ACCESS_TOKEN

Your Meta access token

META_ADS_ENABLE_WRITE_TOOLS

true to also expose mutating tools (off by default)

PORT

Assigned automatically by the platform


Available Tools

Legend: 🔍 read • ✏️ write (gated by META_ADS_ENABLE_WRITE_TOOLS) • 🛠️ pure utility (no API call).

Accounts

Tool

Type

Description

meta_ads_list_ad_accounts

🔍

List all ad accounts accessible with your token

meta_ads_get_ad_account_details

🔍

Get detailed information for a specific ad account

Campaigns

Tool

Type

Description

meta_ads_get_campaign_by_id

🔍

Fetch a specific campaign by its ID

meta_ads_get_campaigns_by_adaccount

🔍

List campaigns within an ad account, with filters and pagination

meta_ads_create_campaign

✏️

Create a new ODAX campaign (CBO or ABO)

meta_ads_update_campaign

✏️

Update name/status/budget/bid; supports CBO → ABO migration via adset_budgets

meta_ads_delete_campaign

✏️

Permanently delete a campaign and its ad sets/ads

meta_ads_pause_campaign

✏️

Convenience: set status to PAUSED

meta_ads_resume_campaign

✏️

Convenience: set status to ACTIVE

meta_ads_create_campaign inputs:

  • act_id (string) — Ad account ID, format act_XXXXXXXXX.

  • name (string) — Campaign name.

  • objective (enum) — ODAX outcome-based objective:

    • OUTCOME_AWARENESS, OUTCOME_TRAFFIC, OUTCOME_ENGAGEMENT, OUTCOME_LEADS, OUTCOME_SALES, OUTCOME_APP_PROMOTION.

    • Legacy objectives (BRAND_AWARENESS, LINK_CLICKS, CONVERSIONS, APP_INSTALLS, …) are not accepted by Meta v22+ and will return HTTP 400.

  • status (default PAUSED), special_ad_categories (default [])

  • daily_budget / lifetime_budget (cents) — omit both when use_adset_level_budgets=true.

  • bid_strategy — LOWEST_COST_WITHOUT_CAP (default), LOWEST_COST_WITH_BID_CAP, COST_CAP, LOWEST_COST_WITH_MIN_ROAS. Bid-cap strategies require bid_amount on every child ad set.

  • bid_cap, spend_cap, campaign_budget_optimization, use_adset_level_budgets, ab_test_control_setups, buying_type.

{
  "act_id": "act_123456789012345",
  "name": "2026 - Spring Sale - Awareness",
  "objective": "OUTCOME_AWARENESS",
  "special_ad_categories": [],
  "status": "PAUSED",
  "bid_strategy": "LOWEST_COST_WITHOUT_CAP",
  "daily_budget": 10000
}

Ad Sets

Tool

Type

Description

meta_ads_get_adset_by_id

🔍

Fetch a single ad set by its ID

meta_ads_get_adsets_by_ids

🔍

Batch fetch multiple ad sets

meta_ads_get_adsets_by_adaccount

🔍

List ad sets in an ad account

meta_ads_get_adsets_by_campaign

🔍

List ad sets within a campaign

meta_ads_create_adset

✏️

Create a new ad set under a campaign

meta_ads_update_adset

✏️

Update an ad set's fields (note: frequency_control_specs is immutable after creation)

meta_ads_delete_adset

✏️

Permanently delete an ad set

meta_ads_pause_adset

✏️

Set status to PAUSED

meta_ads_resume_adset

✏️

Set status to ACTIVE

meta_ads_create_adset highlights:

  • Required: act_id, campaign_id, name, optimization_goal, billing_event.

  • targeting (object) — full targeting spec; remember targeting_automation.advantage_audience defaults to 0 on Meta v24+ — set it explicitly if you want Advantage+ Audience.

  • bid_amount — required for LOWEST_COST_WITH_BID_CAP / COST_CAP.

  • bid_constraints — required for LOWEST_COST_WITH_MIN_ROAS, e.g., {"roas_average_floor": 20000} for a 2.0× ROAS floor.

  • dsa_beneficiary / dsa_payor — required for EU-targeted ad sets.

  • promoted_object — required for APP_INSTALLS.

  • frequency_control_specs — MUST be set at creation; Meta makes it immutable afterward.

  • regional_regulated_categories / regional_regulation_identities — Taiwan / Australia / Singapore / India regulated verticals.

Ads

Tool

Type

Description

meta_ads_get_ad_by_id

🔍

Fetch a single ad by ID

meta_ads_get_ads_by_adaccount

🔍

List ads in an ad account

meta_ads_get_ads_by_campaign

🔍

List ads within a campaign

meta_ads_get_ads_by_adset

🔍

List ads within an ad set

meta_ads_create_ad

✏️

Create a new ad referencing an existing creative

meta_ads_update_ad

✏️

Update name / status / bid / tracking specs / creative reference

meta_ads_delete_ad

✏️

Permanently delete an ad

meta_ads_pause_ad

✏️

Set status to PAUSED

meta_ads_resume_ad

✏️

Set status to ACTIVE

ℹ️ Swapping creative_id on a FLEX ad can fail with error_subcode 3858355 if the new creative's asset_feed_spec images don't match its object_story_spec. In that case, create a new ad with the new creative and pause the old one (you lose social proof but the ad runs).

Creatives

Tool

Type

Description

meta_ads_get_ad_creative_by_id

🔍

Fetch one creative

meta_ads_get_ad_creatives_by_ad_id

🔍

List creatives attached to an ad

meta_ads_get_adcreatives_by_adaccount

🔍

List creatives in an ad account

meta_ads_compute_image_crops

🛠️

Compute centered crop boxes for the 6 Meta-accepted aspect ratios (no API call)

meta_ads_create_ad_creative

✏️

Create a creative — 3 simple modes plus full object_story_spec escape hatch

meta_ads_update_ad_creative

✏️

Update name / asset_feed_spec (Meta restricts most other content updates)

meta_ads_create_ad_creative — three common modes:

  1. Promote an existing post: pass only object_story_id in the form {page_id}_{post_id}.

  2. Single-image link ad: page_id + image_hash + link_url + message + optional headline, description, call_to_action_type.

  3. Single-video ad: page_id + video_id + link_url + message + optional headline, call_to_action_type, thumbnail_url.

For advanced layouts (FLEX/DOF, Placement Asset Customization, Dynamic Creative, multi-headline, lead-gen forms, branded content, image crops), pass a fully composed object_story_spec and/or asset_feed_spec — those take precedence over the simple-mode auto-construction.

Media

Tool

Type

Description

meta_ads_get_ad_images

🔍

List image assets in an ad account

meta_ads_get_image_by_hash

🔍

Single-image lookup by hash (URL + dimensions)

meta_ads_get_ad_previews

🔍

Generate rendered previews of an ad across placements

meta_ads_get_ad_video

🔍

Video details (source URL, thumbnails, length) by ad_id or video_id

meta_ads_upload_ad_image

✏️

Upload an image to an account's ad images library and get back its image_hash

meta_ads_upload_ad_image accepts exactly one of:

  • file — a data URL (data:image/png;base64,iVBORw0KG...) or a raw base64 string.

  • image_url — a public URL; the server downloads the bytes and uploads them.

Returns the image_hash you then pass to meta_ads_create_ad_creative.

Insights

Tool

Type

Description

meta_ads_get_adaccount_insights

🔍

Performance metrics at the account level

meta_ads_get_campaign_insights

🔍

Performance metrics for a specific campaign

meta_ads_get_adset_insights

🔍

Performance metrics for a specific ad set

meta_ads_get_ad_insights

🔍

Performance metrics for a specific ad

All four accept the same option surface: fields, date_preset, time_range, time_ranges, time_increment, level, action_attribution_windows, action_breakdowns, breakdowns, filtering, sort, pagination, and locale.

Time-range precedence: time_ranges > time_range > since/until > date_preset.

Targeting Catalog

Tool

Type

Description

meta_ads_search_interests

🔍

Search Meta's interest catalog by keyword

meta_ads_get_interest_suggestions

🔍

Get related interests from a seed list

meta_ads_search_behaviors

🔍

List available behavior targeting options

meta_ads_search_demographics

🔍

List demographic options (demographics / life_events / industries / income / family_statuses / user_device / user_os)

meta_ads_search_geo_locations

🔍

Search countries / regions / cities / zips / geo_markets / electoral_districts

meta_ads_estimate_audience_size

🔍

Estimate reach for a targeting spec via /act_X/delivery_estimate

Pages

Tool

Type

Description

meta_ads_get_account_pages

🔍

List Facebook Pages reachable from the access token (/me/accounts)

meta_ads_search_pages_by_name

🔍

Substring filter over the token's pages (client-side — Meta does not expose a server-side name filter)

The returned page_id values are the ones you pass to meta_ads_create_ad_creative.

Budget Schedules

Tool

Type

Description

meta_ads_create_budget_schedule

✏️

Schedule a temporary budget bump for a campaign over a Unix-timestamp window

Inputs:

  • campaign_id (string)

  • budget_value (int, positive)

  • budget_value_type — ABSOLUTE (cents in account currency) or MULTIPLIER (e.g., 2 doubles the budget)

  • time_start, time_end (Unix timestamps in seconds) — time_end > time_start

Activities

Tool

Type

Description

meta_ads_get_activities_by_adaccount

🔍

Retrieve the change history log for an ad account

meta_ads_get_activities_by_adset

🔍

Retrieve the change history log for an ad set

Pagination tool

Tool

Type

Description

meta_ads_fetch_pagination_url

🛠️

Follow paging.next / paging.previous URLs from any other tool's response


End-to-End: Create an Ad from Scratch

A typical "build a new ad" workflow uses tools across several categories. With META_ADS_ENABLE_WRITE_TOOLS=true:

1. meta_ads_list_ad_accounts                       → pick an act_id
2. meta_ads_get_account_pages                      → pick a page_id
3. meta_ads_search_geo_locations(q="Vietnam")      → grab the country/region keys
4. meta_ads_search_interests(q="cooking")          → grab interest IDs
5. meta_ads_estimate_audience_size(act_id, targeting)  → sanity-check reach
6. meta_ads_upload_ad_image(act_id, image_url)     → returns image_hash
7. meta_ads_create_campaign(act_id, ...)           → returns campaign_id
8. meta_ads_create_adset(act_id, campaign_id, targeting, ...)  → returns adset_id
9. meta_ads_create_ad_creative(act_id, page_id, image_hash, link_url, message, ...)  → returns creative_id
10. meta_ads_create_ad(act_id, name, adset_id, creative_id, status="PAUSED")  → returns ad_id
11. (Optional) meta_ads_get_ad_previews(ad_id, ...)  → render placements before going live
12. meta_ads_resume_ad(ad_id)                       → flip to ACTIVE when ready

All steps that mutate state default to status: "PAUSED" so nothing goes live until you explicitly call a resume tool.


Pagination

Many list tools return paginated results. When a response contains a paging.next URL, use meta_ads_fetch_pagination_url to retrieve subsequent pages:

1. Call meta_ads_get_campaigns_by_adaccount  →  receive first page
2. Check if response.paging.next exists
3. Call meta_ads_fetch_pagination_url(url=response.paging.next)  →  receive next page
4. Repeat until paging.next is absent

Development

npm run dev              # Watch mode — auto-recompile on change
npm run build            # Compile TypeScript to dist/
npm run clean            # Remove dist/
npm run clean && npm run build   # Full rebuild from scratch

Quick smoke test:

# Default (read-only)
META_ADS_ACCESS_TOKEN=dummy node dist/index.js
# → "Meta Ads MCP server running via stdio"

# With writes enabled
META_ADS_ACCESS_TOKEN=dummy META_ADS_ENABLE_WRITE_TOOLS=true node dist/index.js
# → WARNING line + "Meta Ads MCP server running via stdio"

Project Structure

meta-ads-mcp/
├── src/
│   ├── index.ts                  # Entry point, server setup, transport selection, write-tools warning
│   ├── constants.ts              # API version, base URLs, isWriteToolsEnabled() flag
│   ├── types.ts                  # Shared TypeScript interfaces
│   ├── services/
│   │   └── graph-api.ts          # HTTP client (GET/POST/DELETE), auth, error handling, param builders
│   ├── schemas/
│   │   ├── common.ts             # Shared Zod schemas (pagination, date ranges, filters)
│   │   └── insights.ts           # Insights-specific Zod schemas
│   └── tools/
│       ├── accounts.ts           # Account tools
│       ├── insights.ts           # Insights tools (account/campaign/adset/ad level)
│       ├── campaigns.ts          # Campaign read + write/lifecycle tools
│       ├── adsets.ts             # Ad set read + write/lifecycle tools
│       ├── ads.ts                # Ad read + write/lifecycle tools
│       ├── creatives.ts          # Creative read tools, image crops utility, create/update creative
│       ├── media.ts              # Image list / upload / hash lookup / video / preview
│       ├── activities.ts         # Activity log tools
│       ├── pagination.ts         # Pagination utility tool
│       ├── targeting.ts          # Interest/behavior/demographic/geo search + audience-size estimate
│       ├── pages.ts              # Facebook Pages list and name search
│       └── budget-schedules.ts   # Campaign budget schedule create
├── dist/                         # Compiled JavaScript output (generated)
├── package.json
└── tsconfig.json

License

MIT © hashcott

Available Tools

35 tools
meta_ads_compute_image_cropsCompute Meta Ad Image CropsA
Read-onlyIdempotent

Compute image_crops coordinates for a source image. For each requested key, returns the largest centered region that fits the source while matching that key's aspect ratio (equivalent to Meta's "Original" crop — no content cut beyond the ratio).

Valid keys (Meta accepts only these 6): 100x100 — 1:1 square (Feed, Marketplace) 100x72 — ~1.39:1 horizontal (Marketplace) 400x500 — 4:5 portrait (Feed mobile, Stories fallback) 400x150 — ~2.67:1 banner (Audience Network) 600x360 — ~1.67:1 horizontal (Right column) 90x160 — 9:16 portrait (Stories)

Pass the returned image_crops dict to meta_ads_create_ad_creative.

Inputs: image_width (required), image_height (required), crop_keys.

meta_ads_estimate_audience_sizeEstimate Meta Ad Audience SizeA
Read-onlyIdempotent

Estimate audience size for a targeting spec using Meta's delivery_estimate / reachestimate endpoints.

Args:

  • act_id (string): Ad account ID prefixed with 'act_'.

  • targeting (object): Full targeting spec (geo_locations, age_min, age_max, interests, flexible_spec, etc.).

  • optimization_goal (string, optional): Default 'REACH'. Other common values: LINK_CLICKS, LANDING_PAGE_VIEWS, OFFSITE_CONVERSIONS, IMPRESSIONS.

Returns: Estimated audience size bounds plus the raw API response.

Inputs: act_id (required), targeting (required), optimization_goal.

meta_ads_fetch_pagination_urlFetch Meta Ads Pagination URLA
Read-onlyIdempotent

Fetch the next or previous page of results from a Meta Graph API pagination URL.

Use this tool whenever a Meta Ads tool response contains a paging.next or paging.previous URL. The pagination URL already includes the access token and all necessary parameters.

Args:

  • url (string): The complete pagination URL from response.paging.next or response.paging.previous

Returns: The next/previous page of results in the same format as the original response.

Examples:

  • Use when: response.paging.next exists after calling meta_ads_get_adaccount_insights

  • Use when: response.paging.next exists after calling meta_ads_get_campaigns_by_adaccount

  • Use when: "Get all pages of results automatically"

Note: The pagination URL already contains the access token — do NOT add or modify it.

Inputs: url (required).

meta_ads_get_account_pagesGet Meta Account PagesA
Read-onlyIdempotent

List Facebook Pages reachable from the access token's user. These are the candidate page_id values for create_ad_creative.

Args:

  • act_id (string, optional): Reserved for parity with the Python reference; Meta returns pages bound to the user/token, not the ad account, so this is currently unused.

Returns: { data: [{ id, name, username, category, fan_count, link, verification_status, picture }] }

Inputs: act_id.

meta_ads_get_activities_by_adaccountGet Meta Ad Account Activity LogA
Read-onlyIdempotent

Retrieve the change history (activity log) for a Meta ad account.

Returns key updates to the account and associated ad objects, including status changes, budget updates, targeting changes, and more. By default returns one week of data.

Args:

  • act_id (string): Ad account ID prefixed with 'act_', e.g., 'act_1234567890'

  • fields (string[]): Fields to retrieve. Available: actor_id, actor_name, application_id, application_name, changed_data, date_time_in_timezone, event_time, event_type, extra_data, object_id, object_name, object_type, translated_event_type

  • limit (number): Maximum activities per page

  • after / before (string): Pagination cursors

  • time_range (object): Custom range {'since':'YYYY-MM-DD','until':'YYYY-MM-DD'}. Overrides since/until

  • since (string): Start date in YYYY-MM-DD format (ignored if time_range is set)

  • until (string): End date in YYYY-MM-DD format (ignored if time_range is set)

Returns: Object with data (activity array) and paging. Each activity record contains who made the change, what was changed, when, and the specific details.

  • actor_name (string): Name of the user who made the change

  • object_type (string): Type of object: AD, ADSET, CAMPAIGN, ACCOUNT, IMAGE, REPORT, etc.

  • translated_event_type (string): Human-readable description, e.g., 'ad created', 'campaign budget updated'

  • event_time (string): Timestamp of the event

  • changed_data (string): JSON detailing what changed

Use meta_ads_fetch_pagination_url with paging.next to retrieve additional pages.

Examples:

  • Use when: "Show me all changes made to my ad account in the last week"

  • Use when: "Who changed the budget on this account in January 2024?"

Inputs: act_id (required), fields, time_range, since, +5 more.

meta_ads_get_activities_by_adsetGet Meta Ad Set Activity LogA
Read-onlyIdempotent

Retrieve the change history (activity log) for a specific Meta ad set.

Returns updates to the ad set including status changes, budget updates, targeting changes, and more. By default returns one week of data.

Args:

  • adset_id (string): Ad set ID, e.g., '23843211234567'

  • fields (string[]): Fields to retrieve. Available: actor_id, actor_name, application_id, application_name, changed_data, date_time_in_timezone, event_time, event_type, extra_data, object_id, object_name, object_type, translated_event_type

  • limit (number): Maximum activities per page

  • after / before (string): Pagination cursors

  • time_range (object): Custom range {'since':'YYYY-MM-DD','until':'YYYY-MM-DD'}. Overrides since/until

  • since (string): Start date in YYYY-MM-DD format (ignored if time_range is set)

  • until (string): End date in YYYY-MM-DD format (ignored if time_range is set)

Returns: Object with data (activity array) and paging. Each activity record contains who made the change, what was changed, when, and the specific details.

  • actor_name (string): Name of the user who made the change

  • object_type (string): Type of object: AD, ADSET, CAMPAIGN, ACCOUNT, IMAGE, REPORT, etc.

  • translated_event_type (string): Human-readable description, e.g., 'ad created', 'campaign budget updated'

  • event_time (string): Timestamp of the event

  • changed_data (string): JSON detailing what changed

Use meta_ads_fetch_pagination_url with paging.next to retrieve additional pages.

Examples:

  • Use when: "What changes were made to ad set 23843211234567 this month?"

  • Use when: "Show me the targeting change history for this ad set"

Inputs: adset_id (required), fields, time_range, since, +5 more.

meta_ads_get_ad_account_detailsGet Meta Ad Account DetailsA
Read-onlyIdempotent

Get detailed information about a specific Meta ad account.

Args:

  • act_id (string): The ad account ID prefixed with 'act_', e.g., 'act_1234567890'

  • fields (string[]): Optional. Fields to retrieve. If omitted, defaults to: name, business_name, age, account_status, balance, amount_spent, attribution_spec, account_id, business, business_city, brand_safety_content_filter_levels, currency, created_time, id.

Returns: Object with the requested ad account fields. Key fields:

  • id (string): Ad account ID

  • name (string): Account display name

  • account_status (number): Status code (1=ACTIVE, 2=DISABLED, 3=UNSETTLED, etc.)

  • currency (string): Account currency code (e.g., 'USD')

  • balance (string): Current account balance

  • amount_spent (string): Total lifetime spend

Examples:

  • Use when: "Get details for ad account act_123456"

  • Use when: "What is the currency and balance of my ad account?"

Inputs: act_id (required), fields.

meta_ads_get_adaccount_insightsGet Meta Ad Account InsightsB
Read-onlyIdempotent

Retrieve performance insights for a Meta ad account.

Fetches metrics like impressions, reach, clicks, spend, conversions, and more for an entire ad account. Supports time range definitions, demographic breakdowns, and attribution settings.

Args:

  • act_id (string): Ad account ID prefixed with 'act_', e.g., 'act_1234567890'

  • fields (string[]): Metrics to retrieve. Common: impressions, reach, clicks, spend, ctr, cpc, cpm, cpp, frequency, actions, conversions, cost_per_action_type

  • date_preset (string): Relative time range preset (default: last_30d)

  • time_range (object): Custom range {'since':'YYYY-MM-DD','until':'YYYY-MM-DD'}

  • level (string): Aggregation level: account, campaign, adset, ad (default: account)

  • breakdowns (string[]): Segment by: age, gender, country, impression_device, publisher_platform, etc.

  • See full parameter list in inputSchema

Returns: Object with:

  • data (array): List of insight records with requested metrics

  • paging (object): Pagination cursors. Use meta_ads_fetch_pagination_url with paging.next to get more results

Pagination note: When response contains paging.next, use meta_ads_fetch_pagination_url to retrieve additional pages automatically.

Inputs: act_id (required), fields, date_preset, time_range, +19 more.

meta_ads_get_ad_by_idGet Meta Ad by IDA
Read-onlyIdempotent

Retrieve detailed information about a specific Meta ad.

Args:

  • ad_id (string): Ad ID, e.g., '23843211234567'

  • fields (string[]): Fields per ad. Common: id, name, account_id, adset_id, campaign_id, status, effective_status, configured_status, creative, bid_amount, bid_type, created_time, updated_time, targeting, conversion_specs, recommendations, preview_shareable_link

Returns: Object with the requested ad fields.

Examples:

  • Use when: "Get details for ad 23843211234567"

  • Use when: "What creative and status does this ad have?"

Inputs: ad_id (required), fields.

meta_ads_get_ad_creative_by_idGet Meta Ad Creative by IDA
Read-onlyIdempotent

Retrieve detailed information about a specific Meta ad creative.

Args:

  • creative_id (string): Ad creative ID, e.g., '23842312323312'

  • fields (string[]): Fields to retrieve. Available: id, name, account_id, actor_id, adlabels, asset_feed_spec, authorization_category, body, call_to_action_type, effective_authorization_category, effective_instagram_media_id, effective_object_story_id, image_hash, image_url, instagram_permalink_url, instagram_story_id, instagram_user_id, link_url, object_id, object_story_id, object_story_spec, object_type, object_url, platform_customizations, product_set_id, status, template_url, thumbnail_url, title, url_tags, use_page_actor_override, video_id

  • thumbnail_width (number): Width of the thumbnail image in pixels (default: 64)

  • thumbnail_height (number): Height of the thumbnail image in pixels (default: 64)

Returns: Object with the requested creative fields.

Examples:

  • Use when: "Get the body text, title, and image URL for creative 23842312323312"

  • Use when: "What is the call-to-action type and status of this creative?"

  • Use when: "Get a larger thumbnail (300x200) for this creative"

Inputs: creative_id (required), fields, thumbnail_width, thumbnail_height.

meta_ads_get_adcreatives_by_adaccountGet Meta Ad Creatives by Ad AccountA
Read-onlyIdempotent

Retrieve all ad creatives belonging to a specific Meta ad account.

Useful for auditing all creative assets, finding creatives by status, or reviewing creative content across the account.

Args:

  • act_id (string): Ad account ID prefixed with 'act_', e.g., 'act_1234567890'

  • fields (string[]): Fields to retrieve. Available: id, name, account_id, actor_id, adlabels, asset_feed_spec, authorization_category, body, call_to_action_type, effective_authorization_category, effective_instagram_media_id, effective_object_story_id, image_hash, image_url, instagram_permalink_url, instagram_story_id, instagram_user_id, link_url, object_id, object_story_id, object_story_spec, object_type, object_url, platform_customizations, product_set_id, status, template_url, thumbnail_url, title, url_tags, use_page_actor_override, video_id

  • effective_status (string[]): Filter by status: ACTIVE, DELETED, IN_PROCESS, WITH_ISSUES

  • filtering (object[]): Additional filter objects with field, operator, value

  • limit (number): Results per page (1-100, default: 25)

  • after / before (string): Pagination cursors

Returns: Object with data (creative array) and paging. Use meta_ads_fetch_pagination_url with paging.next for more results.

Examples:

  • Use when: "List all active creatives in my ad account"

  • Use when: "Show all creatives with issues in act_123456"

Inputs: act_id (required), fields, effective_status, filtering, +4 more.

meta_ads_get_ad_creatives_by_ad_idGet Meta Ad Creatives by Ad IDA
Read-onlyIdempotent

Retrieve the ad creatives associated with a specific Meta ad.

Args:

  • ad_id (string): Ad ID to retrieve creatives for, e.g., '23843211234567'

  • fields (string[]): Fields to retrieve. Available: id, name, account_id, actor_id, adlabels, asset_feed_spec, authorization_category, body, call_to_action_type, effective_authorization_category, effective_instagram_media_id, effective_object_story_id, image_hash, image_url, instagram_permalink_url, instagram_story_id, instagram_user_id, link_url, object_id, object_story_id, object_story_spec, object_type, object_url, platform_customizations, product_set_id, status, template_url, thumbnail_url, title, url_tags, use_page_actor_override, video_id

  • limit (number): Maximum creatives per page (default: 25)

  • after / before (string): Pagination cursors from response.paging.cursors

  • date_format (string): Date format: 'U' for Unix timestamp, 'Y-m-d H:i:s' for MySQL datetime

Returns: Object with data (creative array) and paging. Use meta_ads_fetch_pagination_url with paging.next for more results.

Examples:

  • Use when: "What creatives are used by ad 23843211234567?"

  • Use when: "Get the image URLs and titles for all creatives on this ad"

Inputs: ad_id (required), fields, date_format, limit, +3 more.

meta_ads_get_ad_imagesGet Meta Ad ImagesA
Read-onlyIdempotent

Retrieve ad images belonging to a Meta ad account.

Useful for auditing image assets, finding images by hash or name, and checking image dimensions and status.

Args:

  • act_id (string): Ad account ID prefixed with 'act_', e.g., 'act_1234567890'

  • fields (string[]): Fields to retrieve. Available: id, account_id, created_time, creatives, hash, height, is_associated_creatives_in_adgroups, name, original_height, original_width, permalink_url, status, updated_time, url, url_128, width

  • hashes (string[]): Filter by specific image hashes

  • name (string): Filter images by name (partial match)

  • minwidth (number): Minimum image width in pixels

  • minheight (number): Minimum image height in pixels

  • limit (number): Results per page (1-100, default: 25)

  • after / before (string): Pagination cursors

Returns: Object with data (image array) and paging. Each image contains URL, dimensions, hash, and status. Use meta_ads_fetch_pagination_url with paging.next for more results.

Examples:

  • Use when: "List all images in my ad account"

  • Use when: "Find images with hashes abc123 and def456"

  • Use when: "Show images wider than 1000px"

Inputs: act_id (required), fields, hashes, name, +6 more.

meta_ads_get_ad_insightsGet Meta Ad InsightsA
Read-onlyIdempotent

Retrieve detailed performance insights for a specific Meta ad.

Fetches performance metrics for an individual ad, such as impressions, clicks, conversions, video views, etc.

Args:

  • ad_id (string): Ad ID, e.g., '6123456789012'

  • fields (string[]): Metrics to retrieve. Common: ad_name, adset_name, campaign_name, impressions, clicks, spend, ctr, cpc, cpm, reach, frequency, actions, conversions, cost_per_action_type, inline_link_clicks, video_p25_watched_actions

  • date_preset (string): Relative time range preset (default: last_30d)

  • time_range (object): Custom range {'since':'YYYY-MM-DD','until':'YYYY-MM-DD'}

  • level (string): Aggregation level, should be 'ad' (default: ad)

  • breakdowns (string[]): Segment by: age, gender, country, publisher_platform, impression_device, platform_position, device_platform, etc.

  • See full parameter list in inputSchema

Returns: Object with:

  • data (array): List of insight records with requested metrics

  • paging (object): Pagination cursors. Use meta_ads_fetch_pagination_url with paging.next to get more results

Pagination note: When response contains paging.next, use meta_ads_fetch_pagination_url to retrieve additional pages automatically.

Inputs: ad_id (required), fields, date_preset, time_range, +19 more.

meta_ads_get_ad_previewsGet Meta Ad PreviewsA
Read-onlyIdempotent

Generate preview links or embed HTML for a Meta ad in various ad formats and placements.

Allows you to see how an ad looks across different placements (Facebook feed, Instagram, Stories, etc.) before or after publishing.

Args:

  • ad_id (string): Ad ID to preview, e.g., '23843211234567'

  • ad_format (string): Preview format. Options: DESKTOP_FEED_STANDARD, MOBILE_FEED_STANDARD, MOBILE_FEED_BASIC, MOBILE_INTERSTITIAL, MOBILE_BANNER, MOBILE_MEDIUM_RECTANGLE, MOBILE_FULLWIDTH, RIGHT_COLUMN_STANDARD, INSTAGRAM_STANDARD, INSTAGRAM_STORY, AUDIENCE_NETWORK_OUTSTREAM_VIDEO, AUDIENCE_NETWORK_INSTREAM_VIDEO, FACEBOOK_STORY_MOBILE, MESSENGER_MOBILE_INBOX_MEDIA, SUGGESTED_VIDEO_MOBILE, WATCH_FEED_MOBILE, FACEBOOK_REELS_MOBILE, INSTAGRAM_REELS

  • locale (string): Locale for the preview, e.g., 'en_US'

  • start_date (string): Preview start date for scheduled ads (UNIX timestamp)

  • end_date (string): Preview end date for scheduled ads (UNIX timestamp)

Returns: Object with data array. Each item contains:

  • body (string): HTML iframe embed code for the preview

  • encoded_creative_id (string): Encoded creative ID

Examples:

  • Use when: "Show me how ad 23843211234567 looks on Instagram"

  • Use when: "Preview this ad in desktop feed format"

  • Use when: "Generate previews for all placements of this ad"

Inputs: ad_id (required), ad_format, locale, start_date, +1 more.

meta_ads_get_ads_by_adaccountGet Meta Ads by Ad AccountA
Read-onlyIdempotent

Retrieve all ads from a specific Meta ad account with filtering and pagination.

Args:

  • act_id (string): Ad account ID prefixed with 'act_', e.g., 'act_1234567890'

  • fields (string[]): Fields per ad. Common: id, name, account_id, adset_id, campaign_id, status, effective_status, configured_status, creative, bid_amount, bid_type, created_time, updated_time, targeting, conversion_specs, recommendations, preview_shareable_link

  • effective_status (string[]): Filter by status: ACTIVE, PAUSED, DELETED, PENDING_REVIEW, DISAPPROVED, PREAPPROVED, PENDING_BILLING_INFO, CAMPAIGN_PAUSED, ARCHIVED, ADSET_PAUSED, IN_PROCESS, WITH_ISSUES

  • filtering (object[]): Additional filter objects with field, operator, value

  • limit (number): Results per page (1-100, default: 25)

  • after / before (string): Pagination cursors

  • date_preset / time_range: Date filter

  • updated_since (number): Unix timestamp — return ads updated since this time

Returns: Object with data (ad array) and paging. Use meta_ads_fetch_pagination_url with paging.next for more results.

Inputs: act_id (required), fields, filtering, date_preset, +7 more.

meta_ads_get_ads_by_adsetGet Meta Ads by Ad SetA
Read-onlyIdempotent

Retrieve all ads belonging to a specific Meta ad set with filtering and pagination.

Args:

  • adset_id (string): Ad set ID, e.g., '23843211234567'

  • fields (string[]): Fields per ad. Common: id, name, account_id, adset_id, campaign_id, status, effective_status, configured_status, creative, bid_amount, bid_type, created_time, updated_time, targeting, conversion_specs, recommendations, preview_shareable_link

  • effective_status (string[]): Filter by status: ACTIVE, PAUSED, DELETED, PENDING_REVIEW, DISAPPROVED, PREAPPROVED, PENDING_BILLING_INFO, CAMPAIGN_PAUSED, ARCHIVED, IN_PROCESS, WITH_ISSUES

  • filtering (object[]): Filter objects. Operators: EQUAL, NOT_EQUAL, GREATER_THAN, GREATER_THAN_OR_EQUAL, LESS_THAN, LESS_THAN_OR_EQUAL, IN_RANGE, NOT_IN_RANGE, CONTAIN, NOT_CONTAIN, IN, NOT_IN, EMPTY, NOT_EMPTY

  • limit (number): Results per page (1-100, default: 25, max: 100)

  • after / before (string): Pagination cursors

  • date_format (string): Date format for response

Returns: Object with data (ad array) and paging. Use meta_ads_fetch_pagination_url with paging.next for more results.

Inputs: adset_id (required), fields, filtering, effective_status, +5 more.

meta_ads_get_ads_by_campaignGet Meta Ads by CampaignA
Read-onlyIdempotent

Retrieve all ads belonging to a specific Meta campaign with filtering and pagination.

Args:

  • campaign_id (string): Campaign ID, e.g., '23843xxxxx'

  • fields (string[]): Fields per ad. Common: id, name, account_id, adset_id, campaign_id, status, effective_status, configured_status, creative, bid_amount, bid_type, created_time, updated_time, targeting, conversion_specs, recommendations, preview_shareable_link

  • effective_status (string[]): Filter by status: ACTIVE, PAUSED, DELETED, PENDING_REVIEW, DISAPPROVED, PREAPPROVED, PENDING_BILLING_INFO, ADSET_PAUSED, ARCHIVED, IN_PROCESS, WITH_ISSUES

  • filtering (object[]): Additional filter objects with field, operator, value

  • limit (number): Results per page (1-100, default: 25)

  • after / before (string): Pagination cursors

Returns: Object with data (ad array) and paging. Use meta_ads_fetch_pagination_url with paging.next for more results.

Inputs: campaign_id (required), fields, filtering, effective_status, +4 more.

meta_ads_get_adset_by_idGet Meta Ad Set by IDA
Read-onlyIdempotent

Retrieve detailed information about a specific Meta ad set.

Args:

  • adset_id (string): Ad set ID, e.g., '23843211234567'

  • fields (string[]): Fields per ad set. Common: id, name, account_id, campaign_id, status, effective_status, daily_budget, lifetime_budget, budget_remaining, bid_amount, bid_strategy, billing_event, optimization_goal, targeting, start_time, end_time, created_time, updated_time, pacing_type, destination_type

Returns: Object with the requested ad set fields.

Examples:

  • Use when: "Get the targeting and budget for ad set 23843211234567"

  • Use when: "What is the optimization goal and status of this ad set?"

Inputs: adset_id (required), fields.

meta_ads_get_adset_insightsGet Meta Ad Set InsightsA
Read-onlyIdempotent

Retrieve performance insights for a specific Meta ad set.

Provides advertising statistics for an ad set, useful for analyzing performance across its child ads.

Args:

  • adset_id (string): Ad set ID, e.g., '6123456789012'

  • fields (string[]): Metrics to retrieve. Common: adset_name, campaign_name, impressions, clicks, spend, ctr, reach, actions, cpc, cpm, cpp, cost_per_action_type

  • date_preset (string): Relative time range preset (default: last_30d)

  • time_range (object): Custom range {'since':'YYYY-MM-DD','until':'YYYY-MM-DD'}

  • level (string): Aggregation level: adset, ad (default: adset)

  • breakdowns (string[]): Segment by: age, gender, country, publisher_platform, impression_device, platform_position, etc.

  • See full parameter list in inputSchema

Returns: Object with:

  • data (array): List of insight records with requested metrics

  • paging (object): Pagination cursors. Use meta_ads_fetch_pagination_url with paging.next to get more results

Pagination note: When response contains paging.next, use meta_ads_fetch_pagination_url to retrieve additional pages automatically.

Inputs: adset_id (required), fields, date_preset, time_range, +19 more.

meta_ads_get_adsets_by_adaccountGet Meta Ad Sets by Ad AccountA
Read-onlyIdempotent

Retrieve all ad sets from a specific Meta ad account with filtering and pagination.

Args:

  • act_id (string): Ad account ID prefixed with 'act_', e.g., 'act_1234567890'

  • fields (string[]): Fields per ad set. Common: id, name, account_id, campaign_id, status, effective_status, daily_budget, lifetime_budget, budget_remaining, bid_amount, bid_strategy, billing_event, optimization_goal, targeting, start_time, end_time, created_time, updated_time, pacing_type, destination_type

  • effective_status (string[]): Filter by status: ACTIVE, PAUSED, DELETED, PENDING_REVIEW, DISAPPROVED, PREAPPROVED, PENDING_BILLING_INFO, CAMPAIGN_PAUSED, ARCHIVED, WITH_ISSUES

  • filtering (object[]): Additional filter objects, e.g., [{field: 'daily_budget', operator: 'GREATER_THAN', value: 1000}]

  • limit (number): Results per page (1-100, default: 25)

  • after / before (string): Pagination cursors

  • date_preset / time_range: Date filter

  • updated_since (number): Unix timestamp — return ad sets updated since this time

  • date_format (string): Date format for response

Returns: Object with data (ad set array) and paging. Use meta_ads_fetch_pagination_url with paging.next for more results.

Inputs: act_id (required), fields, filtering, date_preset, +8 more.

meta_ads_get_adsets_by_campaignGet Meta Ad Sets by CampaignA
Read-onlyIdempotent

Retrieve all ad sets belonging to a specific Meta campaign with filtering and pagination.

Args:

  • campaign_id (string): Campaign ID, e.g., '23843xxxxx'

  • fields (string[]): Fields per ad set. Common: id, name, account_id, campaign_id, status, effective_status, daily_budget, lifetime_budget, budget_remaining, bid_amount, bid_strategy, billing_event, optimization_goal, targeting, start_time, end_time, created_time, updated_time, pacing_type, destination_type

  • effective_status (string[]): Filter by status: ACTIVE, PAUSED, DELETED, PENDING_REVIEW, DISAPPROVED, PREAPPROVED, PENDING_BILLING_INFO, ARCHIVED, WITH_ISSUES

  • filtering (object[]): Additional filter objects, e.g., [{field: 'optimization_goal', operator: 'IN', value: ['OFFSITE_CONVERSIONS', 'VALUE']}]

  • limit (number): Results per page (1-100, default: 25)

  • after / before (string): Pagination cursors

  • date_format (string): Date format for response

Returns: Object with data (ad set array) and paging. Use meta_ads_fetch_pagination_url with paging.next for more results.

Inputs: campaign_id (required), fields, filtering, effective_status, +5 more.

meta_ads_get_adsets_by_idsGet Multiple Meta Ad Sets by IDsA
Read-onlyIdempotent

Retrieve information for multiple Meta ad sets in a single API call (batch lookup).

Efficient when you need data for several ad sets at once.

Args:

  • adset_ids (string[]): List of ad set IDs to retrieve, e.g., ['23843211234567', '23843211234568']

  • fields (string[]): Fields per ad set. Common: id, name, account_id, campaign_id, status, effective_status, daily_budget, lifetime_budget, budget_remaining, bid_amount, bid_strategy, billing_event, optimization_goal, targeting, start_time, end_time, created_time, updated_time, pacing_type, destination_type

  • date_format (string): Date format: 'U' for Unix timestamp, 'Y-m-d H:i:s' for MySQL datetime

Returns: Object where keys are ad set IDs and values are the corresponding ad set details.

Examples:

  • Use when: "Get details for ad sets 23843211234567, 23843211234568, and 23843211234569"

Inputs: adset_ids (required), fields, date_format.

meta_ads_get_ad_videoGet Meta Ad VideoA
Read-onlyIdempotent

Get video details (source URL, thumbnail, title, duration) for a Meta ad video. Provide either ad_id (server resolves the video_id from the ad's creative) or video_id directly. Pass act_id when available — the /act_X/advideos edge avoids permission errors (#10 / #33) that hit the bare /{video_id} node for BM-shared or page-owned videos.

Inputs: ad_id, video_id, act_id.

meta_ads_get_campaign_by_idGet Meta Campaign by IDA
Read-onlyIdempotent

Retrieve detailed information about a specific Meta ad campaign.

Args:

  • campaign_id (string): Campaign ID, e.g., '23843xxxxx'

  • fields (string[]): Fields to retrieve. Available: id, name, account_id, objective, status, effective_status, configured_status, daily_budget, lifetime_budget, budget_remaining, spend_cap, bid_strategy, buying_type, created_time, updated_time, start_time, stop_time, special_ad_categories, pacing_type, promoted_object, issues_info, recommendations

  • date_format (string): Date format: 'U' for Unix timestamp, 'Y-m-d H:i:s' for MySQL datetime, default: ISO 8601

Returns: Object with the requested campaign fields.

Examples:

  • Use when: "Get details for campaign 23843xxxxx"

  • Use when: "What is the objective and status of my campaign?"

Inputs: campaign_id (required), fields, date_format.

meta_ads_get_campaign_insightsGet Meta Campaign InsightsA
Read-onlyIdempotent

Retrieve performance insights for a specific Meta ad campaign.

Fetches advertising statistics for a campaign, allowing analysis of metrics like impressions, clicks, conversions, spend, etc.

Args:

  • campaign_id (string): Campaign ID, e.g., '23843xxxxx'

  • fields (string[]): Metrics to retrieve. Common: campaign_name, impressions, clicks, spend, ctr, reach, actions, objective, cpc, cpm, date_start, date_stop

  • date_preset (string): Relative time range preset (default: last_30d)

  • time_range (object): Custom range {'since':'YYYY-MM-DD','until':'YYYY-MM-DD'}

  • level (string): Aggregation level: campaign, adset, ad (default: campaign)

  • breakdowns (string[]): Segment by: age, gender, country, publisher_platform, impression_device, etc.

  • See full parameter list in inputSchema

Returns: Object with:

  • data (array): List of insight records with requested metrics

  • paging (object): Pagination cursors. Use meta_ads_fetch_pagination_url with paging.next to get more results

Pagination note: When response contains paging.next, use meta_ads_fetch_pagination_url to retrieve additional pages automatically.

Inputs: campaign_id (required), fields, date_preset, time_range, +19 more.

meta_ads_get_campaigns_by_adaccountGet Meta Campaigns by Ad AccountA
Read-onlyIdempotent

Retrieve all campaigns from a specific Meta ad account with filtering and pagination.

Args:

  • act_id (string): Ad account ID prefixed with 'act_', e.g., 'act_1234567890'

  • fields (string[]): Fields per campaign. Common: id, name, objective, effective_status, created_time, daily_budget, lifetime_budget, budget_remaining

  • effective_status (string[]): Filter by status: ACTIVE, PAUSED, DELETED, PENDING_REVIEW, DISAPPROVED, PREAPPROVED, PENDING_BILLING_INFO, ARCHIVED, WITH_ISSUES

  • objective (string[]): Filter by objective: APP_INSTALLS, BRAND_AWARENESS, CONVERSIONS, EVENT_RESPONSES, LEAD_GENERATION, LINK_CLICKS, MESSAGES, PAGE_LIKES, POST_ENGAGEMENT, PRODUCT_CATALOG_SALES, REACH, VIDEO_VIEWS

  • filtering (object[]): Additional filter objects with field, operator, value

  • limit (number): Results per page (1-100, default: 25)

  • after / before (string): Pagination cursors

  • date_preset / time_range: Date filter for campaigns

  • updated_since (number): Return campaigns updated since this Unix timestamp

  • is_completed (boolean): True = only completed, False = only active, null = both

  • special_ad_categories (string[]): Filter by: EMPLOYMENT, HOUSING, CREDIT, ISSUES_ELECTIONS_POLITICS, NONE

  • include_drafts (boolean): Include draft campaigns if true

  • date_format (string): Date format for response

Returns: Object with data (campaign array) and paging. Use meta_ads_fetch_pagination_url with paging.next for more results.

Inputs: act_id (required), fields, filtering, date_preset, +13 more.

meta_ads_get_image_by_hashGet Meta Ad Image by HashA
Read-onlyIdempotent

Look up a single image in an ad account's image library by hash. Returns the CDN url, dimensions, name, and status — useful when you only have the hash (e.g., from upload_ad_image or a creative's object_story_spec.link_data.image_hash) and need the URL.

Inputs: act_id (required), image_hash (required).

meta_ads_get_interest_suggestionsGet Meta Ad Interest SuggestionsA
Read-onlyIdempotent

Given a seed list of interest names, return related/suggested interests.

Args:

  • interest_list (string[]): Seed interest names, e.g., ["Basketball", "Soccer"]

  • limit (number, optional): Max suggestions (default 25)

Inputs: interest_list (required), limit.

meta_ads_list_ad_accountsList Meta Ad AccountsA
Read-onlyIdempotent

List all ad accounts associated with the authenticated Facebook user.

Returns account names and IDs. When the response contains a paging.next URL, use meta_ads_fetch_pagination_url to retrieve additional pages.

Returns: Object with adaccounts.data array, each containing:

  • id (string): Ad account ID prefixed with 'act_' (e.g., 'act_1234567890')

  • name (string): Display name of the ad account

Examples:

  • Use when: "Show me all my ad accounts"

  • Use when: "What ad accounts do I have access to?"

Inputs: no named parameters.

meta_ads_search_behaviorsSearch Meta Ad BehaviorsA
Read-onlyIdempotent

List available behavior targeting options.

Args:

  • limit (number, optional): Max results (default 50)

Inputs: limit.

meta_ads_search_demographicsSearch Meta Ad DemographicsA
Read-onlyIdempotent

List demographic targeting options. Pass demographic_class to scope the results (default: 'demographics'). Other valid classes: 'life_events', 'industries', 'income', 'family_statuses', 'user_device', 'user_os'.

Inputs: demographic_class, limit.

meta_ads_search_geo_locationsSearch Meta Ad Geo LocationsA
Read-onlyIdempotent

Search Meta's geographic targeting catalog by query string. Returns location keys to use in targeting.geo_locations.

Args:

  • q (string): Search term (e.g., "New York", "Japan")

  • location_types (string[], optional): Filter by types: 'country', 'region', 'city', 'zip', 'geo_market', 'electoral_district'.

  • limit (number, optional): Max results (default 25)

Inputs: q (required), location_types, limit.

meta_ads_search_interestsSearch Meta Ad InterestsA
Read-onlyIdempotent

Search Meta's interest targeting catalog by keyword. Returns interest IDs suitable for use in an ad set's targeting.flexible_spec.

Args:

  • q (string): Search term (e.g., "baseball", "cooking", "travel")

  • limit (number, optional): Max results (default 25)

Returns: { data: [{ id, name, audience_size_lower_bound, audience_size_upper_bound, path, topic }] }

Inputs: q (required), limit.

meta_ads_search_pages_by_nameSearch Meta Pages by NameA
Read-onlyIdempotent

Search the user's pages by a case-insensitive substring of name or username.

Internally fetches /me/accounts then filters client-side. Meta's Graph API does not expose a server-side name filter on /me/accounts.

Args:

  • search_term (string): Substring to match against page name or username.

Inputs: search_term (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.8/5.0

    Scored across 35 tools

    Disambiguation5/5

    Each tool targets a distinct resource and action, such as retrieving ads by account, adset, or campaign, and separate search tools for interests, behaviors, demographics, etc. There is minimal overlap or ambiguity.

    Naming Consistency5/5

    All tool names follow a consistent `meta_ads_<verb>_<object>` pattern, using lowercase and underscores. Variations like `meta_ads_get_ads_by_adaccount` and `meta_ads_search_interests` are predictable and uniform.

    Tool Count2/5

    With 35 tools, the count is well above the typical 15-25 range considered reasonable. While the domain is complex, the number feels excessive and could be streamlined.

    Completeness2/5

    The tool set is heavily read-oriented, covering listing, retrieving, and searching for various objects. However, it lacks essential write operations like create, update, or delete for campaigns, ad sets, ads, and creatives, which is a significant gap for typical advertising workflows.

    Maintenance

    ActivityInactive
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      A 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.
      35
      1,368
      Business Source 1.1
    • A
      license
      C
      quality
      C
      maintenance
      A local Model Context Protocol server that enables interaction with the Meta Marketing API to manage ad accounts, campaigns, and creatives. It provides tools for targeting research, insight reporting, and campaign management through local MCP clients like Claude Code and Cursor.
      40
      79
      AGPL 3.0
    • A
      license
      Not graded
      quality
      B
      maintenance
      A Model Context Protocol server that lets AI assistants run your Meta Ads end to end — launch campaigns, upload creatives, update budgets, and dig into performance through natural conversation. Works across Facebook, Instagram, and other Meta surfaces.
      Business Source 1.1
    • F
      license
      Not graded
      quality
      D
      maintenance
      A comprehensive MCP server for managing and analyzing Meta Ads (Facebook/Instagram) with over 80 natural-language tools for AI agents like Claude Desktop.
      -