Glowe Pinterest MCP

一个公共的 Pinterest 下载器，可以通过两种方式使用：仅供人类使用的 CLI，以及面向 AI 智能体的 stdio MCP 服务器。两者共用同一核心，因此 CLI 与 MCP 会得到相同的结果，执行相同的 URL 验证，并且只下载到配置好的本地文件夹中。

只使用您拥有必要权利的内容。本工具读取 Pinterest 公开返回的数据：它既不是 Pinterest 的官方 API，也不是绕过登录、付费墙或内容限制的方法。

项目功能

• 解析 Pinterest Pin 链接和 pin.it 短链接。

• 按关键词搜索公开的 Pin。

• 提取标题、描述、Pin 的 URL 以及公开暴露的图片/GIF/视频媒体。

• 优先尝试 originals 图片，如果 Pinterest 没有提供最佳版本，就依次尝试 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"

媒体默认限制为 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 — 供 AI 智能体使用

直接启动服务器：

PINTEREST_MCP_DOWNLOAD_DIR="$PWD/downloads" npm run mcp

它使用 stdio：不需要端口、不需要 API 密钥，也不会在 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 条款和版权规则适用于任何下载后的候选内容。

Status: Final content output above, but let's sanity-check some additions: The markdown uses hyphens "---" for bullet in the text? Let me verify if necessary. All done. Note a potential issue: in the bullet list I omitted a space after * ? I wrote "- " equals okay. Markd. All pipes same. Great.

Now final output should be no preamble# Glowe Pinterest MCP

一个公共的 Pinterest 下载工具，使用两种方式：一个供人使用的 CLI，以及一个面向 AI 智能提的 stdio MCP 服务器。两者共用一个核心：因此 CLI 与 MCP 返回相同的结果，应用相同的 URL 验证，只会下载到已配置的本地目录中。

注意：只使用你拥有必要使用权的内容。本项目读取 Pinterest 提供的数据，它不是 Pinterest 的官方 API，也不用来绕过登录认证、付费墙或内容限制。

项目功能

• 解释 Pinterest Pin 链接与 pin.it 短链接。

• 按关键字搜索公开 Pin。

• 提取标题、描述、Pin 的 URL，以及公开的图片/GIF/视频详情。

• 优先尝试 originals 图像，并在 Pinterest 未提供最佳质量时依次尝试 1200x、736x 等。

• 原子下载：先写 .part 临时文件，最后改名为最终文件，绝不覆盖已有文件。

• 拒绝除 pinterest.*、pin.it 以及与允许的 *.pinimg.com CDN 有关的任何重新定向或媒体 URL。

搜索功能使用 Pinterest 返回的公开结构化数据；如果无法获得该数据，会透明回退到 HTML。未登录状态下 Pinterest 可能只返回第一批结果，因此不保证分页，也不应该用它来抓取完整的内容集。

本地安装

需要有 Node 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 —— 给 AI 智能体用

直接启动服务器：

GCP5

它使用 stdio：没有端口，也不需要 Pinterest API 密钥，更不会往 stdout 输出任何应用日志。所有错误和启动诊断都输出到 stderr，以免破坏 MCP 协议。

本地 Codex 配置示例（~/.codex/config.toml）：

GCP6

改完配置之后，请重新启动 MCP/Codex 客户端，以使其重新拉起进程。其他任何 MCP 客户端使用相同的 node 命令、相同的绝对路径参数和相同的环境变量。

MCP 工具契约

阅读类工具带有 MCP 注解 readOnlyHint；写入磁盘的工具会在描述中说明必须有用户确认。智能体最好始终遵循这个流程：pinterest_search → 展示选中内容 → pinterest_get_in → 用户确认 → pinterest_download。

MCP 响应示例

pinterest_get_in 会返回一个结构化 JSON，其中至少包括：

GP7

智能体不要自行臆断媒体是否可用，而是应该依赖 media 字段，并分别报告每一条成功或失败的下载。

测试与质量策略

GCP8

网络测试被刻意独立出来，因为 Pinterest 有可能修改其公共 HTML 或让某个 Pin 不可用。该类测试不应被单元测试掩盖不去。

借鉴与技术选型

本项目设计参考 CHED 的 pinterest-downloader（优先 originals 并做质量递减）以及 PinterestDownloader（结构化 Pin/搜索契约）。MCP 界面的设计曾参考 mcp-pinterest，但这里使用的实现完全独立，不用无标浏览器，并且刻意把下载放缩到更窄。

对已登录 Pinterest 账号所拥有的 Pin 和 boards，请优使用官 Pinterest API v5 与 OAuth。Pinterest 的条款与版权对下载获得的任何内容仍然有效。