Boards & Pins MCP 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

Related MCP server: pinterest-vision-mcp

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:

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:

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