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

Tool	Description
pinterest_search	Search pins by keyword. Filter by mediaType: image | gif | video | all. Returns a bookmark for pagination.
pinterest_get_pin	Full detail for one pin — every image size and video stream.
pinterest_board_pins	Pins from a board (numeric id or username/board-slug).
pinterest_related_pins	Pins related to a given pin id.
pinterest_autocomplete	Search-term suggestions for a partial query.
pinterest_download	Save a pin's best media (or a direct URL) to disk.

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>

Operation	Resource
Search	BaseSearchResource — options.query, paginate via options.bookmarks: [bookmark]
Single pin	PinResource — options.id, field_set_key: auth_web_main_pin
Related pins	RelatedModulesResource — options.pin_id
Board pins	BoardFeedResource — options.board_id
Resolve board path	BoardResource — options.username, options.slug
Autocomplete	AdvancedTypeaheadResource — options.term (returns data.items)

• 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