pinterest-mcp

An MCP server for extracting images, gifs, videos, and search results from Pinterest — using Pinterest's own web /resource/ API.

No authentication required. The web resource API serves search, pins, boards, and related pins fully unauthenticated — no login, token, cookie, reCAPTCHA, or API key. So it works for anyone, anywhere, out of the box. (An optional session cookie can be supplied to unlock personalized resources, but it's never required for extraction.)

The endpoints, request shapes, and pin/media JSON were reverse-engineered from pinterest.com captures and validated live.

Tools

Related MCP server: Pexels MCP Server

Install & build

npm install
npm run build

Install as a Claude Code plugin (recommended)

This repo is also a Claude Code plugin marketplace. Install with no local build:

/plugin marketplace add Martin-Code202/pinterest-mcp
/plugin install pinterest-mcp@pinterest-mcp

The plugin ships a self-contained bundle (server.mjs), so there's nothing to npm install — the pinterest MCP server is registered automatically.

Or register the MCP server manually

git clone https://github.com/Martin-Code202/pinterest-mcp.git
cd pinterest-mcp && npm install && npm run build
claude mcp add -s user pinterest -- node "$PWD/dist/index.js"

Either way — no credentials to configure.

Downloading media

pinterest_download streams images/gifs directly to disk. Pinterest videos on the web are HLS (.m3u8) only, so video downloads are remuxed into a single .mp4 with ffmpeg (-c copy, no re-encode). ffmpeg must be on PATH (or set FFMPEG_PATH); without it, video URLs return a skipped note. Default destination is ~/Downloads/pinterest.

Optional authentication

Not needed for extraction. If you want personalized/authenticated resources (home feed, your own private boards), supply a web session cookie:

npm run login -- --cookie "_pinterest_sess=...; csrftoken=...; _auth=1"
# or via a browser login window (requires Playwright):
npm i -D playwright && npx playwright install chromium
npm run login -- --browser

Or set the PINTEREST_COOKIE env var. Stored at ~/.config/pinterest-mcp/credentials.json (mode 600).

Confirmed API (unauthenticated)

Base: https://www.pinterest.com/resource/<Name>Resource/get/?source_url=<path>&data=<url-encoded {options,context}>&_=<ms>

• Envelope: { resource_response: { status, data: {...}|{results:[...]}, bookmark } }

• Only required header: x-pinterest-pws-handler: www/index.js (the x-app-version build hash is not validated — no time bomb).

• Web videos expose HLS only (V_HLSV4, V_HLSV3_MOBILE); images are { "236x": {url,width,height}, … }.

Architecture

.claude-plugin/
  marketplace.json       Claude Code marketplace manifest
  plugin.json            plugin manifest (registers the MCP server)
server.mjs               self-contained bundle used by the plugin (esbuild)
src/
  config.ts              web base, required headers, optional cookie
  index.ts               MCP server + tool definitions
  auth/                  OPTIONAL cookie handling
    store.ts             cookie persistence
    login-cli.ts         `npm run login` (cookie / browser / status / clear)
    browser-login.ts     browser cookie capture (Playwright, optional)
  pinterest/
    client.ts            web /resource/ GET client + envelope parsing
    endpoints.ts         search / pin / board / related / autocomplete
    media.ts             normalize pins -> images/videos/gifs
    download.ts          stream images; ffmpeg-mux HLS -> mp4