# 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](https://developers.facebook.com)
- Access Token com permissões de leitura (`ads_read`)
- Account ID da conta de anúncios

## 🔧 Instalação

1. Clone o repositório:
```bash
cd mcp-facebook-ads
```

2. Instale as dependências:
```bash
npm install
```

3. Configure as variáveis de ambiente:
```bash
cp .env.example .env
```

4. Edite o arquivo `.env` com suas credenciais:
```env
FB_ACCESS_TOKEN=seu_token_aqui
FB_ACCOUNT_ID=seu_account_id_aqui
FB_API_VERSION=v21.0
```

5. Build o projeto:
```bash
npm run build
```

## 🎯 Como usar

### Opção 1: Via npx (recomendado)

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

```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

```bash
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`)
- `fields` (opcional): Métricas a serem retornadas (ex: `impressions,clicks,spend,ctr`)

### 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`)
- `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`)

### 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](https://developers.facebook.com/tools/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](https://developers.facebook.com/docs/facebook-login/guides/access-tokens/get-long-lived).

## 📖 Documentação da API

- [Facebook Marketing API](https://developers.facebook.com/docs/marketing-apis)
- [Graph API Explorer](https://developers.facebook.com/tools/explorer/)
- [Insights API](https://developers.facebook.com/docs/marketing-api/insights)

## 📝 License

MIT