meta-mcp-py

Serveur MCP en Python pour Meta Business : Facebook Pages, Instagram et Threads. Lecture des statistiques et publication de contenu, directement depuis Claude.

Gratuit et sans intermédiaire : le serveur tape la Graph API de Meta, qui est gratuite. Ton token reste chez toi et n'est envoyé qu'à graph.facebook.com et graph.threads.net.

Points clés

• 56 outils couvrant Pages, Instagram, Threads, statistiques, audiences et publication

• Garde-fou d'écriture : sans META_ENABLE_WRITES=true, aucune publication ni suppression n'est possible — impossible de poster par accident

• Aucune donnée envoyée à un tiers : pas de télémétrie, pas de service externe

• Entièrement typé, testé (pytest), vérifié (ruff, mypy strict)

• Compatible SDK MCP v1 et v2 (couche de compatibilité interne)

Related MCP server: Social Analytics MCP Server

Installation

git clone https://github.com/mathieubernardi/Meta_Business_MCP.git
cd Meta_Business_MCP
python -m venv .venv
source .venv/bin/activate      # Windows : .venv\Scripts\activate
pip install -e ".[dev]"
cp .env.example .env           # puis remplis META_ACCESS_TOKEN

Configuration dans Claude

Ajoute ce bloc à ta configuration MCP :

{
  "mcpServers": {
    "meta": {
      "command": "python",
      "args": ["-m", "meta_mcp"],
      "cwd": "/chemin/vers/meta-mcp-py",
      "env": {
        "META_ACCESS_TOKEN": "ton_token_longue_duree",
        "THREADS_ACCESS_TOKEN": "",
        "META_ENABLE_WRITES": "false"
      }
    }
  }
}

THREADS_ACCESS_TOKEN est optionnel : à ne renseigner que si ton token Threads diffère du token Meta principal. Sans lui, les outils Threads réutilisent META_ACCESS_TOKEN.

Obtenir un token (gratuit, une seule fois)

1. Crée une app sur https://developers.facebook.com/apps (type Business).

2. Ouvre le Graph API Explorer.

3. Ajoute les permissions en lecture seule : pages_read_engagement, pages_show_list, read_insights, instagram_basic, instagram_manage_insights. Pour publier, ajoute pages_manage_posts et instagram_content_publish. Pour les audiences publicitaires, ajoute ads_management.

4. Échange le token court contre un token longue durée (~60 jours) :

   curl "https://graph.facebook.com/v21.0/oauth/access_token?grant_type=fb_exchange_token&client_id=APP_ID&client_secret=APP_SECRET&fb_exchange_token=TOKEN_COURT"

Ton compte Instagram doit être Business/Créateur et rattaché à la Page.

Démarrage rapide

Une fois branché, demande simplement :

1. health_check — vérifie la configuration

2. list_pages — récupère l'ID de ta Page

3. account_summary — bilan Facebook + Instagram sur 30 jours

Outils disponibles

Diagnostic

health_check · token_permissions · token_info · graph_get

Facebook Pages (lecture)

list_pages · get_page · list_page_posts · get_post · list_post_comments get_page_insights · get_post_insights

Instagram (lecture)

find_instagram_account · get_ig_account · list_ig_media · get_ig_media get_ig_media_insights · get_ig_account_insights · get_ig_audience_demographics list_ig_stories · get_ig_story_insights · list_ig_comments

Threads (lecture)

get_threads_profile · list_threads_posts · get_threads_insights

Analyse

account_summary · top_ig_posts · follower_growth

Audience organique — aucun compte publicitaire requis

get_page_audience · audience_overview

Qui sont tes abonnés : répartition par pays, ville, âge/genre et langue. audience_overview renvoie le top 5 de chaque catégorie en un appel.

Meta n'agrège pas ces données tant que l'audience est trop petite : sur une page jeune, attends-toi à un résultat vide et un champ note explicatif.

Audiences publicitaires — nécessite ads_management + compte publicitaire

list_ad_accounts · list_custom_audiences · get_custom_audience create_custom_audience · add_users_to_audience · remove_users_from_audience create_lookalike_audience · delete_custom_audience

Les données personnelles (email, téléphone, nom) sont normalisées puis hachées en SHA-256 localement avant tout envoi : Meta ne reçoit jamais de donnée en clair.

RGPD : constituer une audience à partir de données clients suppose une base légale et une information préalable des personnes. remove_users_from_audience permet de traiter une demande d'opposition ou d'effacement.

Publication — nécessite META_ENABLE_WRITES=true

publish_page_post · publish_page_photo · publish_page_carousel publish_page_photo_from_file · publish_page_carousel_from_files publish_page_video_from_file delete_page_post · reply_to_comment · ig_publish_image · ig_publish_carousel ig_publish_image_from_file · ig_publish_carousel_from_files ig_publish_reel · ig_publish_reel_from_file · ig_container_status ig_reply_to_comment · ig_delete_comment ig_publishing_limit · publish_thread

Les outils _from_file(s) téléversent des fichiers locaux (upload multipart) au lieu de nécessiter des URLs publiques. Pour Instagram, l'astuce consiste à téléverser chaque photo en non publiée sur la Page Facebook liée (page_id) : Meta lui attribue quand même une URL CDN publique, réutilisée pour construire l'image ou le carrousel Instagram — sans aucun hébergement externe.

Vidéo

publish_page_video_from_file publie un MP4 local sur la Page Facebook (description sert de légende). Avec published=False, la vidéo est téléversée sans apparaître dans le fil. Avec scheduled_publish_time (horodatage Unix UTC, entre 10 minutes et 6 mois dans le futur), Meta la publie à l'heure dite — la machine locale n'a pas besoin d'être allumée à ce moment-là.

⚠️ Instagram n'a pas d'équivalent : l'API Content Publishing ne connaît aucune programmation, un reel part à l'instant où ig_publish_reel* est appelé. Pour programmer côté Instagram, il faut passer par Meta Business Suite ou déclencher l'outil à l'heure voulue.

ig_publish_reel_from_file applique aux vidéos la même astuce que pour les photos : le MP4 est téléversé non publié sur la Page liée, son URL source est réutilisée pour l'ingestion du reel, puis la vidéo intermédiaire est supprimée (keep_fb_video=True pour la conserver). Deux limites à connaître :

• l'upload direct est plafonné à MAX_DIRECT_UPLOAD_BYTES (200 Mo) ; au-delà, Meta impose son protocole d'upload repris, non implémenté ici ;

• l'encodage d'un reel est lent — l'attente va jusqu'à 5 minutes, après quoi l'outil renvoie le container_id à surveiller avec ig_container_status.

Instagram attend un reel en 9:16. Une vidéo 4:5 ou carrée est acceptée mais recadrée ou encadrée à l'affichage.

Sécurité

Le mode écriture est désactivé par défaut. C'est volontaire : un assistant qui peut publier ou supprimer sans filet est un risque réel. Deux niveaux de protection :

1. META_ENABLE_WRITES doit valoir true explicitement.

2. Le token lui-même doit porter les permissions de publication.

Tant que l'un des deux manque, rien ne peut être publié ni supprimé.

Développement

pytest              # tests
ruff check src tests
mypy src

Notes

Les noms de métriques Meta évoluent d'une version d'API à l'autre. Ils sont regroupés dans src/meta_mcp/constants.py — un seul endroit à ajuster. Les outils de statistiques renvoient un champ errors listant les métriques indisponibles plutôt que d'échouer complètement.

Licence

MIT — voir LICENSE.