# Meta Ads (Facebook & Instagram)

> Read and manage Meta Ads campaigns, ad sets, ads, audiences, pages and Business Manager. You provide

- name: io.github.mcp-dir/meta_ads-mcp
- version: 0.1.0
- connection class: R0 (autonomous)
- trust: 91/100
- quality: 85/100 (good)
- owner: not claimed
- descriptor: https://api.protogrid.dev/v1/servers/io.github.mcp-dir%2Fmeta_ads-mcp
- tools: https://api.protogrid.dev/v1/servers/io.github.mcp-dir%2Fmeta_ads-mcp/tools

**An agent can connect right now, no human step.** Remote endpoint, no authentication, reachable on the last probe.

## Connection (mcpServers)

```json
{
  "mcpServers": {
    "meta_ads-mcp": {
      "type": "http",
      "url": "https://api.mcp.ai/p_meta_ads"
    }
  }
}
```


## Trust

- hygiene: 100
- liveness: 99
- freshness: 85
- provenance: 80
- drivers: +repository +namespace-matches-repo +reachable +uptime-97% ~updated-60d-ago
- Derived from observable signals (official registry feed and our own credential-free probes); no code audit performed.

## Quality 85/100 (good)

### protocol: 75 (weight 25)

- warn `protocol.modern`: newest supported version is 2025-11-25; 2026-07-28 not supported, older versions are deprecated until 2027-07-28
- n/a `protocol.stateless`: only applies to 2026-07-28 servers
- pass `protocol.transport`: streamable HTTP
- n/a `protocol.list_ttl`: only applies to 2026-07-28 servers

### authorization: n/a (weight 15)

- n/a `auth.prm`, `auth.as_metadata`, `auth.cimd`: no remote uses OAuth
- n/a `auth.secret_in_url`: no templated URL

### tool hygiene: 86 (weight 30)

- pass `tools.descriptions`: every tool has a description
- warn `tools.description_length`: 3 tools have descriptions over 1,024 characters, which crowds the context
- pass `tools.schemas`: every tool has an object input schema
- pass `tools.annotations`: 44 of 44 tools declare readOnlyHint or destructiveHint
- pass `tools.directory_hints`: every tool declares readOnlyHint, destructiveHint, idempotentHint and openWorldHint
- warn `tools.token_cost`: about 10,697 tokens to load every tool
- pass `tools.api_dump`: tools are not a one-to-one API dump

### stability: 100 (weight 15)

- pass `stability.changes`: no tool changes in 30 days
- pass `stability.rug_pull`: no tool changed its meaning under the same name

### dependencies: n/a (weight 15)

- n/a `deps.known_vulns`, `deps.mcp_sdk_version`, `deps.resolvable`: no npm or PyPI package

