Glowe Pinterest MCP

公開Pinterestダウンローダーで、2つの方法で利用できます。人間向けのCLIと、AIエージェント向けのstdio MCPサーバーです。中核は共通です。CLIとMCPは同じ結果を得て、同じURL検証を適用し、設定されたローカルフォルダにのみダウンロードします。

必要な権利を持つコンテンツのみを使用してください。このプロジェクトはPinterestが公開する公開データを読み取ります。これはPinterestの公式APIでも、ログイン、ペイウォール、コンテンツ制限を回避する手段でもありません。

このプロジェクトの機能

• PinterestのPinリンクとpin.it短縮リンクを解決します。

• キーワードで公開ピンを検索します。

• タイトル、説明、ピンのURL、公開されている画像/GIF/動画メディアを抽出します。

• まずoriginals画像を試し、Pinterestが最適なバージョンを提供しない場合は1200x、736xなどのバリアントを試します。

• ローカルをアトミックに実行します: .partファイル、最終リネーム、既存ファイルを上書きしません。

• pinterest.*、pin.it、許可されたCDN *.pinimg.com の外へのリダイレクトおよびメディアURLを拒否します。

検索は、Pinterestが提供する構造化された公開リソースを使用し、利用できなくなった場合に備えて、透過的なHTMLフォールバックを使用します。Pinterestは、ログインなしで最初の結果のみを提供する場合があります。これは保証されたページネーションではなく、完全なテーブルを吸い出すために使用すべきではありません。

Related MCP server: pinterest-mcp

ローカルインストール

Node.js 20以降が必要です。

cd tools/pinterest-mcp
npm install

出力フォルダを明示的に選択します：

export PINTEREST_MCP_DOWNLOAD_DIR="$PWD/downloads"

メディアはデフォルトで35 MiBに制限されています。必要な場合のみ調整します：

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クライアントを再起動してプロセスを再起動します。他の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を変更したり、ピンを利用できなくしたりする可能性があるためです。ユニットテストによって上書きされてはなりません。

インスピレーションと技術的選択

デザインはMITプロジェクト pinterest-downloader(originals 優先と品質カスケード) と PinterestDownloader（構造化されたPin/検索契約）に影響を受けています。MCPインターフェースは mcp-pinterest から着想を得ていますが、ここの実装は独立しており、ヘッドレスブラウザなしで、より制限的なダウンロード面を持つように設計されています。

ログインしたPinterestアカウントが所有するピンやボードについては、公式のPinterest API とOAuthを使用してください。Pinterestの規約および著作権は、ダウンロードされるすべてのコンテンツに引き続き適用されます。