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

2. Instale as dependências:

npm install

3. Configure as variáveis de ambiente:

cp .env.example .env

4. 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

5. 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

• Facebook Marketing API
• Graph API Explorer
• Insights API

📝 License

MIT