# 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

```mermaid
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:

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

Health check:

```bash
curl http://localhost:3000/health
```

## Environment Variables

Minimum local Pinterest setup:

```text
PINTEREST_ACCESS_TOKEN=
```

Refresh-capable setup:

```text
PINTEREST_APP_ID=
PINTEREST_APP_SECRET=
PINTEREST_REFRESH_TOKEN=
PINTEREST_ACCESS_TOKEN=
PINTEREST_ACCESS_TOKEN_EXPIRES_AT=
```

MCP gate:

```text
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](/Users/erdc/Documents/PinterestMCP/api/index.ts)
- [vercel.json](/Users/erdc/Documents/PinterestMCP/vercel.json)

Build locally:

```bash
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:

```bash
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:

```bash
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](/Users/erdc/Documents/PinterestMCP/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.