Glowe Pinterest MCP

Un downloader Pinterest public, utilisable de deux façons : une CLI pour les humains et un serveur MCP stdio pour les agents IA. Le cœur est unique : la CLI et le MCP obtiennent donc les mêmes résultats, appliquent les mêmes validations d’URL et téléchargent uniquement dans un dossier local configuré.

Utiliser seulement les contenus pour lesquels vous détenez les droits nécessaires. Ce projet lit les données publiques rendues par Pinterest : ce n’est ni une API Pinterest officielle, ni une manière de contourner une connexion, un paywall ou une restriction de contenu.

Ce que le projet fait

• Résout les liens de Pins Pinterest et les liens courts pin.it.
• Recherche des Pins publics par mots-clés.
• Extrait le titre, la description, l’URL du Pin et les médias image/GIF/vidéo exposés publiquement.
• Essaie l’image originals, puis les variantes 1200x, 736x, etc. si Pinterest ne sert pas la meilleure version.
• Télécharge de manière atomique : fichier .part, renommage final, sans écraser un fichier existant.
• Refuse les redirections et URLs médias hors de pinterest.*, pin.it et des CDN *.pinimg.com autorisés.

La recherche utilise la ressource publique structurée rendue par Pinterest, avec un fallback HTML transparent si elle devient indisponible. Pinterest peut ne rendre qu’une première tranche de résultats sans connexion : ce n’est pas une pagination garantie et il ne faut pas l’utiliser pour aspirer des tableaux complets.

Installation locale

Node 20 ou plus récent est requis.

cd tools/pinterest-mcp
npm install

Choisissez explicitement le dossier de sortie :

export PINTEREST_MCP_DOWNLOAD_DIR="$PWD/downloads"

Les médias sont limités à 35 MiB par défaut. Ajuster seulement si nécessaire :

export PINTEREST_MCP_MAX_MEDIA_BYTES=52428800

CLI — pour les humains

Toutes les commandes acceptent --json pour une sortie exploitable par script.

# Rechercher des références, sans écrire de fichier
npm run cli -- search "coiffure bob femme" --limit 8

# Charger la page suivante avec le nextCursor renvoyé par la recherche précédente
npm run cli -- search "coiffure bob femme" --limit 8 --cursor "CURSEUR_RENVOYÉ"

# Inspecter exactement ce qu’un Pin expose avant de télécharger
npm run cli -- inspect "https://pin.it/EXEMPLE" --json

# Télécharger un ou plusieurs Pins dans un dossier local contrôlé
npm run cli -- download "https://www.pinterest.com/pin/99360735500167749/" --output ./downloads

# Éviter les vidéos lorsque seules les images intéressent le workflow
npm run cli -- download "https://www.pinterest.com/pin/99360735500167749/" --no-video

# Recherche suivie d’un téléchargement : à employer seulement après validation du volume
npm run cli -- search-download "hairstyle editorial" --limit 5 --output ./downloads

Les commandes download et search-download ne prennent jamais un chemin de sortie depuis une URL ou une réponse distante. Les noms de fichiers sont normalisés et les collisions produisent un suffixe plutôt qu’un écrasement.

MCP — pour les agents IA

Lancer le serveur directement :

PINTEREST_MCP_DOWNLOAD_DIR="$PWD/downloads" npm run mcp

Il utilise stdio : aucun port, aucune clé Pinterest et aucun journal applicatif sur stdout. Les erreurs et diagnostics de démarrage restent sur stderr, afin de ne pas corrompre le protocole MCP.

Exemple de configuration locale Codex (~/.codex/config.toml) :

[mcp_servers.glowe_pinterest]
command = "node"
args = ["/CHEMIN_ABSOLU/glowe/tools/pinterest-mcp/bin/mcp-server.mjs"]

[mcp_servers.glowe_pinterest.env]
PINTEREST_MCP_DOWNLOAD_DIR = "/CHEMIN_ABSOLU/pinterest-downloads"
PINTEREST_MCP_MAX_MEDIA_BYTES = "36700160"

Après modification de la configuration, redémarrer le client MCP/Codex afin qu’il relance le processus. Pour tout autre client MCP, utilisez la même commande node, le même argument absolu et les mêmes variables d’environnement.

Contrat des outils MCP

Outil	Écrit sur disque	Usage agent recommandé
pinterest_search	Non	Chercher et présenter des références avant toute action ; réutiliser nextCursor pour la page suivante lorsqu’il est présent.
pinterest_get_pin	Non	Vérifier un lien pinterest.com ou pin.it, ses médias et ses métadonnées.
pinterest_download	Oui	Demander confirmation, puis télécharger 1 à 20 Pins fournis.
pinterest_search_and_download	Oui	Utiliser uniquement après confirmation explicite du nombre de résultats.
pinterest_status	Non	Vérifier le dossier local et les limites en vigueur.

Les outils de lecture portent l’annotation MCP readOnlyHint. Les outils qui écrivent sur disque expliquent dans leur description qu’une confirmation de l’utilisateur est requise. Un agent doit toujours privilégier cette séquence : pinterest_search → montrer la sélection → pinterest_get_pin → confirmation → pinterest_download.

Exemple de réponse MCP

pinterest_get_pin renvoie un JSON structuré contenant notamment :

{
  "id": "99360735500167749",
  "pinUrl": "https://www.pinterest.com/pin/99360735500167749/",
  "title": "…",
  "media": [
    {
      "type": "image",
      "url": "https://i.pinimg.com/originals/...jpg",
      "alternatives": ["https://i.pinimg.com/1200x/...jpg"]
    }
  ]
}

L’agent ne doit pas inventer la disponibilité d’un média : il s’appuie sur media, puis rapporte séparément chaque téléchargement réussi ou échoué.

Tests et contrôle qualité

# Tests déterministes : URLs, parsing SSR, repli qualité, écriture atomique, handshake MCP
npm test

# Vérification réseau explicite : recherche réelle, extraction d’un Pin, téléchargement CDN réel
npm run test:live

Le test réseau est volontairement séparé : Pinterest peut modifier son HTML public ou rendre un Pin indisponible. Il ne doit jamais être masqué par les tests unitaires.

Inspirations et choix techniques

Le design s’inspire des projets MIT pinterest-downloader (priorité originals et cascade de qualité) et PinterestDownloader (contrats structurés Pin/recherche). L’interface MCP s’inspire de mcp-pinterest, mais l’implémentation ici est autonome, sans navigateur headless, avec une surface de téléchargement volontairement plus restrictive.

Pour les Pins et boards appartenant au compte Pinterest connecté, préférer l’API Pinterest officielle et OAuth. Les conditions Pinterest et les droits d’auteur restent applicables à tout contenu téléchargé.