# pinterest-mcp

An MCP server that lets Claude (or any MCP client) search Pinterest and download images directly to your machine — no manual browsing, no manual saving.

It talks to Pinterest's own internal web API (the same requests your browser makes when you're logged in), authenticated with your personal session cookie. There's no official public Pinterest API for this, so this project reverse-engineers the internal one.

## Features

- **Search and download** — give a keyword, get N full-resolution images saved locally.
- **Board download** — give a board link (`pin.it` short links work), get N images from it.
- **List boards** — see a user's boards, with pin counts, without needing a direct link.
- **Board info** — look up a board's name and pin count.
- **Dedup on re-run** — re-fetching the same query or board skips images you already downloaded instead of re-fetching or leaving stale files behind.
- **Metadata sidecars** — each image's title, description, and source link is saved to a matching `.json` file in a hidden `.meta` folder, so the image folder itself stays clean.

## Requirements

- Python 3.14+
- [uv](https://docs.astral.sh/uv/)
- A Pinterest account, logged in via browser

## Install

```bash
git clone https://github.com/Nuu-maan/pinterest-mcp.git
cd pinterest-mcp
uv sync
```

## Getting your Pinterest cookie

This runs as *you*, using your own logged-in session — it does not create or need a separate API key.

1. Open [pinterest.com](https://pinterest.com) in your browser and make sure you're logged in.
2. Open DevTools (F12) → **Network** tab.
3. Reload the page, click any request to `pinterest.com`.
4. In the request headers, find `Cookie:` and copy the entire value.

Keep this value secret — it's equivalent to your login session.

## Configure

Register the server with Claude Code:

```bash
claude mcp add pinterest --scope user \
  -e PINTEREST_COOKIE="<paste your cookie here>" \
  -e PINTEREST_DOMAIN="www.pinterest.com" \
  -- uv --directory /path/to/pinterest-mcp run server.py
```

`PINTEREST_DOMAIN` defaults to `www.pinterest.com`. If Pinterest redirects you to a country-specific domain when logged in (e.g. `in.pinterest.com`), use that instead.

Images are saved to `~/Pictures/pinterest-downloads/<name>/` by default, or a custom `out_dir` you pass to a tool.

## Usage

Once configured, just ask:

- "Search Pinterest for minimalist logo design, download 10"
- "List my Pinterest boards"
- "Fetch 5 pins from this board: https://pin.it/xxxxxxx"

## Tools

| Tool | Description |
|---|---|
| `search_pinterest_images(query, count=20, out_dir=...)` | Search and download images |
| `get_pinterest_boards(username)` | List a user's boards |
| `get_pinterest_board_info(board_url)` | Look up a board's name and pin count |
| `fetch_pinterest_board(board_url, count, out_dir=...)` | Download images from a board |

## Development

```bash
uv run -- python -m tests.test_pins
uv run -- python -m tests.test_downloader
```

## Disclaimer

This uses Pinterest's internal, unofficial API, not a public developer API. It can break if Pinterest changes their endpoints, and heavy use may draw attention from their bot detection. Use it against your own account, at your own risk.

## License

MIT — see [LICENSE](LICENSE).

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md).