Boards & Pins Server

An MCP (Model Context Protocol) server that lets Claude interact with Pinterest — browsing, creating, and managing boards, pins, sections, and user profiles via the Pinterest API v5.

Features

• Browse boards and pins with bookmark-based pagination
• Create boards, sections, and pins from image URLs
• Update and move pins across boards and sections
• Search pins by keyword
• View pin images directly inside Claude (base64 image blocks)
• OAuth 2.0 with automatic token refresh, or direct access token

Requirements

• Node.js >= 20
• A Pinterest account and app (see Configuration)

Quick Start

git clone https://github.com/sapyx/sapyx-mcp.git
cd sapyx-mcp
npm install
npm run build

Copy the environment template and fill in your credentials:

cp .env.example .env

Then add the server to your MCP client (see Configuration).

Authentication

Two modes are supported:

Mode	Env vars	Access
Direct token	PINTEREST_ACCESS_TOKEN	Read-only
OAuth 2.0	PINTEREST_APP_ID + PINTEREST_APP_SECRET	Full read + write

For OAuth, trigger the flow via the pinterest_auth tool. Tokens are stored in ~/.mcp-credentials/pinterest-tokens.json and refreshed automatically.

Full details: docs/authentication.md

Tools

14 tools across four groups:

Group	Tools
Auth	pinterest_auth, pinterest_auth_status
Boards	list_boards, create_board, list_board_sections, create_board_section
Pins	list_pins, get_pin, get_pin_image, update_pin, move_pin, create_pin
Search	search_pins, get_user_profile

Full reference: docs/tools.md

Project Structure

src/
  index.ts          # Entry point — env validation, server setup, STDIO transport
  auth.ts           # OAuth 2.0 flow, token storage, refresh logic
  api.ts            # Typed HTTP client wrapping Pinterest API v5
  types.ts          # TypeScript interfaces (Pin, Board, tokens, etc.)
  tools/
    auth.ts         # pinterest_auth, pinterest_auth_status
    boards.ts       # list_boards, create_board, list_board_sections, create_board_section
    pins.ts         # list_pins, get_pin, get_pin_image, update_pin, move_pin, create_pin
    search.ts       # search_pins, get_user_profile
docs/
  authentication.md # OAuth flow, token storage, refresh logic
  tools.md          # Full tool reference with parameters
  api-client.md     # Internal API client documentation
  configuration.md  # Env vars, MCP client setup, Pinterest app setup

Tech Stack

• Language: TypeScript (ES2022, Node16 modules)
• Runtime: Node.js >= 20
• MCP Framework: @modelcontextprotocol/sdk
• Validation: Zod
• Transport: STDIO

Documentation

• Authentication
• Tools Reference
• API Client
• Configuration