Meta Ads MCP

Serveur MCP self-hosted qui expose l'API Meta Marketing (Facebook/Instagram Ads) à Claude, pour analyser et piloter des comptes publicitaires clients directement depuis Claude Code / Claude Desktop.

Objectif

• Analyser des comptes clients : insights, campagnes, ad sets, ads, creatives, audiences

• Agir dessus : pause/resume, ajustement de budgets, création de campagnes (toujours en PAUSED par défaut)

• Multi-comptes : une base réutilisable pour plusieurs clients, un token par client

Pas de dépendance à un SaaS tiers (type Pipeboard) : le code appelle directement la Graph API Marketing de Meta via fetch natif, et reste 100% self-hosted.

Related MCP server: Meta Ads MCP Server

Stack

• TypeScript / Node.js 18+

• @modelcontextprotocol/sdk (SDK officiel Anthropic)

• Appels REST directs à la Graph API Marketing (v26.0 par défaut, configurable via META_API_VERSION)

• Transport MCP : stdio pour le dev local (Claude Code / Claude Desktop). Le code est structuré pour ajouter un transport Streamable HTTP plus tard, en vue d'un déploiement remote (Cloud Run ou équivalent).

État du projet

🚧 En cours de développement. Les 14 tools (7 lecture + 7 écriture) sont implémentés. Les tools de lecture sont testables via npm run test:manual ; les tools d'écriture ont été validés en mode preview contre un vrai compte (aucune mutation réelle testée en dehors d'une confirmation explicite de l'utilisateur).

Structure du projet

meta-ads-mcp/
  src/
    server.ts          # point d'entrée MCP
    client/
      meta-api.ts       # wrapper HTTP vers la Graph API Marketing
      auth.ts            # gestion des tokens (long-lived / System User)
    tools/
      read/               # tools de lecture (insights, campagnes, ...)
      write/              # tools d'écriture (pause, budgets, création, ...)
    config/
      accounts.ts         # mapping multi-comptes client -> ad_account_id/token
    types/
  test/
    manual-check.ts      # script de validation manuelle tool par tool
  .github/workflows/ci.yml
  .env.example
  accounts.config.json.example
  .mcp.json.example

Setup

1. Prérequis

• Node.js 18+

• Un compte développeur Meta (developers.facebook.com) avec une app configurée pour la Marketing API

• Accès à un Business Manager Meta

2. Installation

npm install
npm run build

3. Obtenir un token Meta

1. Crée une app sur developers.facebook.com et récupère META_APP_ID / META_APP_SECRET.

2. Génère un access token utilisateur avec les permissions ads_read, ads_management, business_management via l'Explorateur d'API Graph ou le flow OAuth complet.

3. Échange ce token contre un long-lived token (~60 jours) :

   GET /oauth/access_token
     ?grant_type=fb_exchange_token
     &client_id={META_APP_ID}
     &client_secret={META_APP_SECRET}
     &fb_exchange_token={SHORT_LIVED_TOKEN}

