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

License

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