Glowe Pinterest MCP

A public Pinterest downloader, usable two ways: a CLI for humans and a stdio MCP server for AI agents. The core is unique: the CLI and the MCP therefore get the same results, apply the same URL validations, and download only into a configured local folder.

Only use content for which you hold the necessary rights. This project reads public data served by Pinterest: it is neither an official Pinterest API, nor a way to bypass a login, a paywall, or a content restriction.

What the project does

• Resolves Pinterest Pin links and pin.it short links.

• Searches public Pins by keywords.

• Extracts the title, description, Pin URL, and the publicly exposed image/GIF/video media.

• Tries the originals image, then the 1200x, 736x, etc. variants when Pinterest does not serve the best version.

• Downloads atomically: .part file, final rename, without overwriting an existing file.

• Rejects redirects and media URLs outside of pinterest.*, pin.it, and the allowed *.pinimg.com CDNs.

The search uses Pinterest’s structured public resource, with a transparent HTML fallback if it becomes unavailable. Pinterest may only return a first batch of results without a login: this is not guaranteed pagination and should not be used to scrape complete boards.

Related MCP server: pinterest-mcp

Local installation

Node 20 or newer is required.

cd tools/pinterest-mcp
npm install

Explicitly choose the output folder:

export PINTEREST_MCP_DOWNLOAD_DIR="$PWD/downloads"

Media is limited to 35 MiB by default. Adjust only if necessary:

export PINTEREST_MCP_MAX_MEDIA_BYTES=52428800

CLI — for humans

All commands accept --json for script-friendly output.

# 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

The download and search-download commands never take an output path from a URL or remote response. File names are normalized and collisions produce a suffix rather than an overwrite.

MCP — for AI agents

Run the server directly:

PINTEREST_MCP_DOWNLOAD_DIR="$PWD/downloads" npm run mcp

It uses stdio: no port, no Pinterest key, and no application logs on stdout. Errors and startup diagnostics remain on stderr, so as not to corrupt the MCP protocol.

Example Codex local configuration (~/.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"

After modifying the configuration, restart the MCP/Codex client so it relaunches the process. For any other MCP client, use the same node command, the same absolute argument, and the same environment variables.

MCP tool contract

The read tools carry the MCP readOnlyHint annotation. The tools that write to disk explain in their description that user confirmation is required. An agent should always prefer this sequence: pinterest_search → show the selection → pinterest_get_pin → confirmation → pinterest_download.

Example MCP response

pinterest_get_pin returns structured JSON that notably includes:

{
  "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"]
    }
  ]
}

The agent must not invent the availability of a media: it relies on media, then reports each successful or failed download separately.

Tests and quality assurance

# 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

The network test is intentionally separated: Pinterest may modify its public HTML or make a Pin unavailable. It must never be masked by the unit tests.

Inspirations and technical choices

The design is inspired by the MIT projects pinterest-downloader (originals priority and quality cascade) and PinterestDownloader (structured Pin/search contracts). The MCP interface is inspired by mcp-pinterest, but the implementation here is standalone, without a headless browser, with a purposely more restrictive download surface.

For Pins and boards belonging to the connected Pinterest account, prefer the official Pinterest API and OAuth. Pinterest terms and copyright still apply to any downloaded content.