[](https://mseep.ai/app/terryso-mcp-pinterest)
# Pinterest MCP Server
[](https://badge.fury.io/js/pinterest-mcp-server)
[](https://smithery.ai/server/@terryso/mcp-pinterest)
[](https://mseep.ai/app/23da55f4-6d6a-4dc9-af31-cd6073eb1b27)
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 through MCP
- Support for headless browser mode
- Limit control for search results
- Search and download images from Pinterest
## Prerequisites
- [Node.js](https://nodejs.org/) (v18 or higher)
- [Cursor IDE](https://cursor.sh/) for MCP integration
## Installation
### Using NPX (Recommended)
The easiest way to use Pinterest MCP Server is via npx:
```bash
npx pinterest-mcp-server
```
You can configure the server with command-line options:
```bash
# 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
To install the package globally and use it directly from the command line:
```bash
npm install -g pinterest-mcp-server
```
After installation, you can run the server with:
```bash
pinterest-mcp-server
```
With the same command line options as the NPX version:
```bash
pinterest-mcp-server --downloadDir /path/to/downloads --filenameTemplate "pinterest_{id}"
```
### Installing via Smithery
To install mcp-pinterest for Claude Desktop automatically via [Smithery](https://smithery.ai/server/mcp-pinterest):
```bash
npx -y @smithery/cli install mcp-pinterest --client claude
```
### Manual Installation
1. Clone this repository:
```bash
git clone https://github.com/terryso/mcp-pinterest.git pinterest-mcp-server
cd pinterest-mcp-server
```
2. Install dependencies:
```bash
npm install
```
3. Build the server:
```bash
npm run build
```
4. Run the server:
```bash
npm start
```
## Configuring as MCP Server in Cursor
1. Open Cursor IDE
2. Go to Settings (⚙️) > Extensions > MCP
3. Click "Add Server"
4. Enter the following details:
- Name: Pinterest MCP
- Type: Command
- Command: `node`
- Args: `["/path/to/mcp-pinterest/dist/pinterest-mcp-server.js"]`
或者直接编辑Cursor的MCP配置文件（通常位于`~/.cursor/mcp.json`），添加以下内容：
```json
"pinterest": {
"command": "node",
"args": ["/path/to/mcp-pinterest/dist/pinterest-mcp-server.js"]
}
```
5. Click "Save"
### Alternative: Using NPX for Cursor Configuration
You can also configure Cursor to use the npx version of the server:
1. Open Cursor IDE
2. Go to Settings (⚙️) > Extensions > MCP
3. Click "Add Server"
4. Enter the following details:
- Name: Pinterest MCP
- Type: Command
- Command: `npx`
- Args: `["pinterest-mcp-server"]`
5. Click "Save"
### Complete Configuration Example with Environment Variables
For the most flexibility, you can configure the server with environment variables in your Cursor MCP configuration:
```json
"pinterest": {
"command": "npx",
"env": {
"MCP_PINTEREST_DOWNLOAD_DIR": "/Users/xxx/Desktop/Images",
"MCP_PINTEREST_FILENAME_TEMPLATE": "pin_{imageId}_{timestamp}.{fileExtension}",
"MCP_PINTEREST_PROXY_SERVER": "http://127.0.0.1:7890"
},
"args": ["pinterest-mcp-server"]
}
```
This configuration:
- Uses npx to run the server
- Sets a custom download directory on your desktop
- Uses a custom filename template with both image ID and timestamp
- Configures a proxy server for users in regions where Pinterest might be blocked
Add this to your `~/.cursor/mcp.json` file or set up through the Cursor IDE interface.
## Available MCP Functions
The server exposes the following MCP functions:
- `pinterest_search`: Search for images on Pinterest by keyword
- Parameters:
- `keyword`: Search term (required)
- `limit`: Number of images to return (default: 10)
- `headless`: Whether to use headless browser mode (default: true)
- `pinterest_get_image_info`: Get detailed information about a Pinterest image
- Parameters:
- `image_url`: URL of the Pinterest image (required)
- `pinterest_search_and_download`: Search and download images from Pinterest
- Parameters:
- `keyword`: Search term (required)
- `limit`: Number of images to return (default: 10)
- `headless`: Whether to use headless browser mode (default: true)
## Example Usage in Cursor
Once configured, you can use the Pinterest MCP functions directly in Cursor's AI chat:
```
Search for robot images on Pinterest
```
The AI will use the MCP server to search Pinterest and display the results.
### Example Screenshot
*Screenshot showing a search for 20 images of 三上悠亚 with all images successfully downloaded.*
## Development
### Project Structure
- `pinterest-mcp-server.ts`: Main server file
- `dist/pinterest-mcp-server.js`: Built JavaScript file for production
- `package.json`: Project configuration and dependencies
### Adding New Features
To add new MCP functions:
1. Modify `pinterest-mcp-server.ts`
2. Register new functions using the MCP SDK
3. Implement the function logic
4. Rebuild with `npm run build`
## Troubleshooting
- If the server fails to start, check if the port is already in use
- Ensure all dependencies are correctly installed with `npm install`
- Make sure TypeScript is properly configured with a `tsconfig.json` file
- If you encounter build errors, try running `npm install -D typescript @types/node`
- Verify network connectivity for Pinterest access
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Configuration Options
### Command Line Options (NPX Mode)
When using the server via npx, you can configure it using the following command line options:
- `--downloadDir`: Specifies the root directory for downloading images
```bash
npx pinterest-mcp-server --downloadDir /path/to/downloads
```
- `--filenameTemplate`: Specifies the filename template for downloaded images
```bash
npx pinterest-mcp-server --filenameTemplate "pin_{imageId}_{timestamp}"
```
- `--port`: Specifies the port for the server to listen on (default: 3000)
```bash
npx pinterest-mcp-server --port 8080
```
- `--proxyServer`: Specifies the proxy server to use for connecting to Pinterest
```bash
npx pinterest-mcp-server --proxyServer "http://127.0.0.1:7890"
```
You can combine multiple options:
```bash
npx pinterest-mcp-server --downloadDir ./images --filenameTemplate "pinterest_{id}" --port 8080 --proxyServer "http://127.0.0.1:7890"
```
### Environment Variables
The server also supports the following environment variables for configuration:
- `MCP_PINTEREST_DOWNLOAD_DIR`: Specifies the root directory for downloading images. If not set, the default is the `../downloads` directory relative to the server script.
- `MCP_PINTEREST_FILENAME_TEMPLATE`: Specifies the filename template for downloaded images. If not set, the default is `pinterest_{imageId}.{fileExtension}`.
- `MCP_PINTEREST_PROXY_SERVER`: Specifies the proxy server to use for connecting to Pinterest. Format should be `protocol://host:port`, for example `http://127.0.0.1:7890` or `socks5://127.0.0.1:1080`.
These environment variables can be set in several ways:
1. Directly in your terminal (as shown in the examples below)
2. In your Cursor MCP configuration through the `env` field (see [Complete Configuration Example](#complete-configuration-example-with-environment-variables))
3. In a `.env` file in the project root directory
4. Through command line options with npx (as shown in the [Command Line Options](#command-line-options-npx-mode) section)
### Usage
#### Setting Download Directory
1. Using npx with command line options:
```bash
npx pinterest-mcp-server --downloadDir /path/to/your/download/directory
```
2. Set the download directory using an environment variable:
```bash
# Linux/macOS
export MCP_PINTEREST_DOWNLOAD_DIR=/path/to/your/download/directory
npx pinterest-mcp-server
# Windows (CMD)
set MCP_PINTEREST_DOWNLOAD_DIR=C:\path\to\your\download\directory
npx pinterest-mcp-server
# Windows (PowerShell)
$env:MCP_PINTEREST_DOWNLOAD_DIR="C:\path\to\your\download\directory"
npx pinterest-mcp-server
```
3. If the environment variable is not set, the server will use the default download directory (relative to the server script's `../downloads`).
#### Setting Filename Template
1. Using npx with command line options:
```bash
npx pinterest-mcp-server --filenameTemplate "pin_{imageId}_{timestamp}.{fileExtension}"
```
2. Using an environment variable:
```bash
# Linux/macOS
export MCP_PINTEREST_FILENAME_TEMPLATE="pin_{imageId}_{timestamp}.{fileExtension}"
npx pinterest-mcp-server
# Windows (CMD)
set MCP_PINTEREST_FILENAME_TEMPLATE="pin_{imageId}_{timestamp}.{fileExtension}"
npx pinterest-mcp-server
# Windows (PowerShell)
$env:MCP_PINTEREST_FILENAME_TEMPLATE="pin_{imageId}_{timestamp}.{fileExtension}"
npx pinterest-mcp-server
```
The template supports the following variables:
- `{imageId}`: The unique ID of the Pinterest image
- `{fileExtension}`: The file extension (e.g., jpg, png)
- `{timestamp}`: Current UTC timestamp in YYYYMMDDHHMMSS format
- `{index}`: The index number when downloading multiple images (starts from 1)
Example templates:
- `pinterest_{imageId}.{fileExtension}` (default)
- `pin_{timestamp}_{imageId}.{fileExtension}`
- `pinterest_image_{index}_{imageId}.{fileExtension}`
- `{timestamp}_pinterest.{fileExtension}`
If the template is invalid (e.g., contains unsupported variables or has mismatched brackets), the server will log a warning and use the default template.
#### Setting Proxy Server
If you need to use a proxy to access Pinterest (especially in regions where Pinterest might be restricted), you can set the proxy configuration:
1. Using npx with command line options:
```bash
npx pinterest-mcp-server --proxyServer "http://127.0.0.1:7890"
```
2. Using an environment variable:
```bash
# Linux/macOS
export MCP_PINTEREST_PROXY_SERVER="http://127.0.0.1:7890"
npx pinterest-mcp-server
# Windows (CMD)
set MCP_PINTEREST_PROXY_SERVER=http://127.0.0.1:7890
npx pinterest-mcp-server
# Windows (PowerShell)
$env:MCP_PINTEREST_PROXY_SERVER="http://127.0.0.1:7890"
npx pinterest-mcp-server
```
Supported proxy protocols:
- HTTP: `http://host:port`
- HTTPS: `https://host:port`
- SOCKS4: `socks4://host:port`
- SOCKS5: `socks5://host:port`
The proxy configuration affects both the browser used for searching and the image downloading process.
#### Notes
- The server will verify the existence and writability of the download directory when starting. If the directory does not exist, it will attempt to create it; if it cannot be created or written to, the server will exit.
- Clients should not specify download paths or filename templates through parameters when calling download-related tools, as all downloads will use the server's environment variable configuration or defaults.
- The server automatically sanitizes filenames by replacing illegal characters (such as `/`, `\`, `:`, `*`, `?`, `"`, `<`, `>`, `|`) with underscores.
#### Interface Description
The server provides the following MCP tools:
1. `pinterest_search`: Search for Pinterest images by keyword
2. `pinterest_get_image_info`: Get detailed information about a Pinterest image
3. `pinterest_search_and_download`: Search and download Pinterest images
For detailed interface parameter references, please refer to the MCP tool definitions.
