Meta Ads Server

БесплатноHosted

Enables comprehensive management of Facebook and Instagram advertising campaigns via the Meta Marketing API, supporting campaign creation, targeting optimizatio

автор: mikdeangelis

GitHub

Описание

Enables comprehensive management of Facebook and Instagram advertising campaigns via the Meta Marketing API, supporting campaign creation, targeting optimization, and budget management. It provides tools for detailed performance reporting and creative analysis, including insights into spend, ROI, and audience breakdowns.

README

Python 3.10+ Meta Marketing API MCP License: MIT

Server MCP completo per gestire campagne pubblicitarie Facebook/Instagram

Quick Start • Tools Disponibili • Configurazione • Esempi

✨ Caratteristiche

📊 Analisi & Reporting

📈 Metriche performance complete
🎯 Report avanzati con breakdown
💰 Insights su spend, ROI, ROAS
📅 Date personalizzate o preset

🎨 Gestione Campagne

✏️ Crea campagne e ad set
🎯 Modifica targeting e budget
📝 Analizza creative e annunci
🔄 Gestisci stato (attiva/pausa)

🔥 Funzionalità Principali

graph LR
    A[Account] --> B[Campagne]
    B --> C[Ad Set]
    C --> D[Annunci]
    D --> E[Creative]

    B -.-> F[Insights]
    C -.-> F
    D -.-> F
    F --> G[Report]

✅ 10 Tools Completi - Dalla creazione alla reportistica
✅ System User Compatible - Funziona con token permanenti
✅ Error Handling Avanzato - Messaggi di errore dettagliati Meta API
✅ Date Flessibili - Preset o range personalizzati (fino a 37 mesi)
✅ Validazione Automatica - Controlli Pydantic per parametri corretti

⚡ Quick Start

# 1️⃣ Clona il repository
git clone https://github.com/mikdeangelis/mcp-meta-ads.git
cd mcp-meta-ads

# 2️⃣ Crea ambiente virtuale
python3 -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

# 3️⃣ Installa dipendenze
pip install -r requirements.txt

# 4️⃣ Configura token (vedi guida sotto)
export META_ACCESS_TOKEN="your_token_here"

# 5️⃣ Aggiungi al tuo MCP client
# Vedi sezione "Configurazione" per istruzioni specifiche

💡 Primo utilizzo? Segui la guida completa per ottenere il token più sotto.

🛠️ Tools Disponibili

📋 Gestione Risorse

Tool	Descrizione	Esempio
`meta_ads_list_accounts`	Lista tutti gli account pubblicitari	"Mostrami i miei account Meta"
`meta_ads_list_campaigns`	Lista campagne di un account	"Campagne dell'account act_123456"
`meta_ads_list_adsets`	Lista ad set di una campagna	"Ad set della campagna 789"
`meta_ads_list_ads`	Lista annunci di un ad set	"Annunci dell'ad set 456"

✏️ Creazione & Modifica

Tool	Descrizione	Parametri Chiave
`meta_ads_create_campaign`	Crea nuova campagna	`objective`, `daily_budget`, `special_ad_categories`
`meta_ads_create_adset`	Crea nuovo ad set	`targeting`, `bid_amount`, `optimization_goal` ⚠️
`meta_ads_update_adset_targeting`	Modifica targeting	`age_min`, `age_max`, `genders`
`meta_ads_update_adset_budget`	Modifica budget	`daily_budget`
`meta_ads_update_adset_status`	Attiva/pausa ad set	`status` (ACTIVE/PAUSED)

⚠️ Nota: create_adset richiede bid_amount per LINK_CLICKS e targeting_automation.advantage_audience (0 o 1)

📊 Analytics & Insights

Tool	Descrizione	Dettagli
`meta_ads_get_insights`	Metriche performance	Impressions, clicks, spend, CTR, CPC, conversions
`meta_ads_get_creative`	Dettagli creative	Testi, immagini, link, CTA
`meta_ads_generate_report`	Report con breakdown	Età, genere, paese, placement

🔑 Ottenere il Token Meta

Metodo Rapido: Graph API Explorer

📖 Clicca per espandere la guida passo-passo

1️⃣ Crea App Meta Developer

Vai su Facebook Developers
My Apps → Create App → Business
Completa i dettagli dell'app

2️⃣ Aggiungi Marketing API

Dashboard app → trova Marketing API
Clicca Set Up
La Marketing API apparirà nel menu

3️⃣ Genera Token

Opzione A: Graph API Explorer (raccomandato)

Vai su Graph API Explorer
Seleziona la tua app
Get User Access Token → Seleziona permessi:
- ✅ ads_management (gestione completa)
- ✅ ads_read (lettura)
- ✅ read_insights (metriche)
Generate Access Token → Autorizza → Copia token

