Skip to main content
Glama
Martin-Code202

pinterest-mcp

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.

Related MCP server: pinterest-mcp

Install & build

npm install
npm run build

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

BaseSearchResourceoptions.query, paginate via options.bookmarks: [bookmark]

Single pin

PinResourceoptions.id, field_set_key: auth_web_main_pin

Related pins

RelatedModulesResourceoptions.pin_id

Board pins

BoardFeedResourceoptions.board_id

Resolve board path

BoardResourceoptions.username, options.slug

Autocomplete

AdvancedTypeaheadResourceoptions.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

Available Tools

6 tools
pinterest_autocompleteA

Get Pinterest search-term suggestions for a partial query.

ParametersJSON Schema
NameRequiredDescriptionDefault
termYesPartial search text, e.g. 'mini'.
limitNo

TDQS

A3.5/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must carry the full behavioral disclosure burden. It merely states the function and gives no hints about return format, rate limits, authentication, or edge cases. The description's 'Get' is implicit from the tool name, adding no extra transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence of 10 words. Every word contributes meaning, with no filler or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple tool with two parameters and no output schema, the description gives a bare-minimum overview. It does not mention the return value structure (e.g., an array of strings), nor any limitations. It is adequate but leaves clear gaps that could confuse an agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 50%; the 'term' parameter has a description with an example, while 'limit' has only type/default/min/max. The tool description adds a bit of context by calling it a 'partial query' but does not explain the role of 'limit' or the interplay between parameters. Overall, the schema provides adequate parameter semantics.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Get') and names the resource ('Pinterest search-term suggestions') with a clear qualifier ('for a partial query'). It clearly distinguishes from siblings like pinterest_search, which would return full search results.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage with a partial query but does not explicitly state when to use this tool instead of alternatives, nor does it mention exclusions or comparisons to sibling tools like pinterest_search. The context is clear but not explicitly guided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

pinterest_board_pinsB

List pins from a Pinterest board. Accepts a numeric board id or a 'username/board-slug' path.

ParametersJSON Schema
NameRequiredDescriptionDefault
boardYesBoard id or path, e.g. 'nasa/space'.
limitNo
bookmarkNo
mediaTypeNoFilter results to a single media kind, or 'all'.all

TDQS

B3.1/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden but only states the core function. It does not disclose pagination behavior (bookmark), rate limits, error handling, or ordering of pins. The only behavioral hint is the accepted board id format, which is already in the schema, providing minimal extra value.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two short sentences, immediately stating the action and a key detail about accepted inputs. Every word earns its place with no redundancy or filler, making it highly concise and well-structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has four parameters including a pagination bookmark, no output schema, and no annotations. The description is too minimal to cover pagination, return format, or error conditions, leaving significant gaps for an agent to invoke it correctly, especially for multi-page listing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 50% (board and mediaType described). The description repeats the board id/path format already in the schema and does not clarify limit, bookmark, or mediaType semantics. Since it adds no meaning beyond the schema, it fails to compensate for the undocumented parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool lists pins from a Pinterest board, with a specific verb and resource. It distinguishes itself from sibling tools like pinterest_get_pin (single pin) and pinterest_search (search), making the purpose unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives. The description mentions no exclusions, prerequisites, or comparisons to sibling tools, so the agent receives no help deciding between board listing, searching, or related pins.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

pinterest_downloadA

Download a pin's media (image, gif, or video) to local disk. Give a pinId to grab its best asset, or a direct media url. HLS videos are muxed to mp4 via ffmpeg.

ParametersJSON Schema
NameRequiredDescriptionDefault
dirNoDestination directory. Defaults to ~/Downloads/pinterest.
urlNoDirect media URL to download instead of a pin.
pinIdNoPin id to download the best media for.
preferNoFor a pinId: which asset to prefer. 'auto' = video if present, else image.auto

TDQS

