# Meta Ads (Facebook & Instagram) — how to use (mcp.ai)

Leitura e gestão de campanhas Meta Ads, ad sets, ads, audiências, páginas e Business Manager. Você fornece um long-lived access_token e o Facebook App ID (FB_API_ID).

## Option A — via MCP (recommended)
Remote MCP endpoint (HTTP, streamable): `https://api.mcp.ai/p_meta_ads?ms=1781045340000`
Add it as a custom/remote MCP connector in your client (Claude, Cursor, VS Code…), then authenticate when prompted. Once connected, ask the agent to use the server's tools (e.g. `meta_ads_list_accounts`).

## Option B — via direct REST API
Base URL: `https://api.mcp.ai/api/meta_ads`
Auth: `Authorization: Bearer sk_live_…` — create a workspace API key at https://mcp.ai/settings/api-keys
Discover endpoints: `GET https://api.mcp.ai/api/meta_ads/_endpoints`

### Endpoints
- `POST https://api.mcp.ai/api/meta_ads/accounts` — Listar conexões Meta (logins) + ad accounts dentro de cada uma
  - body: { auth_account?: string }
- `POST https://api.mcp.ai/api/meta_ads/status` — Validar token, expiry, ad accounts conectados e scopes
  - body: { auth_account?: string }
- `POST https://api.mcp.ai/api/meta_ads/campaigns` — Listar campanhas: id, nome, status, objective, orçamento, datas
  - body: { auth_account?: string, account?: string, include_paused?: boolean }
- `POST https://api.mcp.ai/api/meta_ads/campaigns/write` — Criar, atualizar, pausar ou ativar campanhas. Orçamentos em centavos.
  - body: { auth_account?: string, account?: string, action: string, campaign_id?: string, name?: string, objective?: string, daily_budget?: number, lifetime_budget?: number, status?: string, special_ad_categories?: string[] }
- `POST https://api.mcp.ai/api/meta_ads/campaigns/delete` — Deletar campanha (irreversível)
  - body: { auth_account?: string, campaign_id: string }
- `POST https://api.mcp.ai/api/meta_ads/adsets` — Detalhes de ad sets: targeting, orçamento, schedule, billing, optimization
  - body: { auth_account?: string, account?: string, include_paused?: boolean }
- `POST https://api.mcp.ai/api/meta_ads/adsets/write` — Criar ou atualizar ad sets. targeting como JSON string.
  - body: { auth_account?: string, account?: string, action: string, adset_id?: string, campaign_id?: string, name?: string, daily_budget?: number, lifetime_budget?: number, billing_event?: string, optimization_goal?: string, targeting?: string, start_time?: string, end_time?: string, status?: string }
- `POST https://api.mcp.ai/api/meta_ads/adsets/delete` — Deletar ad set (irreversível)
  - body: { auth_account?: string, adset_id: string }
- `POST https://api.mcp.ai/api/meta_ads/ads` — Listar ads com creatives e insights (spend, revenue, ROAS, actions)
  - body: { auth_account?: string, account?: string, include_paused?: boolean, since?: string, until?: string }
- `POST https://api.mcp.ai/api/meta_ads/insights/today` — Dashboard de hoje por ad: spend, revenue, ROAS, CPA, impressões, clicks, CTR + _summary
  - body: { auth_account?: string, account?: string, include_zero?: boolean }
- `POST https://api.mcp.ai/api/meta_ads/insights/realtime` — Realtime hourly de hoje por ad + _summary
  - body: { auth_account?: string, account?: string }
- `POST https://api.mcp.ai/api/meta_ads/insights/roas` — ROAS por período via /insights (inclui ads em qualquer status). Default level=ad.
  - body: { auth_account?: string, account?: string, since?: string, until?: string, level?: string }
- `POST https://api.mcp.ai/api/meta_ads/creatives/write` — Criar creative, criar ad ou atualizar ad
  - body: { auth_account?: string, account?: string, action: string, name?: string, page_id?: string, message?: string, link?: string, image_hash?: string, video_id?: string, call_to_action_type?: string, adset_id?: string, creative_id?: string, ad_id?: string, status?: string }
- `POST https://api.mcp.ai/api/meta_ads/creatives/delete` — Deletar ad (irreversível)
  - body: { auth_account?: string, ad_id: string }
- `POST https://api.mcp.ai/api/meta_ads/pages` — Pages: list / insights / posts / post_insights
  - body: { auth_account?: string, action: string, page_id?: string, post_id?: string, period?: string }
- `POST https://api.mcp.ai/api/meta_ads/business` — Business Manager: list / accounts / pages / users / pixels
  - body: { auth_account?: string, action: string, business_id?: string }
- `POST https://api.mcp.ai/api/meta_ads/media` — Listar imagens ou vídeos enviados
  - body: { auth_account?: string, account?: string, action: string }
- `POST https://api.mcp.ai/api/meta_ads/media/write` — Upload de imagens/vídeos ou curl command para vídeos grandes locais
  - body: { auth_account?: string, account?: string, action: string, image_url?: string, video_url?: string, title?: string, file_path?: string }
- `POST https://api.mcp.ai/api/meta_ads/audiences` — Listar Custom Audiences
  - body: { auth_account?: string, account?: string }
- `POST https://api.mcp.ai/api/meta_ads/audiences/write` — Criar audience ou adicionar usuários (PII SHA-256 hashed automaticamente)
  - body: { auth_account?: string, account?: string, action: string, audience_id?: string, name?: string, description?: string, users?: object[] }
- `POST https://api.mcp.ai/api/meta_ads/audiences/delete` — Deletar Custom Audience (irreversível)
  - body: { auth_account?: string, audience_id: string }

## Example prompts
- "Liste minhas contas de anúncio do Meta Ads"
- "Quanto gastei hoje no Facebook Ads e qual o ROAS?"
- "Mostre as campanhas ativas e o orçamento diário"

## More
- Page: https://mcp.ai/meta_ads
- Agent spec (llms.txt): https://mcp.ai/meta_ads/llms.txt
- Postman collection: https://mcp.ai/meta_ads/postman.json