- tools: 44, about 10,697 tokens to load them all
- tool set hash: 1d696752eacbe891c0a6f42d29cabb2e
- badge: [![protogrid quality](https://protogrid.dev/badge/io.github.mcp-dir/meta_ads-mcp.svg)](https://protogrid.dev/servers/io.github.mcp-dir/meta_ads-mcp)
- Checks run on what our credential-free, read-only probes observe; tools are never called and no code audit is performed.

### Tool changes

_No tool definition changes recorded._

## Remotes

- https://api.mcp.ai/p_meta_ads (streamable-http, auth none, reachable true, uptime30d 0.96581197)

## Packages

_none_

## Tools (44)

- `authenticate`: MCP.AI for IDE agents (Cursor, etc.): log in in the browser, copy the access token. Best: add it to this server's config as a header `Authorization: Bearer <token>` for a permanent, non-expiring connection. Or paste it here for a session-only login: call with { token: "<jwt>" } after the user pastes, or with no args to get the link.
- `connect`: Returns connection status and URLs. When all providers are connected, returns authenticated:true and empty pending[]. When credentials are missing, returns connect_url for the toolkit and per-install URLs.
- `marketplace`: The official mcp.ai marketplace — the in-platform catalog of every MCP/tool, AND the way to run them. Covers capability requests like "find an MCP that does X", "consulta um CPF", "is there a tool for Y". Core flow: action=search discovers MCPs by intent → describe returns one MCP's full profile (every tool with its id + params, pricing, auth) so you pick the right tool_id → invoke RUNS that tool. KEY: invoke works even when the MCP is NOT installed — it runs the tool pontualmente (one-off), without adding the MCP to the toolkit and without bloating the tool list. If the MCP needs a credential/login, invoke returns a connect link; if it is paid and the wallet is empty, invoke returns a checkout/top-up link (the user opens it, then you retry). Use install only to make an MCP PERMANENT in the active toolkit (its tools then show up natively in future sessions); prefer invoke for a single/occasional use. list_tools lists what is callable right now. subscribe/cancel handle per-MCP billing; report_bug sends feedback; request_mcp asks us to build a NEW MCP when nothing fits. Search/describe flag installed_in_toolkit vs installed_in_workspace. Writes (install/uninstall/subscribe/cancel and the one-off install behind invoke) require workspace owner/admin. It also carries the mcp.ai PROMPT LIBRARY, which is about ready-made prompt TEXT rather than MCPs: search_prompts finds one, get_prompt returns its full text with {{variables}} filled, and publish_prompt saves a prompt and returns a shareable mcp.ai/p/<slug> link that opens without login.
- `meta_ads_ads`: List ads with creatives (image, video, copy) and performance insights. Includes spend, revenue, ROAS, actions.
- `meta_ads_adset_delete`: Permanently delete a Meta Ads ad set. Irreversible.

Bulk support: accepts adset_ids for batched execution.
- `meta_ads_adset_detail`: Get detailed ad set info: targeting, budget, schedule, billing, optimization goal, delivery status. Fills the gap between campaigns and ads.
- `meta_ads_adset_write_create`: Create or update Meta Ads ad sets.
Actions:
  create — new ad set linked to a campaign (targeting, budget, schedule)
  update — change fields on existing ad set
Targeting is a JSON object: { "geo_locations": { "countries": ["BR"] }, "age_min": 18, "age_max": 65, "genders": [1, 2] }
Budgets in cents.
BUDGET (most common create failure): the ad set REQUIRES daily_budget or lifetime_budget, UNLESS the parent campaign already carries the budget (campaign budget optimization) — in which case the ad set must NOT send one. lifetime_budget also requires end_time.
optimization_goal must match the campaign objective: OUTCOME_TRAFFIC → LINK_CLICKS / LANDING_PAGE_VIEWS / IMPRESSIONS; OUTCOME_AWARENESS → REACH / IMPRESSIONS; OUTCOME_ENGAGEMENT → POST_ENGAGEMENT / THRUPLAY / PAGE_LIKES / CONVERSATIONS; OUTCOME_LEADS → LEAD_GENERATION / QUALITY_LEAD / OFFSITE_CONVERSIONS; OUTCOME_SALES → OFFSITE_CONVERSIONS / VALUE; OUTCOME_APP_PROMOTION → APP_INSTALLS.
OFFSITE_CONVERSIONS/VALUE need promoted_object with the pixel: {"pixel_id":"123","custom_event_type":"PURCHASE"}. LEAD_GENERATION needs {"page_id":"123"}.
destination_type is only for non-website destinations (MESSENGER, WHATSAPP, PHONE_CALL); omit it for regular website traffic.
For destructive delete use meta_ads_adset_delete.

[Flattened action: create]

Bulk support: accepts adset_ids, campaign_ids for batched execution.
- `meta_ads_adset_write_update`: Create or update Meta Ads ad sets.
Actions:
  create — new ad set linked to a campaign (targeting, budget, schedule)
  update — change fields on existing ad set
Targeting is a JSON object: { "geo_locations": { "countries": ["BR"] }, "age_min": 18, "age_max": 65, "genders": [1, 2] }
Budgets in cents.
BUDGET (most common create failure): the ad set REQUIRES daily_budget or lifetime_budget, UNLESS the parent campaign already carries the budget (campaign budget optimization) — in which case the ad set must NOT send one. lifetime_budget also requires end_time.
optimization_goal must match the campaign objective: OUTCOME_TRAFFIC → LINK_CLICKS / LANDING_PAGE_VIEWS / IMPRESSIONS; OUTCOME_AWARENESS → REACH / IMPRESSIONS; OUTCOME_ENGAGEMENT → POST_ENGAGEMENT / THRUPLAY / PAGE_LIKES / CONVERSATIONS; OUTCOME_LEADS → LEAD_GENERATION / QUALITY_LEAD / OFFSITE_CONVERSIONS; OUTCOME_SALES → OFFSITE_CONVERSIONS / VALUE; OUTCOME_APP_PROMOTION → APP_INSTALLS.
OFFSITE_CONVERSIONS/VALUE need promoted_object with the pixel: {"pixel_id":"123","custom_event_type":"PURCHASE"}. LEAD_GENERATION needs {"page_id":"123"}.
destination_type is only for non-website destinations (MESSENGER, WHATSAPP, PHONE_CALL); omit it for regular website traffic.
For destructive delete use meta_ads_adset_delete.

[Flattened action: update]

Bulk support: accepts adset_ids, campaign_ids for batched execution.
- `meta_ads_audience`: List Custom Audiences in the ad account.
- `meta_ads_audience_delete`: Permanently delete a Custom Audience. Irreversible.

Bulk support: accepts audience_ids for batched execution.
- `meta_ads_audience_write_add_users`: Manage Custom Audiences for targeting.
Actions:
  create     — create a new custom audience
  add_users  — upload hashed user data (email, phone, first/last name). PII is SHA-256 hashed before upload.
Users format: array of { email, phone?, fn?, ln? }. Data is normalized and hashed automatically.
For destructive delete use meta_ads_audience_delete.

[Flattened action: add_users]

Bulk support: accepts audience_ids for batched execution.
- `meta_ads_audience_write_create`: Manage Custom Audiences for targeting.
Actions:
  create     — create a new custom audience
  add_users  — upload hashed user data (email, phone, first/last name). PII is SHA-256 hashed before upload.
Users format: array of { email, phone?, fn?, ln? }. Data is normalized and hashed automatically.
For destructive delete use meta_ads_audience_delete.

[Flattened action: create]

Bulk support: accepts audience_ids for batched execution.
- `meta_ads_business_accounts`: Read Facebook Business Manager data. Actions:
  list — list Business Managers
  accounts — ad accounts owned by a BM
  pages — pages owned by a BM
  users — business users and system users
  pixels — pixels owned by a BM

[Flattened action: accounts]

Bulk support: accepts business_ids for batched execution.
- `meta_ads_business_list`: Read Facebook Business Manager data. Actions:
  list — list Business Managers
  accounts — ad accounts owned by a BM
  pages — pages owned by a BM
  users — business users and system users
  pixels — pixels owned by a BM

[Flattened action: list]

Bulk support: accepts business_ids for batched execution.
- `meta_ads_business_pages`: Read Facebook Business Manager data. Actions:
  list — list Business Managers
  accounts — ad accounts owned by a BM
  pages — pages owned by a BM
  users — business users and system users
  pixels — pixels owned by a BM

[Flattened action: pages]

Bulk support: accepts business_ids for batched execution.
- `meta_ads_business_pixels`: Read Facebook Business Manager data. Actions:
  list — list Business Managers
  accounts — ad accounts owned by a BM
  pages — pages owned by a BM
  users — business users and system users
  pixels — pixels owned by a BM

[Flattened action: pixels]

Bulk support: accepts business_ids for batched execution.
- `meta_ads_business_users`: Read Facebook Business Manager data. Actions:
  list — list Business Managers
  accounts — ad accounts owned by a BM
  pages — pages owned by a BM
  users — business users and system users
  pixels — pixels owned by a BM

[Flattened action: users]

Bulk support: accepts business_ids for batched execution.
- `meta_ads_campaign_delete`: Permanently delete a Meta Ads campaign. Irreversible.

Bulk support: accepts campaign_ids for batched execution.
- `meta_ads_campaigns`: List Meta Ads campaigns. Returns: id, name, status, objective, budget, dates.
Set include_paused=true to also show paused campaigns.
- `meta_ads_campaign_write_activate`: Create, update, pause or activate Meta Ads campaigns.
Actions:
  create  — new campaign (name, objective, budget required)
  update  — change name, budget, status
  pause   — shortcut to pause a campaign
  activate — shortcut to activate a campaign
Objectives: OUTCOME_TRAFFIC, OUTCOME_ENGAGEMENT, OUTCOME_LEADS, OUTCOME_SALES, OUTCOME_AWARENESS, OUTCOME_APP_PROMOTION.
Budgets are in cents (e.g. 5000 = $50.00). A budget HERE means campaign budget optimization: the ad sets under it must then NOT carry their own budget. Leave the campaign budget empty to budget per ad set instead.
For destructive delete use meta_ads_campaign_delete.

[Flattened action: activate]

Bulk support: accepts campaign_ids for batched execution.
- `meta_ads_campaign_write_create`: Create, update, pause or activate Meta Ads campaigns.
Actions:
  create  — new campaign (name, objective, budget required)
  update  — change name, budget, status
  pause   — shortcut to pause a campaign
  activate — shortcut to activate a campaign
Objectives: OUTCOME_TRAFFIC, OUTCOME_ENGAGEMENT, OUTCOME_LEADS, OUTCOME_SALES, OUTCOME_AWARENESS, OUTCOME_APP_PROMOTION.
Budgets are in cents (e.g. 5000 = $50.00). A budget HERE means campaign budget optimization: the ad sets under it must then NOT carry their own budget. Leave the campaign budget empty to budget per ad set instead.
For destructive delete use meta_ads_campaign_delete.

[Flattened action: create]

Bulk support: accepts campaign_ids for batched execution.
- `meta_ads_campaign_write_pause`: Create, update, pause or activate Meta Ads campaigns.
Actions:
  create  — new campaign (name, objective, budget required)
  update  — change name, budget, status
  pause   — shortcut to pause a campaign
  activate — shortcut to activate a campaign
Objectives: OUTCOME_TRAFFIC, OUTCOME_ENGAGEMENT, OUTCOME_LEADS, OUTCOME_SALES, OUTCOME_AWARENESS, OUTCOME_APP_PROMOTION.
Budgets are in cents (e.g. 5000 = $50.00). A budget HERE means campaign budget optimization: the ad sets under it must then NOT carry their own budget. Leave the campaign budget empty to budget per ad set instead.
For destructive delete use meta_ads_campaign_delete.

[Flattened action: pause]

Bulk support: accepts campaign_ids for batched execution.
- `meta_ads_campaign_write_update`: Create, update, pause or activate Meta Ads campaigns.
Actions:
  create  — new campaign (name, objective, budget required)
  update  — change name, budget, status
  pause   — shortcut to pause a campaign
  activate — shortcut to activate a campaign
Objectives: OUTCOME_TRAFFIC, OUTCOME_ENGAGEMENT, OUTCOME_LEADS, OUTCOME_SALES, OUTCOME_AWARENESS, OUTCOME_APP_PROMOTION.
Budgets are in cents (e.g. 5000 = $50.00). A budget HERE means campaign budget optimization: the ad sets under it must then NOT carry their own budget. Leave the campaign budget empty to budget per ad set instead.
For destructive delete use meta_ads_campaign_delete.

[Flattened action: update]

Bulk support: accepts campaign_ids for batched execution.
- `meta_ads_creative_delete`: Permanently delete a Meta Ads ad. Irreversible.

Bulk support: accepts ad_ids for batched execution.
- `meta_ads_creative_write_create_ad`: Create ad creatives and ads (final step to launch).
Actions:
  create_creative — create ad creative with image/video + copy (requires page_id)
  create_ad       — create ad linking creative to ad set
  update_ad       — update ad fields (name, status, creative)
For create_creative: provide image_hash (from upload_image) OR video_id (from upload_video) + page_id + message.
call_to_action_type: LEARN_MORE, SHOP_NOW, SIGN_UP, DOWNLOAD, GET_QUOTE, CONTACT_US, SUBSCRIBE, BOOK_NOW, etc.
For destructive delete use meta_ads_creative_delete.

[Flattened action: create_ad]

Bulk support: accepts page_ids, video_ids, adset_ids, creative_ids, ad_ids for batched execution.
- `meta_ads_creative_write_create_creative`: Create ad creatives and ads (final step to launch).
Actions:
  create_creative — create ad creative with image/video + copy (requires page_id)
  create_ad       — create ad linking creative to ad set
  update_ad       — update ad fields (name, status, creative)
For create_creative: provide image_hash (from upload_image) OR video_id (from upload_video) + page_id + message.
call_to_action_type: LEARN_MORE, SHOP_NOW, SIGN_UP, DOWNLOAD, GET_QUOTE, CONTACT_US, SUBSCRIBE, BOOK_NOW, etc.
For destructive delete use meta_ads_creative_delete.

[Flattened action: create_creative]

Bulk support: accepts page_ids, video_ids, adset_ids, creative_ids, ad_ids for batched execution.
- `meta_ads_creative_write_update_ad`: Create ad creatives and ads (final step to launch).
Actions:
  create_creative — create ad creative with image/video + copy (requires page_id)
  create_ad       — create ad linking creative to ad set
  update_ad       — update ad fields (name, status, creative)
For create_creative: provide image_hash (from upload_image) OR video_id (from upload_video) + page_id + message.
call_to_action_type: LEARN_MORE, SHOP_NOW, SIGN_UP, DOWNLOAD, GET_QUOTE, CONTACT_US, SUBSCRIBE, BOOK_NOW, etc.
For destructive delete use meta_ads_creative_delete.

[Flattened action: update_ad]

Bulk support: accepts page_ids, video_ids, adset_ids, creative_ids, ad_ids for batched execution.
- `meta_ads_list_accounts`: List Meta (Facebook) connections AND the ad accounts inside each — returns `connections[]` (OAuth logins) and `ad_accounts[]` with id (act_XXX), name, currency, timezone, status. Use the ad_account_id in `account` on the other tools.
- `meta_ads_media_list_images`: List uploaded media in the ad account.
Actions: list_images, list_videos.

[Flattened action: list_images]
- `meta_ads_media_list_videos`: List uploaded media in the ad account.
Actions: list_images, list_videos.

[Flattened action: list_videos]
- `meta_ads_media_write_get_upload_command`: Upload images and videos to Meta Ads account.
Actions:
  upload_image        — upload an image. Returns the image hash you need for create_creative.
  upload_video        — upload video from URL (Meta fetches it). Returns video_id.
  get_upload_command  — get a curl command for uploading large local video files (keeps file out of AI context).
upload_image accepts the file in four ways (use exactly one): image_url/file_url (public URL),
upload_id (uploaded via the command this tool hands you), file_base64, or upload_code.
Call upload_image with NO file to get a ready-made upload command for a file on the user's machine.
Facebook CDN links (*.fbcdn.net) are signed, expiring and pinned to the browser that opened them —
they do NOT work as image_url from the server; upload the file instead.
For listing already-uploaded media use meta_ads_media.

[Flattened action: get_upload_command]

Bulk support: accepts upload_ids for batched execution.
- `meta_ads_media_write_upload_image`: Upload images and videos to Meta Ads account.
Actions:
  upload_image        — upload an image. Returns the image hash you need for create_creative.
  upload_video        — upload video from URL (Meta fetches it). Returns video_id.
  get_upload_command  — get a curl command for uploading large local video files (keeps file out of AI context).
upload_image accepts the file in four ways (use exactly one): image_url/file_url (public URL),
upload_id (uploaded via the command this tool hands you), file_base64, or upload_code.
Call upload_image with NO file to get a ready-made upload command for a file on the user's machine.
Facebook CDN links (*.fbcdn.net) are signed, expiring and pinned to the browser that opened them —
they do NOT work as image_url from the server; upload the file instead.
For listing already-uploaded media use meta_ads_media.

[Flattened action: upload_image]

Bulk support: accepts upload_ids for batched execution.
- `meta_ads_media_write_upload_video`: Upload images and videos to Meta Ads account.
Actions:
  upload_image        — upload an image. Returns the image hash you need for create_creative.
  upload_video        — upload video from URL (Meta fetches it). Returns video_id.
  get_upload_command  — get a curl command for uploading large local video files (keeps file out of AI context).
upload_image accepts the file in four ways (use exactly one): image_url/file_url (public URL),
upload_id (uploaded via the command this tool hands you), file_base64, or upload_code.
Call upload_image with NO file to get a ready-made upload command for a file on the user's machine.
Facebook CDN links (*.fbcdn.net) are signed, expiring and pinned to the browser that opened them —
they do NOT work as image_url from the server; upload the file instead.
For listing already-uploaded media use meta_ads_media.

[Flattened action: upload_video]

Bulk support: accepts upload_ids for batched execution.
- `meta_ads_pages_insights`: Read Facebook Pages data. Actions:
  list — all pages the user manages (name, fan_count, followers)
  insights — page engagement metrics (follows, views) for a specific page
  posts — recent posts with likes, comments, shares
  post_insights — detailed insights for a specific post

[Flattened action: insights]

Bulk support: accepts page_ids, post_ids for batched execution.
- `meta_ads_pages_list`: Read Facebook Pages data. Actions:
  list — all pages the user manages (name, fan_count, followers)
  insights — page engagement metrics (follows, views) for a specific page
  posts — recent posts with likes, comments, shares
  post_insights — detailed insights for a specific post

[Flattened action: list]

Bulk support: accepts page_ids, post_ids for batched execution.
- `meta_ads_pages_post_insights`: Read Facebook Pages data. Actions:
  list — all pages the user manages (name, fan_count, followers)
  insights — page engagement metrics (follows, views) for a specific page
  posts — recent posts with likes, comments, shares
  post_insights — detailed insights for a specific post

[Flattened action: post_insights]

Bulk support: accepts page_ids, post_ids for batched execution.
- `meta_ads_pages_posts`: Read Facebook Pages data. Actions:
  list — all pages the user manages (name, fan_count, followers)
  insights — page engagement metrics (follows, views) for a specific page
  posts — recent posts with likes, comments, shares
  post_insights — detailed insights for a specific post

[Flattened action: posts]

Bulk support: accepts page_ids, post_ids for batched execution.
- `meta_ads_realtime`: Hourly realtime dashboard for today. Shows per-ad breakdown with hourly stats, campaign/adset/creative details, plus _summary.
- `meta_ads_roas`: ROAS (Return on Ad Spend) for a date range using Meta's /insights endpoint — includes spend from ads in ANY status (ACTIVE/PAUSED/DISABLED/ARCHIVED). Defaults to current month, level=ad. For account totals use level=account; for per-campaign view use level=campaign. Returns per-row spend, revenue, ROAS, plus _summary.
- `meta_ads_status`: Validate Facebook token, check expiry date, list connected ad accounts and scopes.
- `meta_ads_today`: Today's ad performance dashboard. Returns per-ad: spend, revenue, ROAS, CPA, impressions, clicks, CTR. Plus _summary aggregate across all ads.
- `report_bug`: Report a bug, missing feature, or send feedback. Include the conversation array with recent messages for reproduction.
- `show_version`: Show the current MCP platform and adapter versions.
- `toolkit_info`: Returns the current toolkit state: installed MCPs, their connection status, the accounts connected to each one, and how many catalog tools each exposes.