Pinterest MCP Server

A Model Context Protocol (MCP) server for Pinterest image search and information retrieval.

Features

• Search for images on Pinterest by keywords
• Retrieve detailed information about Pinterest images
• Seamless integration with Cursor IDE, Claude Desktop, and Remote MCP clients
• Dual transport modes: Stdio (Local IDEs) and HTTP/SSE (Remote Hosting / Render)
• API Key Bearer Authentication for cloud deployment
• Support for headless browser mode
• Configurable search result limits and filename templates
• Search and download images directly to local storage

Prerequisites

• Node.js (v18 or higher)
• Cursor IDE or Claude Desktop for MCP integration

Installation & Deployment

🚀 Deploying to Render (Remote MCP Server over HTTP/SSE)

You can host this Pinterest MCP server as a secure remote service on Render, Railway, or Fly.io with Bearer API Key authentication.

1. Connect your repository to Render or use the included render.yaml blueprint.
2. Set Environment Variables:
   • PORT: 3000 (or leave default set by Render)
   • API_KEY: your_super_secret_key_here (Secret key required for client requests)
   • MCP_PINTEREST_DOWNLOAD_DIR: /tmp/downloads
3. Health check URL: GET /health (Returns 200 OK)
4. SSE connection URL: GET /sse (Requires Authorization: Bearer <API_KEY> header or x-api-key header)

Client Request Example with Bearer Key

GET /sse HTTP/1.1
Host: pinterest-mcp.onrender.com
Authorization: Bearer your_super_secret_key_here

Unauthenticated requests receive 401 Unauthorized responses.

---

Local Installation via NPX (Recommended for Local Use)

npx pinterest-mcp-server

Command-line options:

# Specify download directory
npx pinterest-mcp-server --downloadDir /path/to/downloads

# Specify filename template
npx pinterest-mcp-server --filenameTemplate "pinterest_{id}"

# Specify both options
npx pinterest-mcp-server --downloadDir ./images --filenameTemplate "pinterest_{id}"

Global Installation

npm install -g pinterest-mcp-server
pinterest-mcp-server --downloadDir /path/to/downloads

Manual Installation

1. Clone repository:

   git clone https://github.com/terryso/mcp-pinterest.git pinterest-mcp-server
   cd pinterest-mcp-server
   

2. Install dependencies:

   npm install
   

3. Build server:

   npm run build
   

4. Start server:

   npm start
   

Configuring as MCP Server in Cursor

1. Open Cursor IDE
2. Go to Settings (⚙️) > Extensions > MCP
3. Click Add Server
4. Enter configuration:
   • Name: Pinterest MCP
   • Type: Command
   • Command: node
   • Args: ["/path/to/mcp-pinterest/dist/pinterest-mcp-server.js"]

Or edit your Cursor MCP config file (~/.cursor/mcp.json):

{
  "pinterest": {
    "command": "node",
    "args": ["/path/to/mcp-pinterest/dist/pinterest-mcp-server.js"]
  }
}

Environment Variables Configuration Example

{
  "pinterest": {
    "command": "npx",
    "env": {
      "MCP_PINTEREST_DOWNLOAD_DIR": "/Users/user/Desktop/Images",
      "MCP_PINTEREST_FILENAME_TEMPLATE": "pin_{imageId}_{timestamp}.{fileExtension}",
      "MCP_PINTEREST_PROXY_SERVER": "http://127.0.0.1:7890"
    },
    "args": ["pinterest-mcp-server"]
  }
}

Available MCP Tools

• pinterest_health_check: System metrics, memory usage, Chromium binary status, and write diagnostics

  • No required parameters.

• pinterest_search: Search for images on Pinterest by keyword with persistent browser pool

  • keyword: Search term (required)
  • limit: Number of images to return (default: 10)
  • headless: Whether to use headless browser mode (default: true)

• pinterest_get_similar_pins: Deep visual recommendation engine for a target Pin URL or Pin ID

  • pin_url_or_id: Pinterest Pin URL (e.g. https://www.pinterest.com/pin/11822017768403505/) or numeric Pin ID (required)
  • limit: Number of recommended pins to return (default: 10)
  • headless: Whether to use headless browser mode (default: true)

• pinterest_get_image_info: Retrieve detailed information for a Pinterest image

  • image_url: Image URL (required)

• pinterest_search_and_download: Search and download Pinterest images directly to disk

  • keyword: Search term (required)
  • limit: Number of images (default: 10)
  • headless: Whether to use headless browser mode (default: true)

Environment Variables Reference

Variable	Description	Default
PORT / HTTP_PORT	HTTP Port for SSE server mode	(Stdio mode if unassigned)
API_KEY / MCP_API_KEY	Secret API key for HTTP/SSE authentication	(No auth if empty)
MCP_PINTEREST_DOWNLOAD_DIR	Root directory for downloads	../downloads
MCP_PINTEREST_FILENAME_TEMPLATE	Template for downloaded file names	pinterest_{imageId}.{fileExtension}
MCP_PINTEREST_PROXY_SERVER	Optional proxy server (http://host:port)	None
PUPPETEER_EXECUTABLE_PATH	Path to custom Chrome/Chromium binary	System default

License

This project is licensed under the MIT License - see the LICENSE file for details.

<!-- Deployed: 2026-07-29 -->