Opzione B: System User Token (non scade)

Per produzione, usa System User nel Business Manager.

4️⃣ Converti in Long-Lived Token (60 giorni)

curl -X GET "https://graph.facebook.com/v21.0/oauth/access_token" \
  -d "grant_type=fb_exchange_token" \
  -d "client_id=YOUR_APP_ID" \
  -d "client_secret=YOUR_APP_SECRET" \
  -d "fb_exchange_token=YOUR_SHORT_LIVED_TOKEN"

Sostituisci:

YOUR_APP_ID: Dashboard → Settings → Basic
YOUR_APP_SECRET: Dashboard → Settings → Basic
YOUR_SHORT_LIVED_TOKEN: Token generato al punto 3

5️⃣ Verifica Token

curl "https://graph.facebook.com/v21.0/me?access_token=YOUR_TOKEN"

Dovresti vedere i dettagli del tuo profilo Facebook.

Configurazione Token

Opzione 1: File .env (raccomandato)

Crea .env nella directory del progetto:

META_ACCESS_TOKEN=your_token_here

Opzione 2: Variabile d'ambiente

# Linux/macOS
export META_ACCESS_TOKEN="your_token_here"

# Windows PowerShell
$env:META_ACCESS_TOKEN="your_token_here"

# Persistente: aggiungi a ~/.bashrc o ~/.zshrc
echo 'export META_ACCESS_TOKEN="your_token_here"' >> ~/.bashrc
source ~/.bashrc

⚙️ Configurazione

Per Claude Code

Metodo Automatico

claude mcp add meta-ads \
  --command "$(pwd)/.venv/bin/python" \
  --arg "$(pwd)/meta_ads_mcp.py"

Metodo Manuale

Modifica ~/.config/claude-code/config.json:

{
  "mcpServers": {
    "meta-ads": {
      "command": "/path/to/mcp-meta-ads/.venv/bin/python",
      "args": ["/path/to/mcp-meta-ads/meta_ads_mcp.py"],
      "env": {
        "META_ACCESS_TOKEN": "your_token_here"
      }
    }
  }
}

Per Claude Desktop

Modifica claude_desktop_config.json:

macOS/Linux: ~/.config/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "meta-ads": {
      "command": "python",
      "args": ["/path/to/mcp-meta-ads/meta_ads_mcp.py"],
      "env": {
        "META_ACCESS_TOKEN": "your_token_here"
      }
    }
  }
}

💡 Esempi Pratici

🎯 Creare una Campagna Completa

// 1. Crea campagna
meta_ads_create_campaign({
  "account_id": "act_123456789",
  "name": "Estate 2025 - Promozione",
  "objective": "OUTCOME_SALES",
  "daily_budget": 5000,  // €50/giorno
  "status": "PAUSED"
})
// ✅ Campagna creata: ID 120236574531090062

// 2. Crea ad set con targeting
meta_ads_create_adset({
  "campaign_id": "120236574531090062",
  "name": "Italia 25-55 anni",
  "optimization_goal": "LINK_CLICKS",
  "billing_event": "LINK_CLICKS",
  "bid_amount": 150,  // €1.50 per click
  "targeting": {
    "geo_locations": {"countries": ["IT"]},
    "age_min": 25,
    "age_max": 55,
    "targeting_automation": {
      "advantage_audience": 0  // ⚠️ OBBLIGATORIO
    }
  },
  "status": "PAUSED"
  // ⚠️ NON specificare daily_budget se campagna ha già budget
})
// ✅ Ad set creato: ID 120236575096660062

📊 Analisi Performance

// Metriche ultimi 30 giorni
meta_ads_get_insights({
  "object_id": "act_123456789",
  "level": "campaign",
  "date_preset": "last_30d"
})

// Metriche con date personalizzate
meta_ads_get_insights({
  "object_id": "120236574531090062",
  "level": "campaign",
  "since": "2025-01-01",
  "until": "2025-01-31"
})

// Report breakdown per età e genere
meta_ads_generate_report({
  "object_id": "120236575096660062",
  "breakdowns": ["age", "gender"],
  "date_preset": "last_7d"
})

🎨 Analisi Creative

// Dettagli creative di un annuncio
meta_ads_get_creative({
  "ad_id": "123456789"
})
// Restituisce: titolo, body, link, CTA, immagini/video

🔄 Gestione Stato e Budget

// Modifica targeting
meta_ads_update_adset_targeting({
  "adset_id": "120236575096660062",
  "age_min": 30,
  "age_max": 50,
  "genders": [2]  // Solo donne
})

