PinterestMCP

Read-only Pinterest MCP server for ChatGPT and other MCP clients. The goal is to expose Pinterest boards, sections, pins, and pin imagery as a stable visual-reference library.

Status

This repository now contains a working TypeScript MCP server with:

• Streamable HTTP MCP endpoint at /mcp
• HTTP endpoints at /, /health, /privacy, /terms
• Typed Pinterest API client with token refresh support
• Read-only MCP tools for boards, sections, pins, search, and pin images
• Unit and integration tests
• GitHub Actions CI
• Vercel-ready entrypoint and rewrites

Current auth modes:

• none: local development and inspector work
• bearer: simple shared-secret gate for a private endpoint

Important:

• Official OpenAI docs recommend OAuth for user-specific remote MCP data.
• This repo is auth-ready at the application boundary, but a production OAuth authorization server is still a separate step.
• Pinterest runtime verification against the real account requires valid Pinterest credentials in environment variables.

Architecture

flowchart TD
  A["ChatGPT or MCP Client"] -->|Streamable HTTP| B["PinterestMCP"]
  B -->|Bearer access token or refresh flow| C["Pinterest API v5"]
  C --> D["Pinterest Account Data"]
  E["Optional MCP Auth Layer"] --> B

Auth layers:

• Layer A: PinterestMCP -> Pinterest API
• Layer B: ChatGPT -> PinterestMCP

Available MCP Tools

• pinterest_list_boards
• pinterest_get_board
• pinterest_list_board_sections
• pinterest_list_board_pins
• pinterest_get_pin
• pinterest_search_saved_pins
• pinterest_get_pin_image
• pinterest_get_reference_set

All tools are annotated as read-only.

Local Setup

Requirements:

• Node.js 22+
• npm 10+

Install and run:

npm ci
cp .env.example .env
npm run dev

Health check:

curl http://localhost:3000/health

Environment Variables

Minimum local Pinterest setup:

PINTEREST_ACCESS_TOKEN=

Refresh-capable setup:

PINTEREST_APP_ID=
PINTEREST_APP_SECRET=
PINTEREST_REFRESH_TOKEN=
PINTEREST_ACCESS_TOKEN=
PINTEREST_ACCESS_TOKEN_EXPIRES_AT=

MCP gate:

MCP_AUTH_MODE=none|bearer
MCP_BEARER_TOKEN=

Pinterest Developer Setup

Based on the official Pinterest docs checked on August 13, 2026:

• Pinterest API uses v5.
• OAuth token endpoint is https://api.pinterest.com/v5/oauth/token.
• Authorization Code flow is the recommended full-capability flow.
• Pinterest now uses continuous refresh tokens with 60-day expiry and indefinite refresh as long as they are rotated in time.
• Relevant scopes are confirmed in the official docs:
  • boards:read
  • pins:read
  • user_accounts:read
  • boards:read_secret
  • pins:read_secret
• Official user pin search exists at GET /search/pins, so this server uses that endpoint when possible.

OAuth and MCP Auth

Pinterest OAuth and MCP auth are separate:

• Pinterest OAuth protects access to Pinterest data.
• MCP auth protects the PinterestMCP endpoint from arbitrary clients.

OpenAI's current docs state that user-specific remote MCP data should be protected with OAuth rather than an anonymous public endpoint. This repo therefore keeps MCP auth configurable and isolates it from the Pinterest client layer.

Deployment

Vercel is supported through:

• api/index.ts
• vercel.json

Build locally:

npm run build

ChatGPT Connection

Two realistic paths exist:

1. Manual MCP connection for local/private testing.
2. Workspace app / remote MCP rollout after production auth is added.

Useful checks before connecting:

curl http://localhost:3000/health
curl -X POST http://localhost:3000/mcp -H 'Content-Type: application/json' -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"curl","version":"1.0.0"}}}'

Testing

Run the full local verification suite:

npm run lint
npm run typecheck
npm test
npm run build

What is covered:

• normalizers
• pagination
• search ranking
• error mapping
• image host validation
• MCP initialize + tools/list
• MCP pinterest_get_pin_image image-content delivery

Optional smoke coverage:

• tests/pinterest-smoke.test.ts activates only when Pinterest credentials are present.

Security

See SECURITY.md.

Limitations

• No write operations by design.
• Production-grade MCP OAuth is not implemented yet.
• Real Pinterest verification depends on valid Pinterest credentials.
• Final ChatGPT workspace-app verification depends on OpenAI workspace permissions and browser-side setup.

Troubleshooting

• 401 unauthorized on /mcp: check MCP_AUTH_MODE and MCP_BEARER_TOKEN.
• pinterest_not_configured: add a Pinterest access token or refresh-capable credentials.
• image_url_untrusted_host: the pin image host is outside the Pinterest CDN allowlist.
• Empty search results with local fallback: provide boardId or enable official search.