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

Related MCP server: pinterest-mcp

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.

Troubleshooting

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