A4.2/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must carry the behavioral burden. It does disclose that a download writes to disk and that HLS videos are muxed to mp4 via ffmpeg. However, it omits details like file overwriting behavior, error handling, or external dependencies beyond ffmpeg.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with the main purpose, and every sentence adds useful information. No waste.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with no output schema and no annotations, the description covers the main use cases and a notable behavioral detail (ffmpeg conversion). It lacks return value/error behavior details but is sufficient for a competent agent to invoke correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining the relationship between pinId and url, and clarifying that 'best asset' is determined by the prefer parameter, which is more than the schema alone provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Download') with a clear resource ('a pin's media') and destination ('to local disk'). It clearly distinguishes from sibling tools, which are search/read operations.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains the two primary usage modes: 'Give a pinId to grab its best asset, or a direct media url.' This gives clear context, though it does not explicitly name alternative tools or exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

pinterest_get_pinA

Fetch full detail for a single pin by id, including every image size and video stream.

ParametersJSON Schema
NameRequiredDescriptionDefault
pinIdYesNumeric Pinterest pin id.

TDQS

A4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden. It signals a read-only operation via 'Fetch' and transparently lists what is included in the response (image sizes, video streams). It does not cover rate limits or errors, but for a simple retrieval this is adequate.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence that conveys the primary action, the object, and key return details with no redundant words or fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a one-parameter read tool with no output schema, the description covers the main return content (full detail, image sizes, video streams). It could be more explicit about other fields, but 'full detail' is broad enough to imply comprehensive data.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema already provides 100% coverage for pinId with 'Numeric Pinterest pin id.' The description adds no additional parameter semantics, so the baseline score of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action (fetch), resource (single pin), and scope (by id). It also specifies the content included (every image size and video stream), which distinguishes it from sibling tools that search or list pins.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies that this tool is for when a specific pin ID is known and full details are needed, but it does not explicitly contrast with siblings like pinterest_search or pinterest_board_pins, leaving the choice to the agent's inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 6 tool updatesv0.2.0
    • First observedpinterest_autocomplete
    • First observedpinterest_board_pins
    • First observedpinterest_download
    • First observedpinterest_get_pin
    • First observedpinterest_related_pins
    • First observedpinterest_search

TDQS

A3.8/5.0
Disambiguation5/5

Each tool has a clear, distinct purpose: search, detail, board listing, related, autocomplete, and download. No two tools appear to overlap in functionality, making selection unambiguous.

Naming Consistency4/5

All tools share the pinterest_ prefix, but the pattern is mixed: some are verbs (pinterest_search, pinterest_download), some are verb+noun (pinterest_get_pin), and some are noun+noun or adjective+noun (pinterest_board_pins, pinterest_related_pins). While readable, the lack of a uniform verb_noun structure is a minor deviation.

Tool Count5/5

Six tools is well within the ideal range for a focused media search and retrieval server. Each tool earns its place and the count feels neither thin nor bloated.

Completeness4/5

The surface covers the core read-only workflows: searching, fetching details, listing board pins, finding related content, getting suggestions, and downloading media. Minor gaps like board metadata or user profiles exist, but they are not essential for the apparent purpose.

Maintenance

ActivitySlowing
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • A
    license
    Not graded
    quality
    D
    maintenance
    Enables AI agents to manage Pinterest boards and pins, create and update pins, and track analytics via the Pinterest API v5.
    4
    MIT
  • A
    license
    B
    quality
    B
    maintenance
    Enables image search and information retrieval from Pinterest using the Model Context Protocol. Supports searching by keywords, getting similar pins, and downloading images directly.
    5
    92
    MIT
  • A
    license
    A
    quality
    B
    maintenance
    MCP server for parsing, validating, classifying, and normalizing Pinterest URLs locally, supporting pins, profiles, boards, and ideas URLs across Pinterest country domains without network requests.
    3
    42
    MIT

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/Martin-Code202/pinterest-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server