// Aumenta budget
meta_ads_update_adset_budget({
  "adset_id": "120236575096660062",
  "daily_budget": 3000  // €30/giorno
})

// Attiva ad set
meta_ads_update_adset_status({
  "adset_id": "120236575096660062",
  "status": "ACTIVE"
})

📐 Struttura Meta Ads

Account Pubblicitario (act_XXXXX)
│
├── 📁 Campagna (Campaign)
│   ├── 🎯 Obiettivo: OUTCOME_SALES, OUTCOME_TRAFFIC, ecc.
│   ├── 💰 Budget: Giornaliero o Lifetime
│   ├── ⏱️ Schedule: Data inizio/fine
│   │
│   └── 📦 Ad Set
│       ├── 🎯 Targeting
│       │   ├── Geo: Paesi, regioni, città
│       │   ├── Demografia: Età, genere
│       │   └── Advantage Audience: 0 o 1
│       ├── 💵 Bid Amount (per alcuni goals)
│       ├── 📊 Optimization Goal: LINK_CLICKS, CONVERSIONS, ecc.
│       │
│       └── 🎨 Annuncio (Ad)
│           └── 🖼️ Creative
│               ├── 📝 Headline & Body
│               ├── 🖼️ Immagine/Video
│               ├── 🔗 Link URL
│               └── 🎬 Call-to-Action

⚠️ Requisiti Importanti

Per `meta_ads_create_adset`

Parametro	Obbligatorio?	Note
`targeting.geo_locations`	✅ Sì	Almeno paesi, regioni o città
`targeting.targeting_automation.advantage_audience`	✅ Sì	0 (disabilitato) o 1 (abilitato)
`bid_amount`	⚠️ Dipende	OBBLIGATORIO per LINK_CLICKS, LANDING_PAGE_VIEWS, ecc.
`daily_budget`/`lifetime_budget`	⚠️ Dipende	NON usare se campagna ha già budget

Budget: Regole

✅ Budget solo campagna: OK
✅ Budget solo ad set: OK (se campagna senza budget)
❌ Budget campagna + budget ad set: ERRORE (subcode 1885621)

🐛 Troubleshooting

❌ Errore: "META_ACCESS_TOKEN non trovato"

Causa: Variabile d'ambiente non configurata

Soluzione:

export META_ACCESS_TOKEN="your_token_here"
# Oppure crea file .env nella directory del progetto

❌ Errore: "Token non valido o scaduto"

Causa: Token scaduto (short-lived durano poche ore)

Soluzione:

Genera nuovo token da Graph API Explorer
Converti in long-lived (60 giorni)
Oppure usa System User token (permanente)

❌ Errore: "Permessi insufficienti"

Causa: Token senza permessi necessari

Soluzione: Rigenera token includendo:

ads_management (gestione completa)
ads_read (minimo per lettura)
read_insights (per metriche)

❌ Errore: "Invalid parameter (subcode 1815857)"

Causa: Manca bid_amount per LINK_CLICKS

Soluzione: Aggiungi bid_amount in centesimi (es. 100 = €1.00)

❌ Errore: "Cannot set budget (subcode 1885621)"

Causa: Campagna ha già budget, non puoi specificarlo anche nell'ad set

Soluzione: Ometti daily_budget/lifetime_budget dall'ad set

❌ Errore: "Advantage audience required (subcode 1870227)"

Causa: Manca targeting_automation.advantage_audience

Soluzione: Aggiungi al targeting:

"targeting_automation": {
  "advantage_audience": 0  // o 1
}

❌ Errore: "Rate limit raggiunto (429)"

Causa: Troppe richieste API in poco tempo

Soluzione: Attendi 5-10 minuti prima di riprovare

📚 Risorse Utili

🤝 Contributi

Contributi, issues e feature requests sono benvenuti!

Fork del progetto
Crea il tuo feature branch (git checkout -b feature/AmazingFeature)
Commit delle modifiche (git commit -m 'Add some AmazingFeature')
Push al branch (git push origin feature/AmazingFeature)
Apri una Pull Request

📄 Licenza

Questo progetto è rilasciato sotto licenza MIT. Vedi il file LICENSE per i dettagli.

🙏 Riconoscimenti

Basato su Meta Marketing API v21.0
Costruito con FastMCP
Validazione con Pydantic v2

⭐ Se questo progetto ti è utile, lascia una stella su GitHub!

Как установить

Добавь это в claude_desktop_config.json и перезапусти Claude Desktop.

{
  "mcpServers": {
    "meta-ads-mcp-server": {
      "command": "npx",
      "args": []
    }
  }
}