4. Recommandé pour la prod : crée un System User dans le Business Manager (Paramètres de l'entreprise > Utilisateurs > Utilisateurs système), assigne-lui les comptes publicitaires nécessaires, et génère un token System User — il n'expire pas et évite la gestion de renouvellement.

4. Configuration

cp .env.example .env
cp accounts.config.json.example accounts.config.json

Remplis .env avec tes identifiants Meta (voir tableau ci-dessous), puis déclare chaque client dans accounts.config.json (fichier ignoré par git — ne jamais le commiter s'il contient des tokens en clair). Ce fichier est mis en cache 30s en mémoire (src/config/accounts.ts) : ajouter un client n'exige pas de redémarrer le serveur, juste d'attendre jusqu'à 30s.

5. Connexion à Claude Code / Claude Desktop

Copie .mcp.json.example vers .mcp.json à la racine du projet (ou dans la config Claude Desktop équivalente) et adapte les variables d'environnement :

cp .mcp.json.example .mcp.json

Claude Code détecte automatiquement .mcp.json à la racine du repo. Pour Claude Desktop, ajoute la même entrée dans claude_desktop_config.json sous mcpServers.

Tools MCP disponibles

Lecture (priorité 1)

Champs pouvant revenir vides selon le volume/l'état du compte

• get_adsets.learning_phase (status, conversions, last_significant_edit) : Meta ne renseigne ces sous-champs que pendant que l'ad set délivre activement (effective_status: ACTIVE). Sur un ad set en pause (ou dont la campagne parente est en pause), ils reviennent à null — seul attribution_windows reste renseigné. status prend l'une des valeurs LEARNING / SUCCESS / FAIL d'après la documentation Meta v26.0 ; à date, ce repo n'a pas pu confirmer ces valeurs sur un ad set réellement en apprentissage (aucune campagne active sur le compte de test) — à vérifier dès qu'un client aura une campagne active.

• get_insights (niveau ad) .quality_ranking / .engagement_rate_ranking / .conversion_rate_ranking : reviennent à "UNKNOWN" en dessous d'environ 500 impressions sur l'ad — comportement confirmé en conditions réelles, ce n'est pas un bug du MCP.

• Aucun champ Meta n'expose la part d'impressions sur audience nouvelle vs déjà exposée (saturation d'audience) — recherché explicitement dans la référence Insights, non trouvé. Utiliser frequency comme proxy.

Écriture (priorité 2)

Règle de sécurité non négociable : aucun tool d'écriture n'exécute quoi que ce soit au premier appel. Chaque tool suit un pattern preview → confirm :

1. Appelé sans confirm: true, il renvoie un aperçu structuré (status: "preview_only") avec l'état actuel, le changement proposé, et — pour les budgets — le delta en % calculé automatiquement (avertissement si supérieur à BUDGET_CHANGE_CONFIRMATION_THRESHOLD_PERCENT, 20% par défaut). Aucun appel d'écriture n'est fait à la Graph API à ce stade.

2. Il faut un second appel explicite avec confirm: true pour que la mutation soit réellement exécutée.

Cette validation humaine systématique est non négociable, quel que soit le type ou l'ampleur de l'action. Elle est conçue pour rester compatible avec un futur mode Autopilot (UI séparée) : quand ce toggle sera actif, l'orchestrateur pourra passer confirm: true automatiquement pour les actions à faible risque, mais devra toujours exiger une confirmation explicite (modale) pour toute hausse de budget — cette exception ne peut pas être appliquée par le serveur MCP lui-même (il ne sait pas qui l'appelle), elle doit être respectée par la couche orchestratrice qui pilotera l'Autopilot.

Gestion des erreurs et rate limits

Meta limite à 200 appels/heure/utilisateur. Le client HTTP (src/client/meta-api.ts) implémente un retry avec backoff exponentiel sur les erreurs 429 et les codes d'erreur Meta 17, 32 et 613 (rate limit). Les erreurs API Meta remontent au niveau MCP sous forme de message clair, jamais de stack trace brute.

Tests manuels

npm run test:manual

Exécute chaque tool directement (hors transport MCP) et affiche le résultat, pour validation avant connexion à Claude Code en usage réel. Termine par un rapport de disponibilité des champs qui affiche explicitement ce qui revient null/UNKNOWN/MISSING sur le compte testé (phase d'apprentissage, diagnostics de pertinence) — c'est l'info utile pour savoir ce qui sera réellement exploitable par l'UI et l'analyste plus tard.

Développement

npm run dev     # lance le serveur via tsx (hot reload TS)
npm run build   # compile vers dist/
npm run lint    # ESLint
npm start       # lance la version compilée

Roadmap

• Scaffold du repo, CI, structure du projet

• Authentification Meta (résolution multi-comptes, long-lived token exchange, support System User)

• Retry / backoff et gestion d'erreurs Meta (codes 17, 32, 613, HTTP 429)

• Tools de lecture (7/7)

• Tools d'écriture (7/7) + garde-fou preview/confirm systématique

• Champs fondation pour l'UI/l'autopilot : learning_phase, timestamps ad set/ad, diagnostics de pertinence, business portfolio, cache config avec TTL (voir docs/AUDIT.md)

• Transport Streamable HTTP pour déploiement remote

• Persistance Neon (comptes, snapshots, insights journaliers, rapports, angles créatifs)

• Pipeline d'analyse autopilot (calcul déterministe, format JSON strict, règles anti-sur-optimisation, playbook versionné, planification)

• UI de pilotage (multi-comptes, plages de dates, sélection de métriques) — phase séparée, branchée sur ce MCP