Glowe Pinterest MCP

Публичный загрузчик Pinterest, который можно использовать двумя способами: CLI для людей и MCP-сервер stdio для ИИ-агентов. Ядро едино: CLI и MCP получают одинаковые результаты, применяют одинаковые проверки URL и скачивают только в настроенную локальную папку.

Используйте только те материалы, на которые у вас есть необходимые права. Этот проект читает публичные данные, отдаваемые Pinterest: это ни официальный API Pinterest, ни способ обойти вход, платный доступ или ограничение контента.

Что делает проект

• Разрешает ссылки на Пины Pinterest и короткие ссылки pin.it.

• Ищет публичные Пины по ключевым словам.

• Извлекает заголовок, описание, URL пина и публично доступные медиа: изображения, GIF, видео.

• Пробует изображение originals, затем варианты 1200x, 736x и т. д., если Pinterest не отдаёт лучшую версию.

• Скачивает атомарно: файл .part, финальное переименование, без перезаписи существующих файлов.

• Отклоняет переходы и URL медиа вне pinterest.*, pin.it и разрешённых CDN *.pinimg.com.

Для поиска используется публичный структурированный ресурс, отдаваемый Pinterest, с прозрачным HTML-запасным вариантом, если он станет недоступен. Без входа Pinterest может отдавать только первую порцию результатов: это не гарантированная пагинация, и не стоит использовать её для выгрузки полных коллекций.

Related MCP server: pinterest-mcp

Локальная установка

Требуется Node 20 или новее.

cd tools/pinterest-mcp
npm install

Явно укажите выходную папку:

export PINTEREST_MCP_DOWNLOAD_DIR="$PWD/downloads"

По умолчанию медиа ограничены 35 МиБ. Меняйте лимит только при необходимости:

export PINTEREST_MCP_MAX_MEDIA_BYTES=52428800

CLI — для людей

Все команды принимают --json для вывода, пригодного для обработки скриптами.

# 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

Команды download и search-download никогда не берут путь вывода из URL или удалённого ответа. Имена файлов нормализуются, а при конфликтах создаётся суффикс, а не перезапись.

MCP — для ИИ-агентов

Запустите сервер напрямую:

PINTEREST_MCP_DOWNLOAD_DIR="$PWD/downloads" npm run mcp

Он использует stdio: ни порта, ни ключа Pinterest, ни журнала приложения в stdout. Ошибки и диагностика запуска остаются в stderr, чтобы не нарушать протокол MCP.

Пример локальной конфигурации 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"

После изменения конфигурации перезапустите клиент MCP/Codex, чтобы он перезапустил процесс. Для любого другого — используйте ту же команду node, тот же абсолютный аргумент и те же переменные окружения.

Контракт инструментов MCP

Читательские инструменты имеют аннотацию MCP readOnlyHint. Инструменты, которые пишут на диск, объясняют в описании, что требуется подтверждение пользователя. Агент всегда должен отдавать предпочтение такой последовательности: pinterest_search → показать источники → pinterest_get_pin → подтверждение → pinterest_download.

Пример ответа MCP

pinterest_get_pin возвращает структурированный JSON со следующим:

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

Агент не должен выдумывать доступность медиафайлов: он опирается на media, а затем сообщает о каждом успешном или неудачном скачивании отдельно.

Тесты и контроль качества

# 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

Сетевой тест намеренно вынесен отдельно: Pinterest может изменить публичный HTML или сделать Пин в названием недоступным. Он не должен никогда маскироваться обычными юнит-тестами.

Вдохновение и технический выбор

Дизайн вдохновлён MIT-проектами pinterest-downloader (приоритет originals и каскад качества) и PinterestDownloader. Интерфейс MCP вдохновлён mcp-pinterest, но здесь используется собственная реализация, и она — без headless-браузера — намеренно более ограничена визуально и функционально на скачивание.

Для Пинов и досок, принадлежащих подключённому аккаунту Pinterest, используйте официальный API Pinterest и OAuth. Условия Pinterest и авторские права применяются к любому скачанному контенту.