@channel47/pinterest-ads-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 channel47
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,194 @@
+# @channel47/pinterest-ads-mcp
+
+MCP server for Pinterest Ads using the Pinterest REST API (`v5`).
+
+This server exposes four tools expected by channel47 Pinterest workflows:
+
+- `list_accounts`
+- `query`
+- `analytics`
+- `mutate`
+
+## Installation
+
+### Standalone
+
+```bash
+npx @channel47/pinterest-ads-mcp@latest
+```
+
+### Monorepo Development
+
+```bash
+cd mcps
+npm install
+npm run test
+```
+
+## Configuration
+
+### Getting Credentials
+
+1. Create an app at [developers.pinterest.com/apps](https://developers.pinterest.com/apps/) and request Standard access for the `ads:read` (and `ads:write` for mutations) scopes.
+2. Complete the OAuth authorization-code flow to obtain an access token and refresh token — see [Set up authentication and authorization](https://developers.pinterest.com/docs/getting-started/set-up-authentication-and-authorization/).
+3. Either paste a valid access token into `PINTEREST_ADS_ACCESS_TOKEN`, or configure the client credentials + refresh token and let this server mint access tokens itself.
+
+### Required (one of the two options)
+
+| Variable | Description |
+|----------|-------------|
+| `PINTEREST_ADS_ACCESS_TOKEN` | Pinterest OAuth access token (sent as `Authorization: Bearer`) |
+
+or all three of:
+
+| Variable | Description |
+|----------|-------------|
+| `PINTEREST_ADS_CLIENT_ID` | Pinterest app ID |
+| `PINTEREST_ADS_CLIENT_SECRET` | Pinterest app secret |
+| `PINTEREST_ADS_REFRESH_TOKEN` | OAuth refresh token used to mint access tokens via `POST /v5/oauth/token` |
+
+When both are configured, the refresh-token flow wins. Access tokens are cached in
+memory and refreshed about 5 minutes before expiry. Pinterest uses continuous
+refresh tokens and may rotate the refresh token on use — the server logs a stderr
+warning when that happens because it cannot persist the new value; update
+`PINTEREST_ADS_REFRESH_TOKEN` yourself when you see the warning.
+
+### Optional
+
+| Variable | Description |
+|----------|-------------|
+| `PINTEREST_ADS_AD_ACCOUNT_ID` | Default ad account ID used when `ad_account_id` is omitted |
+| `PINTEREST_ADS_READ_ONLY` | Set to `true` to disable live mutations |
+| `PINTEREST_ADS_REQUEST_TIMEOUT_MS` | HTTP request timeout in milliseconds (default `30000`) |
+
+### Claude Code
+
+```bash
+claude mcp add pinterest-ads \
+  --env PINTEREST_ADS_ACCESS_TOKEN=<token> \
+  --env PINTEREST_ADS_AD_ACCOUNT_ID=<ad-account-id> \
+  -- npx @channel47/pinterest-ads-mcp@latest
+```
+
+Or as JSON config:
+
+```json
+{
+  "mcpServers": {
+    "pinterest-ads": {
+      "command": "npx",
+      "args": ["@channel47/pinterest-ads-mcp@latest"],
+      "env": {
+        "PINTEREST_ADS_ACCESS_TOKEN": "<token>",
+        "PINTEREST_ADS_AD_ACCOUNT_ID": "<ad-account-id>"
+      }
+    }
+  }
+}
+```
+
+## Tool Reference
+
+### `list_accounts`
+
+List accessible ad accounts from `GET /ad_accounts` with bookmark pagination.
+
+**Params:**
+- `include_shared_accounts` (optional): include accounts shared with you (API default `true`)
+
+**Notes:**
+- Returns `id`, `name`, `currency`, `country`, `owner_username`, `time_zone`, `permissions`
+- Follows bookmark pagination to return all accessible accounts
+
+### `query`
+
+Structured entity reads over:
+
+- `campaigns` — `GET /ad_accounts/{id}/campaigns`
+- `ad_groups` — `GET /ad_accounts/{id}/ad_groups`
+- `ads` — `GET /ad_accounts/{id}/ads`
+
+**Params:**
+- `entity` (required)
+- `ad_account_id` (optional if `PINTEREST_ADS_AD_ACCOUNT_ID` exists)
+- `entity_statuses`: `ACTIVE`, `PAUSED`, `ARCHIVED`, `DRAFT`, `DELETED_DRAFT` — the API defaults to `ACTIVE, PAUSED`, so pass this to see archived entities
+- `campaign_ids` / `ad_group_ids` / `ad_ids`: id filters (each only where the endpoint supports it)
+- `order`: `ASCENDING` | `DESCENDING` by ID
+- `limit`: rows to return across pages (default `100`, max `1000`; API pages are max `250`)
+
+### `analytics`
+
+Metrics via the v5 analytics endpoints:
+
+- `account` — `GET /ad_accounts/{id}/analytics`
+- `campaign` — `GET /ad_accounts/{id}/campaigns/analytics` (requires `campaign_ids`)
+- `ad_group` — `GET /ad_accounts/{id}/ad_groups/analytics` (requires `ad_group_ids`)
+- `ad` — `GET /ad_accounts/{id}/ads/analytics` (requires `ad_ids`)
+
+**Params:**
+- `start_date` / `end_date` (required, `YYYY-MM-DD`): at most 90 days back and a 90-day range
+- `level`: `account` (default), `campaign`, `ad_group`, `ad`
+- `columns`: defaults to `SPEND_IN_DOLLAR, IMPRESSION_2, CLICKTHROUGH_2, CTR_2, TOTAL_CONVERSIONS` (see the `pinterestads://analytics-columns` resource)
+- `granularity`: `TOTAL` (default), `DAY`, `WEEK`, `MONTH`, `HOUR` (`HOUR` no longer returns conversion metrics)
+- `click_window_days` / `engagement_window_days` / `view_window_days`: `0, 1, 7, 14, 30, 60`
+- `conversion_report_time`: `TIME_OF_AD_ACTION` | `TIME_OF_CONVERSION`
+- `reporting_timezone`: `PINTEREST_TIME_ZONE` | `AD_ACCOUNT_TIME_ZONE`
+
+### `mutate`
+
+Mutation tool with dry-run safety by default.
+
+**Operation format:**
+
+```json
+{
+  "entity": "campaign",
+  "action": "update",
+  "id": "626735565838",
+  "params": {
+    "daily_spend_cap": 25000000
+  }
+}
+```
+
+**Supported entities:** `campaign`, `ad_group`, `ad`
+
+**Supported actions:** `create`, `update`, `pause`, `enable`, `archive`
+
+**Top-level params:**
+- `operations` (required)
+- `dry_run` (default `true`)
+- `partial_failure` (default `true`)
+
+**Notes:**
+- Pinterest v5 uses bulk-array bodies: creates are `POST /ad_accounts/{id}/{campaigns|ad_groups|ads}` with an array of creation objects; updates and status changes are `PATCH` with an array of `{ id, ...changes }`
+- **There is no delete.** `archive` sets `status: ARCHIVED`, which is terminal — archived entities cannot be reactivated
+- Pinterest has no server-side validate-only mode, so `dry_run` performs local validation and returns a preview of the exact requests (method, path, body) without calling the API
+- Creates default to `status: PAUSED` (pass an explicit `status` to override)
+- Required create fields — campaign: `name`, `objective_type`; ad_group: `name`, `campaign_id`, `billable_event`; ad: `ad_group_id`, `pin_id`, `creative_type`
+- Money fields (spend caps, budgets, bids) are in micro-currency: `25000000` = 25.00 in the account currency
+
+## Read-Only Mode
+
+Set `PINTEREST_ADS_READ_ONLY=true` to remove the `mutate` tool from the tool list
+and block mutate calls entirely. Recommended for reporting-only setups.
+
+## Behavior Notes
+
+- Auth is sent via `Authorization: Bearer <token>` request header
+- Retries once on HTTP `429`, using `Retry-After` when available (fallback `60s`)
+- Requests abort on timeout (default `30000ms`, configurable via `PINTEREST_ADS_REQUEST_TIMEOUT_MS`)
+- Errors surface as `Pinterest Ads API request failed (<status>): <message> [code <n>]`
+- Pagination uses `page_size` (max 250) + `bookmark` cursors; responses are `{ items, bookmark }`
+
+## Development Commands
+
+```bash
+cd pinterest-ads
+npm test
+node server/index.js
+```
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@channel47/pinterest-ads-mcp",
+  "version": "0.1.0",
+  "description": "Pinterest Ads MCP Server - Query and mutate Pinterest advertising data via REST API v5",
+  "main": "server/index.js",
+  "bin": {
+    "pinterest-ads-mcp": "server/index.js"
+  },
+  "type": "module",
+  "files": [
+    "server/**/*.js",
+    "server/**/*.md",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "start": "node server/index.js",
+    "test": "node --test *.test.js test/*.test.js",
+    "prepublishOnly": "npm test"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "pinterest-ads",
+    "pinterest",
+    "analytics",
+    "advertising",
+    "claude"
+  ],
+  "author": "channel47",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/channel47/mcps.git",
+    "directory": "pinterest-ads"
+  },
+  "bugs": {
+    "url": "https://github.com/channel47/mcps/issues"
+  },
+  "homepage": "https://github.com/channel47/mcps/tree/main/pinterest-ads#readme",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/server/auth.js

@@ -0,0 +1,141 @@
+const TOKEN_URL = 'https://api.pinterest.com/v5/oauth/token';
+const REFRESH_ENV_VARS = [
+  'PINTEREST_ADS_CLIENT_ID',
+  'PINTEREST_ADS_CLIENT_SECRET',
+  'PINTEREST_ADS_REFRESH_TOKEN'
+];
+const REFRESH_MARGIN_MS = 5 * 60 * 1000;
+
+let cachedAccessToken = null;
+let cachedTokenExpiresAt = null;
+
+function hasStaticToken() {
+  return Boolean(process.env.PINTEREST_ADS_ACCESS_TOKEN);
+}
+
+function missingRefreshVars() {
+  return REFRESH_ENV_VARS.filter((name) => !process.env[name]);
+}
+
+function hasRefreshCredentials() {
+  return missingRefreshVars().length === 0;
+}
+
+/**
+ * Validate required environment variables for Pinterest Ads auth.
+ * Valid when PINTEREST_ADS_ACCESS_TOKEN is set, or when all of
+ * PINTEREST_ADS_CLIENT_ID + PINTEREST_ADS_CLIENT_SECRET + PINTEREST_ADS_REFRESH_TOKEN are set.
+ * @returns {{ valid: boolean, missing: string[] }}
+ */
+export function validateEnvironment() {
+  if (hasStaticToken() || hasRefreshCredentials()) {
+    return { valid: true, missing: [] };
+  }
+
+  const partialRefresh = missingRefreshVars().length < REFRESH_ENV_VARS.length;
+  if (partialRefresh) {
+    return { valid: false, missing: missingRefreshVars() };
+  }
+
+  return { valid: false, missing: ['PINTEREST_ADS_ACCESS_TOKEN'] };
+}
+
+function extractRefreshErrorMessage(payload) {
+  if (payload && typeof payload === 'object') {
+    return payload.message || payload.error_description || payload.error || 'Unknown OAuth error';
+  }
+
+  if (typeof payload === 'string' && payload) {
+    return payload;
+  }
+
+  return 'Unknown OAuth error';
+}
+
+async function refreshAccessToken(fetchImpl) {
+  const clientId = process.env.PINTEREST_ADS_CLIENT_ID;
+  const clientSecret = process.env.PINTEREST_ADS_CLIENT_SECRET;
+  const refreshToken = process.env.PINTEREST_ADS_REFRESH_TOKEN;
+  const basicAuth = Buffer.from(`${clientId}:${clientSecret}`).toString('base64');
+
+  const body = new URLSearchParams({
+    grant_type: 'refresh_token',
+    refresh_token: refreshToken
+  });
+
+  const response = await fetchImpl(TOKEN_URL, {
+    method: 'POST',
+    headers: {
+      Authorization: `Basic ${basicAuth}`,
+      'Content-Type': 'application/x-www-form-urlencoded'
+    },
+    body: body.toString()
+  });
+
+  let payload;
+  try {
+    payload = await response.json();
+  } catch {
+    payload = null;
+  }
+
+  if (!response.ok || !payload?.access_token) {
+    const message = extractRefreshErrorMessage(payload);
+    throw new Error(`Pinterest Ads token refresh failed (${response.status}): ${message}`);
+  }
+
+  if (payload.refresh_token && payload.refresh_token !== refreshToken) {
+    console.error(
+      'Warning: Pinterest rotated the refresh token (continuous refresh). '
+      + 'Update PINTEREST_ADS_REFRESH_TOKEN with the new value or future refreshes may fail.'
+    );
+  }
+
+  const expiresInMs = Number(payload.expires_in || 0) * 1000;
+  cachedAccessToken = String(payload.access_token);
+  cachedTokenExpiresAt = expiresInMs > 0 ? Date.now() + expiresInMs - REFRESH_MARGIN_MS : null;
+
+  return cachedAccessToken;
+}
+
+/**
+ * Return a Pinterest Ads access token with in-memory caching.
+ * Prefers the refresh-token flow when full OAuth credentials are configured;
+ * otherwise falls back to the static PINTEREST_ADS_ACCESS_TOKEN value.
+ * @param {{ fetchImpl?: typeof fetch }} [dependencies]
+ * @returns {Promise<string>}
+ */
+export async function getAccessToken(dependencies = {}) {
+  const fetchImpl = dependencies.fetchImpl || fetch;
+
+  const { valid, missing } = validateEnvironment();
+  if (!valid) {
+    throw new Error(`Missing required environment variables: ${missing.join(', ')}`);
+  }
+
+  if (hasRefreshCredentials()) {
+    const cacheIsFresh = cachedAccessToken
+      && (cachedTokenExpiresAt === null || Date.now() < cachedTokenExpiresAt);
+    if (cacheIsFresh) {
+      return cachedAccessToken;
+    }
+
+    return refreshAccessToken(fetchImpl);
+  }
+
+  if (cachedAccessToken) {
+    return cachedAccessToken;
+  }
+
+  cachedAccessToken = String(process.env.PINTEREST_ADS_ACCESS_TOKEN);
+  cachedTokenExpiresAt = null;
+  return cachedAccessToken;
+}
+
+/**
+ * Clear the in-memory token cache (used by tests and local dev flows).
+ */
+export function clearAuthCache() {
+  cachedAccessToken = null;
+  cachedTokenExpiresAt = null;
+}

package/server/http.js

@@ -0,0 +1,198 @@
+import { getAccessToken } from './auth.js';
+import { invalidParamsError } from './utils/errors.js';
+
+/**
+ * Base URL for all Pinterest REST API v5 requests used by this server.
+ */
+export const PINTEREST_BASE_URL = 'https://api.pinterest.com/v5';
+const DEFAULT_TIMEOUT_MS = 30_000;
+const DEFAULT_RATE_LIMIT_SLEEP_MS = 60_000;
+
+function sleep(ms) {
+  return new Promise((resolve) => {
+    setTimeout(resolve, ms);
+  });
+}
+
+function normalizePath(path) {
+  if (!path) {
+    throw new Error('API path is required');
+  }
+
+  return path.startsWith('/') ? path : `/${path}`;
+}
+
+function serializeParamValue(value) {
+  if (Array.isArray(value)) {
+    return value.map((entry) => String(entry).trim()).filter(Boolean).join(',');
+  }
+
+  return String(value);
+}
+
+function buildUrl(path, params = {}) {
+  const url = new URL(`${PINTEREST_BASE_URL}${normalizePath(path)}`);
+
+  for (const [key, value] of Object.entries(params)) {
+    if (value === undefined || value === null || value === '') {
+      continue;
+    }
+
+    const serialized = serializeParamValue(value);
+    if (serialized === '') {
+      continue;
+    }
+    url.searchParams.set(key, serialized);
+  }
+
+  return url;
+}
+
+async function parseResponse(response) {
+  const contentType = response.headers.get('content-type') || '';
+
+  if (contentType.includes('application/json')) {
+    return response.json();
+  }
+
+  const text = await response.text();
+  try {
+    return JSON.parse(text);
+  } catch {
+    return text;
+  }
+}
+
+function extractErrorMessage(payload) {
+  if (payload?.message) {
+    return payload.message;
+  }
+
+  if (typeof payload === 'string' && payload) {
+    return payload;
+  }
+
+  return 'Unknown Pinterest Ads API error';
+}
+
+function extractErrorCode(payload) {
+  return Number(payload?.code || 0);
+}
+
+function resolveTimeoutMs(timeoutMs) {
+  const candidate = timeoutMs ?? process.env.PINTEREST_ADS_REQUEST_TIMEOUT_MS ?? DEFAULT_TIMEOUT_MS;
+  const parsed = Number(candidate);
+  if (!Number.isFinite(parsed) || parsed <= 0) {
+    return DEFAULT_TIMEOUT_MS;
+  }
+  return Math.floor(parsed);
+}
+
+function getRateLimitSleepMs(response) {
+  const retryAfter = response?.headers?.get('retry-after');
+  if (!retryAfter) {
+    return DEFAULT_RATE_LIMIT_SLEEP_MS;
+  }
+
+  const seconds = Number(retryAfter);
+  if (Number.isFinite(seconds) && seconds > 0) {
+    return Math.floor(seconds * 1000);
+  }
+
+  const retryAtMs = Date.parse(retryAfter);
+  if (Number.isFinite(retryAtMs)) {
+    const delta = retryAtMs - Date.now();
+    if (delta > 0) {
+      return Math.floor(delta);
+    }
+  }
+
+  return DEFAULT_RATE_LIMIT_SLEEP_MS;
+}
+
+/**
+ * Execute an authenticated Pinterest REST API v5 request with timeout and retry handling.
+ * Array query parameter values are serialized as comma-separated strings per Pinterest conventions.
+ * @param {string} path
+ * @param {Record<string, unknown>} [params]
+ * @param {{
+ *   method?: string,
+ *   body?: unknown,
+ *   timeoutMs?: number,
+ *   retryThrottled?: boolean,
+ *   sleep?: (ms: number) => Promise<void>
+ * }} [options]
+ * @returns {Promise<unknown>}
+ */
+export async function pinterestRequest(
+  path,
+  params = {},
+  {
+    method = 'GET',
+    body,
+    timeoutMs,
+    retryThrottled = true,
+    sleep: sleepFn = sleep
+  } = {}
+) {
+  const token = await getAccessToken();
+  const url = buildUrl(path, params);
+  const resolvedTimeoutMs = resolveTimeoutMs(timeoutMs);
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => {
+    controller.abort();
+  }, resolvedTimeoutMs);
+
+  const requestOptions = {
+    method,
+    headers: {
+      'Content-Type': 'application/json',
+      Authorization: `Bearer ${token}`
+    },
+    signal: controller.signal
+  };
+
+  if (body !== undefined && body !== null) {
+    requestOptions.body = typeof body === 'string' ? body : JSON.stringify(body);
+  }
+
+  let response;
+  try {
+    response = await fetch(url, requestOptions);
+  } catch (error) {
+    if (error?.name === 'AbortError') {
+      throw new Error(`Pinterest Ads API request timed out after ${resolvedTimeoutMs}ms`);
+    }
+    throw error;
+  } finally {
+    clearTimeout(timeoutId);
+  }
+
+  const payload = await parseResponse(response);
+
+  if (response.ok) {
+    return payload;
+  }
+
+  if (response.status === 401) {
+    const message = extractErrorMessage(payload);
+    throw invalidParamsError(`Pinterest Ads API request failed (${response.status}): ${message}`);
+  }
+
+  if (response.status === 429 && retryThrottled) {
+    await sleepFn(getRateLimitSleepMs(response));
+
+    return pinterestRequest(path, params, {
+      method,
+      body,
+      timeoutMs: resolvedTimeoutMs,
+      retryThrottled: false,
+      sleep: sleepFn
+    });
+  }
+
+  const message = extractErrorMessage(payload);
+  const code = extractErrorCode(payload);
+  const codeSuffix = code ? ` [code ${code}]` : '';
+  throw new Error(`Pinterest Ads API request failed (${response.status}): ${message}${codeSuffix}`);
+}