Meta Ads MCP Server

Local setup required. This server has to be cloned and prepared on your machine before you register it in Claude Code.
1

Set the server up locally

Run this once to clone and prepare the server before adding it to Claude Code.

Run in terminal
git clone https://github.com/mikdeangelis/mcp-meta-ads.git
cd mcp-meta-ads
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
2

Register it in Claude Code

After the local setup is done, run this command to point Claude Code at the built server.

Run in terminal
claude mcp add -e "META_ACCESS_TOKEN=${META_ACCESS_TOKEN}" meta-ads-852b -- python "<FULL_PATH_TO_MCP_META_ADS>/dist/index.js"

Replace <FULL_PATH_TO_MCP_META_ADS>/dist/index.js with the actual folder you prepared in step 1.

Required:META_ACCESS_TOKEN
README.md

Complete MCP server to manage Facebook and Instagram advertising campaigns

🚀 Meta Ads MCP Server

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
  1. Vai su Facebook Developers
  2. My Apps → Create App → Business
  3. Completa i dettagli dell'app
2️⃣ Aggiungi Marketing API
  1. Dashboard app → trova Marketing API
  2. Clicca Set Up
  3. La Marketing API apparirà nel menu
3️⃣ Genera Token

Opzione A: Graph API Explorer (raccomandato)

  1. Vai su Graph API Explorer
  2. Seleziona la tua app
  3. Get User Access Token → Seleziona permessi:
    • ✅ ads_management (gestione completa)
    • ✅ ads_read (lettura)
    • ✅ read_insights (metriche)
  4. 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.fac

Tools (12)

meta_ads_list_accountsLists all advertising accounts associated with the user.
meta_ads_list_campaignsLists all campaigns for a specific account.
meta_ads_list_adsetsLists all ad sets for a specific campaign.
meta_ads_list_adsLists all ads for a specific ad set.
meta_ads_create_campaignCreates a new advertising campaign.
meta_ads_create_adsetCreates a new ad set within a campaign.
meta_ads_update_adset_targetingUpdates the targeting parameters for an existing ad set.
meta_ads_update_adset_budgetUpdates the daily budget for an ad set.
meta_ads_update_adset_statusActivates or pauses an ad set.
meta_ads_get_insightsRetrieves performance metrics like impressions, clicks, and spend.
meta_ads_get_creativeRetrieves details about ad creatives including text and images.
meta_ads_generate_reportGenerates a performance report with specific breakdowns.

Environment Variables

META_ACCESS_TOKENrequiredThe access token for the Meta Marketing API.

Configuration

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

Try it

→List all my active Meta ad accounts.
→Show me the performance insights for my campaign with ID 789 for the last 30 days.
→Create a new ad set in campaign 123 with a daily budget of 50 dollars.
→What are the current impressions and CTR for my latest ad set?
→Generate a report broken down by country for my main advertising account.

Frequently Asked Questions

What are the key features of Meta Ads?

Comprehensive performance reporting with custom date ranges. Full lifecycle management of campaigns, ad sets, and ads. Advanced targeting and budget modification tools. Detailed creative analysis and breakdown reporting. Pydantic-based automatic parameter validation.

What can I use Meta Ads for?

Automating daily performance reporting for marketing teams. Quickly adjusting ad set budgets based on real-time performance data. Managing targeting parameters across multiple ad sets via natural language. Auditing ad creative performance to optimize ROI.

How do I install Meta Ads?

Install Meta Ads by running: git clone https://github.com/mikdeangelis/mcp-meta-ads.git && cd mcp-meta-ads && python3 -m venv .venv && source .venv/bin/activate && pip install -r requirements.txt

What MCP clients work with Meta Ads?

Meta Ads works with any MCP-compatible client including Claude Desktop, Claude Code, Cursor, and other editors with MCP support.

Turn this server into reusable context

Keep Meta Ads docs, env vars, and workflow notes in Conare so your agent carries them across sessions.

Need the old visual installer? Open Conare IDE.
Open Conare
View all other servers →

Related MCP Servers

Nuclear
Free, open-source music player without ads or tracking.
other17.1K stars
Domain Check
Fast domain availability checker with RDAP/WHOIS lookup and batch checking.
other253 stars
Ableton MCP Extended
Control Ableton Live using natural language via AI assistants
other142 stars
US Government Open Data MCP
MCP Server + TypeScript SDK for 40+ U.S. Government APIs
other90 stars
Garmin Connect
Access your fitness, health, and training data from MCP clients.
other71 stars
BinjaLattice MCP
Secure communication protocol for Binary Ninja and MCP servers
other61 stars