Ads Uploader

Documentation

MCP, CLI et API

Configuration du MCP

Le MCP (Model Context Protocol) est une façon standard pour les applications d'IA d'utiliser des outils externes. Le serveur MCP d'Ads Uploader donne à ton agent IA les mêmes fonctions que celles qu'utilise le CLI : parcourir les comptes, campagnes, ensembles de publicités et annonces, téléverser des médias, enregistrer des préréglages, travailler avec les builds enregistrés, prévisualiser un build et créer des annonces. Si tu connais l'application web ou le CLI, les outils MCP suivent exactement le même flux de travail.

L'accès au MCP est réservé aux forfaits payants et n'est pas disponible pendant l'essai. Il utilise le même compte et la même connexion Meta que l'application web et le CLI, et il est désactivé dès que l'accès au CLI est désactivé pour un compte.

CLI ou MCP ?

Les deux tournent sur la même infrastructure, c'est donc un choix de flux de travail, pas de fonctionnalités. Le CLI convient mieux quand tu veux faire tourner toute ton activité via un agent IA : téléversements en masse depuis ton disque, lancements répétés et builds complets assemblés depuis le terminal.

Le MCP convient mieux aux tâches ciblées où l'application web reste dans la boucle. Par exemple :

  • Téléverse et vérifie tous tes médias dans l'uploader web, puis confie le build à l'agent pour une seule étape
  • Laisse l'agent mettre en place la configuration de l'ensemble de publicités
  • Laisse l'agent rédiger ou réécrire le texte de tes annonces
  • Associe le texte d'annonces d'un tableur aux noms de fichiers de tes téléversements

Les builds enregistrés relient les deux. L'uploader web, le CLI et le MCP utilisent tous les mêmes références de build, donc un build peut passer de l'un à l'autre sans que personne n'ait à le ressaisir. Consulte Builds enregistrés.

Connecter une application de chat (Claude, ChatGPT, Cursor)

Utilise le serveur hébergé quand tu travailles depuis une application de chat et que tu veux te connecter via ton navigateur. Ajoute cette URL comme connecteur personnalisé dans ton application :

https://adsuploader.com/api/mcp

Par exemple, dans Claude, va dans Settings > Connectors > Add custom connector. ChatGPT et Cursor prennent aussi en charge les connecteurs MCP personnalisés. Une fois le connecteur ajouté, termine la connexion à Ads Uploader et l'écran de consentement dans ton navigateur. Il n'y a aucun jeton à copier ou coller. Pour vérifier que tout fonctionne, demande à ton agent de lister tes comptes publicitaires.

Se connecter avec une clé API (pour tes propres agents et scripts)

La connexion OAuth est la méthode normale pour relier une app d'IA comme Claude ou ChatGPT. Utilise une clé API pour les connexions de longue durée de tes propres agents et scripts quand la connexion dans un navigateur n'est pas pratique. Crée-la sous Account > MCP, CLI & API. Chaque clé est réservée à une personne. Consulte Clés API pour la création, l'utilisation et la révocation.

Envoie Authorization: Bearer adk_... à https://adsuploader.com/api/mcp. Pour un client MCP qui accepte les en-têtes personnalisés, la configuration peut ressembler à ceci :

{
  "mcpServers": {
    "ads-uploader": {
      "url": "https://adsuploader.com/api/mcp",
      "headers": { "Authorization": "Bearer adk_..." }
    }
  }
}

Connecter un agent de code (Claude Code, Claude Desktop, Cursor)

Les agents de code peuvent utiliser le même serveur hébergé. Dans Claude Code, lance :

claude mcp add --transport http ads-uploader https://adsuploader.com/api/mcp

Dans les autres agents, ajoute https://adsuploader.com/api/mcp comme serveur MCP distant et termine la connexion dans le navigateur quand on te le demande. Si ton agent ne prend en charge que les serveurs locaux (stdio), fais le pont vers le serveur hébergé avec npx mcp-remote https://adsuploader.com/api/mcp.

Faire tourner le serveur sur ton propre ordinateur

Tu peux aussi faire tourner le serveur MCP en local. C'est utile quand tu veux que l'agent téléverse des fichiers directement depuis ton disque. Il nécessite Node.js 18 ou plus récent :

npm install -g @adsuploader/cli @adsuploader/mcp
ads login

Ajoute ensuite la commande ads-mcp aux paramètres MCP de ton agent :

{
  "mcpServers": {
    "ads-uploader": {
      "command": "ads-mcp"
    }
  }
}

Le serveur local utilise la connexion enregistrée par ads login. Il n'ouvre pas de navigateur lui-même, donc relance ads login quand cette connexion expire (au bout de 30 jours).

Ce que ton agent peut faire

