Pinterest Business MCP

Local Model Context Protocol server for Pinterest Business workflows. This repository includes a stdio MCP server, Pinterest OAuth connection tools, encrypted local token storage, and server status reporting.

Requirements

• Node.js 22+
• pnpm 11+
• A Pinterest developer app with the redirect URI below

Pinterest developer dashboard setup

1. Sign in at Pinterest Developers.

2. Create or open your app.

3. Under Configure, add this exact redirect URI:

   http://127.0.0.1:3333/oauth/callback

4. Copy your App ID and App secret key.

5. Request the scopes your workflow needs. At minimum, connection testing commonly uses read scopes such as boards:read, pins:read, and user_accounts:read.

6. For sandbox testing, keep PINTEREST_ENVIRONMENT=sandbox. Pinterest uses the same OAuth authorize page for both environments; token exchange uses the sandbox API host when sandbox is selected.

Local setup

pnpm install
cp .env.example .env

Edit .env and set at minimum:

PINTEREST_ENVIRONMENT=sandbox
PINTEREST_APP_ID=your-app-id
PINTEREST_APP_SECRET=your-app-secret
PINTEREST_TOKEN_ENCRYPTION_KEY=your-base64-key
PINTEREST_OAUTH_SCOPES=boards:read,pins:read,user_accounts:read

Generate an encryption key:

openssl rand -base64 32

Development

pnpm dev          # watch mode (tsx)
pnpm build        # compile to dist/
pnpm start        # run compiled server
pnpm verify       # typecheck, lint, test, build

MCP client configuration (Cursor)

Add a project-scoped MCP server entry in .cursor/mcp.json (recommended) or your user MCP settings. Do not commit real secrets.

{
  "mcpServers": {
    "pinterest-business": {
      "command": "node",
      "args": ["/absolute/path/to/pinterest-business-mcp/dist/index.js"],
      "env": {
        "PINTEREST_ENVIRONMENT": "sandbox",
        "PINTEREST_APP_ID": "your-app-id",
        "PINTEREST_APP_SECRET": "your-app-secret",
        "PINTEREST_TOKEN_ENCRYPTION_KEY": "your-base64-key",
        "PINTEREST_OAUTH_SCOPES": "boards:read,pins:read,user_accounts:read",
        "PINTEREST_WRITES_ENABLED": "false",
        "LOG_LEVEL": "info"
      }
    }
  }
}

Restart Cursor after changing MCP configuration.

Connecting your Pinterest Business account

1. Start the MCP server in Cursor.
2. Call pinterest_get_authorization_url.
3. Open the returned authorization URL in your browser.
4. Approve the Pinterest app when prompted.
5. Wait for the local callback page at http://127.0.0.1:3333/oauth/callback to report success.
6. Call pinterest_connection_status to confirm the connection.

The MCP server never asks for your Pinterest password. Authentication happens only on Pinterest's official OAuth page.

Sandbox setup

• Set PINTEREST_ENVIRONMENT=sandbox.
• Use the same redirect URI: http://127.0.0.1:3333/oauth/callback.
• OAuth authorization still starts at https://www.pinterest.com/oauth/.
• Token exchange and refresh use https://api-sandbox.pinterest.com/v5/oauth/token.

Tools

pinterest_server_status

Returns server metadata and configuration flags only — never credential values.

pinterest_get_authorization_url

Starts the local callback listener on 127.0.0.1:3333, creates a single-use OAuth state value, and returns the Pinterest authorization URL plus safe instructions. Tokens are never returned by this tool.

Optional input:

• scopes: array of official Pinterest scopes. If omitted, PINTEREST_OAUTH_SCOPES is used.

pinterest_connection_status

Reports whether a Pinterest account is connected locally, including scope and expiry metadata. Tokens are never returned. Expired access tokens are refreshed automatically when a valid refresh token is available.

pinterest_disconnect

Securely removes locally stored OAuth authorization data. To revoke access on Pinterest itself, remove the app from Pinterest settings under Security and logins → Apps.

Environment variables

See .env.example for the full list.

Variable	Required	Description
PINTEREST_ENVIRONMENT	Yes	sandbox or production
PINTEREST_APP_ID	OAuth	Pinterest app ID
PINTEREST_APP_SECRET	OAuth	Pinterest app secret
PINTEREST_TOKEN_ENCRYPTION_KEY	OAuth	Base64 or passphrase used for AES-256-GCM token encryption
PINTEREST_TOKEN_STORE_PATH	No	Encrypted token file path (default: .tokens/pinterest-oauth.enc)
PINTEREST_OAUTH_SCOPES	OAuth	Default scopes unless overridden by the authorization tool
PINTEREST_WRITES_ENABLED	No	true or false (default: false)
LOG_LEVEL	No	debug, info, warn, or error

Troubleshooting

Problem	What to check
Callback port already in use	Another OAuth attempt or process is using 127.0.0.1:3333. Wait for it to finish or stop the other process.
Redirect URI mismatch	The Pinterest app must contain the exact URI http://127.0.0.1:3333/oauth/callback.
Missing scopes	Set PINTEREST_OAUTH_SCOPES or pass scopes to pinterest_get_authorization_url.
Connection not stored	Confirm PINTEREST_TOKEN_ENCRYPTION_KEY is set and writable, then repeat the OAuth flow.
Sandbox token exchange failed	Keep PINTEREST_ENVIRONMENT=sandbox so token exchange uses the sandbox API host.
Refresh failed	Reconnect with pinterest_get_authorization_url if the refresh token expired or was revoked.

Token revocation and disconnect

• Local disconnect: call pinterest_disconnect.
• Pinterest-side revocation: open Pinterest settings → Security and logins → Apps and remove this app.
• Pinterest's remote revocation endpoint is unreliable in some app states, so local disconnect plus manual app removal is the supported recovery path.

Security

See SECURITY.md for credential handling and threat boundaries.

License

MIT