pinterest-mcp
Provides tools to search, retrieve, and download pins, boards, and related content from Pinterest.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@pinterest-mcpsearch for minimalist wall art"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 |
| Search pins by keyword. Filter by |
| Full detail for one pin — every image size and video stream. |
| Pins from a board (numeric id or |
| Pins related to a given pin id. |
| Search-term suggestions for a partial query. |
| Save a pin's best media (or a direct URL) to disk. |
Related MCP server: pinterest-mcp
Install & build
npm install
npm run buildInstall 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-mcpThe 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 -- --browserOr 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 |
|
Single pin |
|
Related pins |
|
Board pins |
|
Resolve board path |
|
Autocomplete |
|
Envelope:
{ resource_response: { status, data: {...}|{results:[...]}, bookmark } }Only required header:
x-pinterest-pws-handler: www/index.js(thex-app-versionbuild 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 -> mp4Available Tools
6 toolspinterest_autocompleteA
Get Pinterest search-term suggestions for a partial query.
| Name | Required | Description | Default |
|---|---|---|---|
| term | Yes | Partial search text, e.g. 'mini'. | |
| limit | No |
TDQS
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.
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.
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.
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.
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.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| board | Yes | Board id or path, e.g. 'nasa/space'. | |
| limit | No | ||
| bookmark | No | ||
| mediaType | No | Filter results to a single media kind, or 'all'. | all |
TDQS
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.
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.
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.
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.
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.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| dir | No | Destination directory. Defaults to ~/Downloads/pinterest. | |
| url | No | Direct media URL to download instead of a pin. | |
| pinId | No | Pin id to download the best media for. | |
| prefer | No | For a pinId: which asset to prefer. 'auto' = video if present, else image. | auto |
TDQS
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.
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.
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.
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.
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.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| pinId | Yes | Numeric Pinterest pin id. |
TDQS
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.
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.
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.
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.
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.
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.
pinterest_searchA
Search Pinterest for pins by keyword. Returns images, gifs, and/or videos with direct media URLs and a pagination bookmark. No authentication required.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| query | Yes | Search keywords, e.g. 'minimal desk setup'. | |
| bookmark | No | Pagination cursor returned by a previous call. | |
| mediaType | No | Filter results to a single media kind, or 'all'. | all |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the transparency burden. It discloses that no authentication is required and describes the return payload (images/gifs/videos, direct URLs, pagination bookmark), which gives useful behavioral context beyond a bare 'search' statement.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two tight sentences: first states the action, second states the return and auth trait. No filler or redundancy; every word contributes.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a search tool with 4 parameters and no output schema, the description covers the core return contract and auth. It omits details like sort order, default result behavior, or rate limits, but given schema covers most params, it is sufficiently complete for an agent to use it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 75%, so the baseline is 3. The description adds minimal param-level insight beyond the schema—only the keyword concept is reinforced. It does not explain limit or further elaborate on mediaType/bookmark, so it doesn't elevate above baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool searches Pinterest by keyword, identifying the specific verb (search) and resource (pins). It distinguishes this from sibling tools like get_pin or board_pins by focusing on keyword-based search.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for keyword searches and provides clear context about returns (media URLs, pagination) and auth requirements. It does not explicitly mention alternatives or when not to use, so it misses the full 5-level.
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.
6 tool updates
v0.2.0- First observed
pinterest_autocomplete - First observed
pinterest_board_pins - First observed
pinterest_download - First observed
pinterest_get_pin - First observed
pinterest_related_pins - First observed
pinterest_search
TDQS
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.
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.
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.
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
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
- pinsuiteOAuthapp.pinsuite
Download and save Pinterest boards, Instagram posts and web pages into a library you own.
Get social media data from Instagram and TikTok: profiles, posts, videos, comments, and more.
Image Search: Fast and Simple Image Search API. You can get 100+ search results in one query!.
Instagram: Instagram public data scraper API for search, users, posts, hashtags, locations and more.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to interact with the Pinterest API, allowing management of boards and pins through natural language commands.9220MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to manage Pinterest boards and pins, create and update pins, and track analytics via the Pinterest API v5.4MIT
- AlicenseBqualityBmaintenanceEnables image search and information retrieval from Pinterest using the Model Context Protocol. Supports searching by keywords, getting similar pins, and downloading images directly.592MIT
- AlicenseAqualityBmaintenanceMCP server for parsing, validating, classifying, and normalizing Pinterest URLs locally, supporting pins, profiles, boards, and ideas URLs across Pinterest country domains without network requests.342MIT
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
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