Le serveur donne à ton agent des outils pour tout le flux de travail d'un build. Tu décris ce que tu veux en langage courant, et l'agent appelle les outils pour toi.

DomaineCe que l'agent peut faire
IdentitéConfirmer sous quel utilisateur Ads Uploader il est connecté avant de modifier quoi que ce soit
ComptesLister tes comptes publicitaires Meta et passer le bon accountId à chaque appel
ExplorationLister les campagnes, ensembles de publicités, annonces et Pages ; lire tous les paramètres créatifs d'une annonce
CiblageRechercher les clés de villes, les zips/codes postaux et les ID de ciblage avancé avec ads_search_targeting, pour ne jamais avoir à les deviner
PréréglagesLister les préréglages API et de texte enregistrés, lire un préréglage avec ads_get_preset, et enregistrer une annonce existante comme préréglage
BuildsLister, lire, enregistrer, mettre à jour et supprimer des builds enregistrés, ou en copier un dans un nouveau brouillon avec ads_fork_build pour que l'original reste intact. Chaque build est fourni avec un lien qui l'ouvre dans l'uploader web.
MédiasTéléverser des images et des vidéos dans ton compte publicitaire et lister les lots de téléversement récents
AperçuMontrer exactement ce qui serait créé avant que quoi que ce soit ne soit fait
CréationCréer des annonces à partir d'un préréglage, d'une annonce copiée, d'un build enregistré ou d'une spécification complète, puis suivre ou annuler la tâche
Duplication par ID de publicationPrévisualiser une duplication par ID de publication avec ads_duplicate_by_post_preview, la lancer avec ads_duplicate_by_post, et la suivre avec ads_get_duplication

Prévisualise d'abord. Sur le serveur hébergé, ads_create suit la tâche pendant environ 60 secondes. Si la tâche tourne encore, il renvoie la référence de la tâche et ton agent continue de la vérifier avec ads_get_job. La tâche elle-même tourne sur le serveur et ne dépend pas du maintien de la connexion. Sur le serveur local, ads_create peut suivre la tâche jusqu'à 30 minutes.

Travailler avec les builds enregistrés

Les builds s'enregistrent automatiquement pendant que tu travailles dans l'uploader web. Chacun a une référence durable (build_...), affichée en bas de l'étape de configuration et dans la fenêtre Saved Builds. Donne cette référence à ton agent et il peut lire la configuration exacte que tu vois, la modifier et l'enregistrer dans ce même build.

Si le build est ouvert dans l'uploader, celui-ci récupère la modification enregistrée et l'applique pour toi quand tu n'as pas de modifications non enregistrées. Tu peux aussi cliquer sur le bouton d'actualisation à côté de la référence du build pour vérifier tout de suite. Si tu as des modifications non enregistrées quand un changement externe arrive, l'uploader te demande s'il faut charger les changements externes ou garder les tiens, pour qu'aucune version ne soit perdue. Si l'onglet est fermé, demande le lien du build à l'agent.

Les éditeurs de texte par annonce et par ensemble de publicités de l'uploader web ont des boutons Claude et ChatGPT qui ouvrent une conversation avec la référence de ton build déjà remplie, donc confier une passe sur les textes ne prend qu'un clic. Ça marche aussi dans l'autre sens : demande à l'agent d'enregistrer son travail comme build, puis ouvre le lien pour tout vérifier dans le navigateur avant la création de la moindre annonce.

Téléverser des médias

La façon dont les fichiers arrivent dans ton compte publicitaire dépend de l'endroit où tourne le serveur :

  • Serveur hébergé (applications de chat et agents de code qui utilisent l'URL hébergée) : donne à l'agent des liens de téléchargement HTTPS publics, un lien public vers un fichier Google Drive, ou un lien public vers un dossier Drive. Ads Uploader télécharge et traite les fichiers en arrière-plan, donc les données des fichiers ne passent jamais par le chat.
  • Serveur local (ads-mcp) : l'agent peut aussi téléverser des fichiers directement depuis ton disque. Tu peux aussi utiliser le CLI avec ads upload pour les dossiers de ton ordinateur.

Une fois un téléversement par lien ou depuis Drive lancé, l'agent le vérifie avec ads_get_upload. Quand il est terminé, le résultat inclut le résumé du lot utilisé pour les aperçus et la création d'annonces. Pour arrêter un import non voulu, l'agent appelle ads_cancel_job ; les fichiers déjà terminés restent utilisables, et le résultat indique combien ont abouti, échoué ou été ignorés. Les images nommées *_thumbnail sont jointes à la vidéo correspondante comme miniatures personnalisées au lieu d'être comptées comme des médias séparés, donc le total de médias d'un dossier peut être inférieur à son nombre de fichiers. Si Google bloque un import de dossier pendant un moment, le résultat indique ce qui a abouti, échoué et été ignoré, pour que l'agent puisse te dire de réessayer plus tard.

Les liens Drive doivent être partagés en Anyone with the link (Viewer). Les fichiers Drive privés sont une fonctionnalité de l'uploader web.

Les petites images peuvent aussi être envoyées directement dans l'appel (jusqu'à 10 Mo au total par appel). Un agent de code capable d'envoyer lui-même des données de fichiers peut demander l'ancien chemin de téléversement direct, qui téléverse vers le stockage d'Ads Uploader. Seul ce chemin nécessite un accès sortant à notre hôte de téléversement. Si ton agent tourne dans un bac à sable réseau, autorise *.adsuploader.com dans la liste d'autorisation réseau ou du bac à sable de ton agent. La réponse de téléversement indique l'hôte exact dans allowlistHost ; s'il diffère un jour, fie-toi à la réponse.

