Glowe Pinterest MCP

공개 Pinterest 다운로더로, 두 가지 방식으로 사용할 수 있습니다: 인간을 위한 CLI와 AI 에이전트를 위한 stdio MCP 서버가 그것입니다. 핵심은 하나입니다. 따라서 CLI와 MCP는 동일한 데이터를 얻고, 동일한 URL 검증을 적용하며, 설정된 로컬 디렉터리에만 다운로드를 수행합니다.

필요한 권한을 보유한 콘텐츠만 사용하세요. 이 프로젝트는 Pinterest가 제공하는 공개 데이터를 읽습니다: 공식 Pinterest API도 아니고, 로그인, 유료 장벽 또는 콘텐츠 제한을 우회하기 위한 방법도 아닙니다.

프로젝트의 기능

• Pinterest Pin 링크와 pin.it 단축 링크를 해석합니다.

• 공개 Pin을 키워드로 검색합니다.

• 공개적으로 노출된 이미지/GIF/비디오 미디어 및 Pin의 제목, 설명, URL을 추출합니다.

• Pinterest가 최고 품질 이미지를 제공하지 않는 경우 originals 이미지를 먼저 시도한 후 1200x, 736x 등의 변형을 시도합니다.

• 원자적으로 다운로드합니다: .part 파일, 최종 이름 변경, 기존 파일을 덮어쓰지 않음.

• pinterest.*, pin.it 및 허용된 *.pinimg.com CDN 외부의 리다이렉션과 미디어 URL을 거부합니다.

검색은 Pinterest가 렌더링하는 공개 데이터 구조를 사용하며, 데이터를 사용할 수 없게 되면 처리되는 HTML 폴백으로 전환합니다. Pinterest는 로그인 없이 첫 번째 결과 일부만 렌더링할 수 있습니다: 이는 보장된 페이지네이션이 아니며, 전체 표를 수집하는 데 사용해서는 안 됩니다.

Related MCP server: pinterest-mcp

로컬 설치

필요한 Node 20 이상이 필요합니다.

cd tools/pinterest-mcp
npm install

출력 폴더를 명시적으로 선택하세요:

export PINTEREST_MCP_DOWNLOAD_DIR="$PWD/downloads"

미디어는 기본적으로 35MiB로 제한됩니다. 필요한 경우에만 조정하세요:

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 — AI 에이전트용

서버를 직접 실행하세요:

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 클라이언트를 다시 시작하여 프로세스를 다시 시작하게 하세요. 다른 MCP 클라이언트도 동일한 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을 변경하거나 Pin을 낸할 수 있기 때문입니다. 유닛 테스트로 가려져서는 안 됩니다.

영감과 기술적 선택

디자인은 MIT 프로젝트 pinterest-downloader (originals 우선 및 품질 캐스케이드)와 PinterestDownloader (구조화된 Pin/검색 계약)에서 영감을 받았습니다. MCP 인터페이스는 mcp-pinterest에서 영감을 받았지만, 여기의 구현은 headless 브라우저 없이 자체적으로 작성되었으며 의도적으로 더 제한된 다운로드 면을 가집니다.

로그인한 Pinterest 계정 소유의 Pin 및 데이터는 공식 Pinterest API와 OAuth를 사용하는 것을 권장합니다. Pinterest 이용 약관과 저작권은 다운로드된 모든 콘텐츠에 적용됩니다.