Content
# pinterest-mcp
A local MCP server that exposes the Pinterest API v5 (read-only) to Claude Code.
Six tools, all `readOnlyHint: true`:
| Tool | Endpoint |
| --- | --- |
| `pinterest_get_user_account` | `GET /v5/user_account` |
| `pinterest_list_boards` | `GET /v5/boards` |
| `pinterest_get_board` | `GET /v5/boards/{board_id}` |
| `pinterest_list_board_pins` | `GET /v5/boards/{board_id}/pins` |
| `pinterest_list_pins` | `GET /v5/pins` |
| `pinterest_get_pin` | `GET /v5/pins/{pin_id}` |
Tokens are persisted to `~/.pinterest-mcp/tokens.json` and refreshed automatically.
---
## 1. Create a Pinterest developer app
1. Sign in at <https://developers.pinterest.com/apps/>.
2. Click **Create app**. Pick any name and description.
3. Once created, open the app and copy **App ID** and **App secret key**.
4. Under **Redirect URIs**, add exactly: `http://localhost:8085/callback`
- The OAuth helper listens on this port. If you need a different port, change both this field and `PINTEREST_REDIRECT_URI` in `.env`.
5. The default scopes (`user_accounts:read`, `boards:read`, `pins:read`) work on the standard app tier. No trade review needed for read-only exploration.
## 2. Configure the project
```sh
cd pinterest-mcp
npm install
cp .env.example .env
# Edit .env and paste PINTEREST_APP_ID and PINTEREST_APP_SECRET
```
## 3. Authorize once
```sh
npm run auth
```
This will:
1. Open `pinterest.com/oauth/` in your browser.
2. Wait for you to approve the requested scopes.
3. Catch the redirect on `localhost:8085`, exchange the code for tokens.
4. Write `~/.pinterest-mcp/tokens.json` (mode 0600).
You only need to repeat this if you revoke access or the refresh token expires (Pinterest continuous refresh tokens last 60 days but auto-extend on use).
## 4. Build and smoke-test
```sh
npm run build
npm run inspect # opens MCP Inspector against the built server
```
In the inspector, call `pinterest_get_user_account` — it should return your profile.
## 5. Wire into Claude Code
Add to your Claude Code MCP config (e.g., `~/.claude.json` under `mcpServers`):
```json
{
"mcpServers": {
"pinterest": {
"command": "node",
"args": ["/Users/marketingmanagerturkiye/Documents/Claude/Projects/HyperFrame/pinterest-mcp/dist/server.js"],
"env": {
"PINTEREST_APP_ID": "...",
"PINTEREST_APP_SECRET": "..."
}
}
}
}
```
`PINTEREST_APP_ID` and `PINTEREST_APP_SECRET` must be readable by the server process — either inline as above, or via the `.env` file in this directory (dotenv loads automatically).
---
## Notes
- Pagination: tools that return lists accept `page_size` (1–100) and `bookmark`. Pass the `bookmark` from a previous response to fetch the next page.
- Errors: Pinterest API errors are returned as MCP tool errors with the full response body so you can debug 4xx/5xx without reading server logs.
- Adding write tools (create pin, create board, etc.) requires the matching `:write` scopes — add them to `PINTEREST_SCOPES` and re-run `npm run auth`, then add the tool to `src/server.ts`.