Limites

  • 50 fichiers par appel de téléversement. Répartis les gros téléversements sur plusieurs appels.
  • Limites de requêtes. Les appels sont limités par utilisateur et par type d'appel sur une minute glissante (par exemple, 120 appels d'outils MCP par minute, et 20 par minute pour chaque type d'appel de liste ou d'aperçu). Un usage normal reste bien en dessous. Si ton agent atteint une limite, il reçoit une erreur "rate limit" et doit attendre avant de réessayer.
  • Une seule tâche de création d'annonces à la fois par utilisateur, comme avec le CLI.

Connexion et accès

Le serveur hébergé te connecte avec OAuth, le flux standard "se connecter et approuver". Le jeton d'accès qu'il émet dure une heure. Si ton application prend en charge les jetons d'actualisation, elle reçoit aussi un jeton d'actualisation valable 30 jours et l'utilise pour renouveler le jeton d'accès en arrière-plan, donc tu n'as pas à te reconnecter à chaque session. Sinon, l'application te demande de te reconnecter quand le jeton expire.

L'accès suit ton compte : il est réservé aux forfaits payants, et désactiver l'accès au CLI pour un compte lui retire aussi immédiatement l'accès au MCP.

Annonces de partenariat

Les outils MCP ads_preview et ads_create acceptent les mêmes spécifications de partenariat que le CLI :

  • Avec tes propres médias : ajoute profile.partnership.enabled: true avec les ID de ton partenaire à une spécification de médias normale. Tu peux définir un partenaire différent par annonce ou par ensemble de publicités.
  • À partir de publications Instagram existantes : importe une publication autorisée avec mediaItems[].kind: "partnershipPost".

L'aperçu montre le partenaire, l'approbation et le mode d'en-tête de chaque annonce, regroupés par ensemble de publicités. Pour les formats de spécification complets et les limites, consulte Annonces de partenariat avec tes propres médias et Spécification de partenariat à partir d'une publication Instagram existante.

Product Showcase

Product Showcase affiche des produits d’un catalogue sous une publicité avec une seule image ou vidéo. Les publicités de catalogue complet (dynamiques/DPA) ne sont pas encore prises en charge.

Les IDs doivent être des chaînes de chiffres. Les recommandations nécessitent des campagnes Ventes (OUTCOME_SALES) ; la sélection manuelle du catalogue et de l’ensemble fonctionne aussi avec d’autres objectifs. Product Showcase est indisponible pour les carrousels, formats flexibles, multimédias, publications existantes et publicités Partnership.

Consultez les catalogues et ensembles, puis demandez une recommandation :

  • ads_list_catalogs({ accountId })
  • ads_list_product_sets({ accountId, catalogId, productSetId? })
  • ads_get_product_showcase_recommendation({ accountId, adUrl, pageId?, pixelId? })

Create et Preview acceptent productShowcase: { enabled?, catalogId?, productSetId?, useRecommendation? } ; enabled vaut true par défaut. L’omission conserve la création source. RECOMMENDED utilise le choix Meta (choiceSource: "DEFAULT") ; MUST_PICK exige un ID candidat comme productSetId ("MANUAL"). MANUAL nécessite catalogue et ensemble. Un autre choix vérifié utilise "MANUAL".

Options Create et Preview : --product-showcase <on|off|recommended>, --catalog <id>, --product-set <id>. Les IDs seuls signifient on ; recommended active useRecommendation: true. Off donne { enabled: false }, refuse les IDs et conserve l’ensemble de l’annonce source.

Preview renvoie productShowcase avec enabled, IDs, nom facultatif, choiceSource et source (recommendation, manual, source_ad), ou null. Les recommandations sont en lecture seule. Test Mode exige des IDs si activé, ne consulte pas les catalogues et signale l’absence de vérification. Les choix enregistrés dans l’interface sont convertis ; les valeurs par défaut sont revérifiées au lancement.

←
Previous
Référence complète du CLI
Next
Ads Insights (Beta)
→