mcp-facebook-ads

MarceloSantosCorrea/mcp-facebook-ads

3.1

If you are the rightful owner of mcp-facebook-ads and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

MCP Server for querying Facebook Ads API data, providing read-only access to campaigns, metrics, insights, and ad creatives.

Tools
4
Resources
0
Prompts
0

MCP Facebook Ads

MCP Server para consultar dados do Facebook Ads API (Marketing API) - Somente leitura.

🚀 Features

  • ✅ Consultar campanhas
  • ✅ Obter métricas e performance de campanhas
  • ✅ Extrair insights e relatórios da conta
  • ✅ Consultar criativos de anúncios

📋 Pré-requisitos

  • Node.js 18+
  • Facebook App criado no Facebook Developers
  • Access Token com permissões de leitura (ads_read)
  • Account ID da conta de anúncios

🔧 Instalação

  1. Clone o repositório:
cd mcp-facebook-ads
  1. Instale as dependências:
npm install
  1. Configure as variáveis de ambiente:
cp .env.example .env
  1. Edite o arquivo .env com suas credenciais:
FB_ACCESS_TOKEN=seu_token_aqui
FB_ACCOUNT_ID=seu_account_id_aqui
FB_API_VERSION=v21.0
  1. Build o projeto:
npm run build

🎯 Como usar

Opção 1: Via npx (recomendado)

Adicione ao seu arquivo de configuração MCP (ex: .cursor/mcp.json):

"facebook-ads": {
  "command": "npx",
  "args": [
    "--yes",
    "mcp-facebook-ads",
    "--transport",
    "stdio"
  ],
  "env": {
    "FB_ACCESS_TOKEN": "seu_token_aqui",
    "FB_ACCOUNT_ID": "seu_account_id_aqui",
    "FB_API_VERSION": "v21.0"
  }
}

Opção 2: Executar localmente

npm start

🛠️ Tools disponíveis

1. get_campaigns

Retorna lista de campanhas da conta de anúncios.

Parâmetros:

  • fields (opcional): Campos a serem retornados (ex: id,name,status,objective)
  • limit (opcional): Limite de resultados (padrão: 25)

2. get_campaign_insights

Retorna métricas e performance de uma campanha específica.

Parâmetros:

  • campaign_id (obrigatório): ID da campanha
  • date_preset (opcional): Período pré-definido (ex: last_7d, last_30d, lifetime)
  • since (opcional): Data inicial no formato YYYY-MM-DD (requer until)
  • until (opcional): Data final no formato YYYY-MM-DD (requer since)
  • fields (opcional): Métricas a serem retornadas (ex: impressions,clicks,spend,ctr)

Nota: Use date_preset OU since/until para definir o período. Se ambos forem fornecidos, since/until terá prioridade.

3. get_account_insights

Retorna insights e relatórios da conta de anúncios.

Parâmetros:

  • date_preset (opcional): Período pré-definido (ex: last_7d, last_30d, today)
  • since (opcional): Data inicial no formato YYYY-MM-DD (requer until)
  • until (opcional): Data final no formato YYYY-MM-DD (requer since)
  • fields (opcional): Métricas a serem retornadas (ex: impressions,clicks,spend,cpc,cpm,ctr)
  • level (opcional): Nível de agregação (account, campaign, adset, ad)

Nota: Use date_preset OU since/until para definir o período. Se ambos forem fornecidos, since/until terá prioridade.

4. get_ad_creatives

Retorna informações sobre os criativos de um anúncio.

Parâmetros:

  • ad_id (obrigatório): ID do anúncio
  • fields (opcional): Campos a serem retornados (ex: name,thumbnail_url,object_story_spec)

📚 Campos úteis da API

Campanhas:

  • id, name, status, objective, daily_budget, lifetime_budget, created_time

Métricas/Insights:

  • impressions, clicks, spend, ctr, cpc, cpm, reach, frequency, conversions

Criativos:

  • id, name, thumbnail_url, image_url, video_id, object_story_spec

🔐 Obter Access Token

  1. Acesse o Facebook Graph API Explorer
  2. Selecione seu App
  3. Adicione as permissões: ads_read
  4. Clique em "Generate Access Token"
  5. Copie o token gerado

⚠️ Importante: Tokens de curta duração expiram em 1-2 horas. Para uso prolongado, gere um Long-Lived Token.

📖 Documentação da API

📝 License

MIT