@channel47/pinterest-ads-mcp 0.1.0

package/server/index.js

@@ -0,0 +1,272 @@
+#!/usr/bin/env node
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import {
+  CallToolRequestSchema,
+  GetPromptRequestSchema,
+  ListPromptsRequestSchema,
+  ListResourcesRequestSchema,
+  ListToolsRequestSchema,
+  ReadResourceRequestSchema
+} from '@modelcontextprotocol/sdk/types.js';
+
+import { validateEnvironment } from './auth.js';
+import { listAccounts } from './tools/list-accounts.js';
+import { query } from './tools/query.js';
+import { analytics } from './tools/analytics.js';
+import { mutate } from './tools/mutate.js';
+import { getPromptsList, renderPrompt } from './prompts/templates.js';
+import { getResourcesList, readResource } from './resources/index.js';
+
+const SERVER_NAME = 'pinterest-ads-mcp';
+const SERVER_VERSION = '0.1.0';
+const READ_ONLY = process.env.PINTEREST_ADS_READ_ONLY === 'true';
+
+const IDS_FILTER_SCHEMA = {
+  anyOf: [
+    { type: 'string' },
+    {
+      type: 'array',
+      items: { type: 'string' }
+    }
+  ]
+};
+
+const ALL_TOOLS = [
+  {
+    name: 'list_accounts',
+    description: 'List all accessible Pinterest ad accounts for the authenticated token, including id, name, currency, country, and owner.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        include_shared_accounts: {
+          type: 'boolean',
+          description: 'Include ad accounts shared with the authenticated user (API default: true)'
+        }
+      }
+    }
+  },
+  {
+    name: 'query',
+    description: 'Query Pinterest Ads campaigns, ad_groups, or ads with optional entity status and id filters. Note: the API returns only ACTIVE and PAUSED entities by default — pass entity_statuses to include ARCHIVED or DRAFT.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        ad_account_id: {
+          type: 'string',
+          description: 'Pinterest ad account ID (falls back to PINTEREST_ADS_AD_ACCOUNT_ID)'
+        },
+        entity: {
+          type: 'string',
+          enum: ['campaigns', 'ad_groups', 'ads'],
+          description: 'Entity type to query'
+        },
+        entity_statuses: {
+          ...IDS_FILTER_SCHEMA,
+          description: 'Status filter: ACTIVE, PAUSED, ARCHIVED, DRAFT, DELETED_DRAFT (API default: ACTIVE, PAUSED)'
+        },
+        campaign_ids: {
+          ...IDS_FILTER_SCHEMA,
+          description: 'Filter by campaign IDs (comma-separated string or array)'
+        },
+        ad_group_ids: {
+          ...IDS_FILTER_SCHEMA,
+          description: 'Filter by ad group IDs (ad_groups and ads entities only)'
+        },
+        ad_ids: {
+          ...IDS_FILTER_SCHEMA,
+          description: 'Filter by ad IDs (ads entity only)'
+        },
+        order: {
+          type: 'string',
+          enum: ['ASCENDING', 'DESCENDING'],
+          description: 'Sort order by ID (higher IDs are more recently created)'
+        },
+        limit: {
+          type: 'integer',
+          minimum: 1,
+          maximum: 1000,
+          description: 'Maximum rows to return across pages (default: 100, max: 1000)'
+        }
+      },
+      required: ['entity']
+    }
+  },
+  {
+    name: 'analytics',
+    description: 'Pull Pinterest Ads analytics at account, campaign, ad_group, or ad level. Entity levels require the matching ids param (campaign_ids, ad_group_ids, ad_ids). Dates are YYYY-MM-DD, at most 90 days back and a 90-day range.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        ad_account_id: {
+          type: 'string',
+          description: 'Pinterest ad account ID (falls back to PINTEREST_ADS_AD_ACCOUNT_ID)'
+        },
+        level: {
+          type: 'string',
+          enum: ['account', 'campaign', 'ad_group', 'ad'],
+          description: 'Reporting level (default: account)'
+        },
+        start_date: {
+          type: 'string',
+          description: 'Report start date (YYYY-MM-DD, UTC). Cannot be more than 90 days back from today.'
+        },
+        end_date: {
+          type: 'string',
+          description: 'Report end date (YYYY-MM-DD, UTC). Cannot be more than 90 days past start_date.'
+        },
+        columns: {
+          ...IDS_FILTER_SCHEMA,
+          description: 'Metric columns (default: SPEND_IN_DOLLAR, IMPRESSION_2, CLICKTHROUGH_2, CTR_2, TOTAL_CONVERSIONS). See the pinterestads://analytics-columns resource.'
+        },
+        granularity: {
+          type: 'string',
+          enum: ['TOTAL', 'DAY', 'WEEK', 'MONTH', 'HOUR'],
+          description: 'Time breakdown (default: TOTAL). HOUR no longer returns conversion metrics.'
+        },
+        campaign_ids: {
+          ...IDS_FILTER_SCHEMA,
+          description: 'Campaign IDs (required for level=campaign)'
+        },
+        ad_group_ids: {
+          ...IDS_FILTER_SCHEMA,
+          description: 'Ad group IDs (required for level=ad_group)'
+        },
+        ad_ids: {
+          ...IDS_FILTER_SCHEMA,
+          description: 'Ad IDs (required for level=ad)'
+        },
+        click_window_days: {
+          type: 'integer',
+          enum: [0, 1, 7, 14, 30, 60],
+          description: 'Click attribution window in days (API default: 30)'
+        },
+        engagement_window_days: {
+          type: 'integer',
+          enum: [0, 1, 7, 14, 30, 60],
+          description: 'Engagement attribution window in days (API default: 30)'
+        },
+        view_window_days: {
+          type: 'integer',
+          enum: [0, 1, 7, 14, 30, 60],
+          description: 'View attribution window in days (API default: 1)'
+        },
+        conversion_report_time: {
+          type: 'string',
+          enum: ['TIME_OF_AD_ACTION', 'TIME_OF_CONVERSION'],
+          description: 'Report conversions by ad action time or conversion time (API default: TIME_OF_AD_ACTION)'
+        },
+        reporting_timezone: {
+          type: 'string',
+          enum: ['PINTEREST_TIME_ZONE', 'AD_ACCOUNT_TIME_ZONE'],
+          description: 'Timezone used to bucket metrics'
+        }
+      },
+      required: ['start_date', 'end_date']
+    }
+  },
+  {
+    name: 'mutate',
+    description: 'Execute create/update/pause/enable/archive operations for campaign, ad_group, and ad entities via Pinterest bulk-array endpoints. dry_run defaults to true and performs local validation plus a preview of the exact requests (Pinterest has no server-side validate-only mode). Creates default to PAUSED status. Pinterest has NO delete — archive (status ARCHIVED) is the terminal state and archived entities cannot be reactivated. Campaign creates require name and objective_type; ad_group creates require name, campaign_id, and billable_event; ad creates require ad_group_id, pin_id, and creative_type.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        ad_account_id: {
+          type: 'string',
+          description: 'Pinterest ad account ID (falls back to PINTEREST_ADS_AD_ACCOUNT_ID)'
+        },
+        operations: {
+          type: 'array',
+          description: 'Array of operation objects: { entity, action, id?, params? }',
+          items: {
+            type: 'object'
+          }
+        },
+        dry_run: {
+          type: 'boolean',
+          description: 'Validate and preview only (default: true)',
+          default: true
+        },
+        partial_failure: {
+          type: 'boolean',
+          description: 'Continue executing later operations when one fails (default: true)',
+          default: true
+        }
+      },
+      required: ['operations']
+    }
+  }
+];
+
+const TOOLS = READ_ONLY ? ALL_TOOLS.filter((tool) => tool.name !== 'mutate') : ALL_TOOLS;
+
+const envStatus = validateEnvironment();
+if (!envStatus.valid) {
+  console.error(`Missing required environment variables: ${envStatus.missing.join(', ')}`);
+  console.error('Set PINTEREST_ADS_ACCESS_TOKEN, or all of PINTEREST_ADS_CLIENT_ID + PINTEREST_ADS_CLIENT_SECRET + PINTEREST_ADS_REFRESH_TOKEN for the refresh-token flow.');
+  process.exit(1);
+}
+
+if (READ_ONLY) {
+  console.error('Read-only mode enabled — mutate tool disabled');
+}
+
+const server = new Server(
+  {
+    name: SERVER_NAME,
+    version: SERVER_VERSION
+  },
+  {
+    capabilities: {
+      tools: {},
+      prompts: {},
+      resources: {}
+    }
+  }
+);
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: params } = request.params;
+
+  if (name === 'list_accounts') {
+    return listAccounts(params);
+  }
+
+  if (name === 'query') {
+    return query(params);
+  }
+
+  if (name === 'analytics') {
+    return analytics(params);
+  }
+
+  if (name === 'mutate') {
+    if (READ_ONLY) {
+      throw new Error('mutate is disabled in read-only mode (PINTEREST_ADS_READ_ONLY=true)');
+    }
+    return mutate(params);
+  }
+
+  throw new Error(`Unknown tool: ${name}`);
+});
+
+server.setRequestHandler(ListPromptsRequestSchema, async () => ({ prompts: getPromptsList() }));
+server.setRequestHandler(GetPromptRequestSchema, async (request) => (
+  renderPrompt(request.params.name, request.params.arguments || {})
+));
+
+server.setRequestHandler(ListResourcesRequestSchema, async () => ({ resources: getResourcesList() }));
+server.setRequestHandler(ReadResourceRequestSchema, async (request) => readResource(request.params.uri));
+
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error(`${SERVER_NAME} v${SERVER_VERSION} started`);
+}
+
+main().catch((error) => {
+  console.error('Fatal error:', error);
+  process.exit(1);
+});

package/server/prompts/templates.js

@@ -0,0 +1,130 @@
+export const PROMPT_TEMPLATES = {
+  spend_pacing_check: {
+    name: 'spend_pacing_check',
+    description: 'Check campaign spend pacing against budgets and recent delivery',
+    arguments: [
+      {
+        name: 'ad_account_id',
+        description: 'Pinterest ad account ID',
+        required: true
+      },
+      {
+        name: 'start_date',
+        description: 'Report start date (YYYY-MM-DD, within the last 90 days)',
+        required: true
+      },
+      {
+        name: 'end_date',
+        description: 'Report end date (YYYY-MM-DD)',
+        required: true
+      }
+    ],
+    template: `Run a spend pacing check for Pinterest ad account {{ad_account_id}} from {{start_date}} to {{end_date}}:
+
+1. Query active campaigns with their daily_spend_cap and lifetime_spend_cap values.
+2. Pull campaign-level analytics (SPEND_IN_DOLLAR, IMPRESSION_2, CLICKTHROUGH_2, TOTAL_CONVERSIONS) with DAY granularity.
+3. Compare daily spend velocity against spend caps (caps are in micro-currency: 1,000,000 = 1 unit).
+4. Flag campaigns underpacing (spend well below cap) and overpacing (near or at cap early in the day).
+5. Highlight campaigns spending with weak conversion signals.
+6. Return top pacing issues with recommended budget actions.`,
+    requiredTools: ['query', 'analytics']
+  },
+  creative_performance_review: {
+    name: 'creative_performance_review',
+    description: 'Review ad-level performance and flag fatigued or underperforming Pins',
+    arguments: [
+      {
+        name: 'ad_account_id',
+        description: 'Pinterest ad account ID',
+        required: true
+      },
+      {
+        name: 'start_date',
+        description: 'Report start date (YYYY-MM-DD, within the last 90 days)',
+        required: true
+      },
+      {
+        name: 'end_date',
+        description: 'Report end date (YYYY-MM-DD)',
+        required: true
+      }
+    ],
+    template: `Run a creative performance review for Pinterest ad account {{ad_account_id}} from {{start_date}} to {{end_date}}:
+
+1. Query active ads to collect ad IDs, names, creative types, and parent ad groups.
+2. Pull ad-level analytics (SPEND_IN_DOLLAR, IMPRESSION_2, CLICKTHROUGH_2, CTR_2, TOTAL_ENGAGEMENT, TOTAL_CONVERSIONS) with WEEK granularity.
+3. Flag ads with declining week-over-week CTR or engagement despite sustained impressions.
+4. Group weak performers by ad group and campaign to spot structural issues.
+5. Rank creatives to refresh first by wasted spend.
+6. Return prioritized creative refresh recommendations with rationale.`,
+    requiredTools: ['query', 'analytics']
+  },
+  account_structure_audit: {
+    name: 'account_structure_audit',
+    description: 'Audit campaign and ad group structure for objective and budget hygiene',
+    arguments: [
+      {
+        name: 'ad_account_id',
+        description: 'Pinterest ad account ID',
+        required: true
+      }
+    ],
+    template: `Run an account structure audit for Pinterest ad account {{ad_account_id}}:
+
+1. Query all campaigns (include ACTIVE and PAUSED) with objective_type, spend caps, and status.
+2. Query ad groups with budgets, bid strategies, billable events, and targeting summaries.
+3. Flag campaigns with mismatched objective_type and ad group billable_event combinations.
+4. Identify ad groups without budgets, with overlapping targeting, or stuck in DRAFT status.
+5. Check for single-ad ad groups that limit creative rotation.
+6. Return a prioritized list of structural fixes with expected impact.`,
+    requiredTools: ['query']
+  }
+};
+
+export function getPromptDefinition(name) {
+  return PROMPT_TEMPLATES[name] || null;
+}
+
+export function getPromptsList() {
+  return Object.values(PROMPT_TEMPLATES).map((prompt) => ({
+    name: prompt.name,
+    description: prompt.description,
+    arguments: prompt.arguments
+  }));
+}
+
+export function renderPrompt(name, args = {}) {
+  const template = PROMPT_TEMPLATES[name];
+  if (!template) {
+    throw new Error(`Unknown prompt: ${name}. Available prompts: ${Object.keys(PROMPT_TEMPLATES).join(', ')}`);
+  }
+
+  const missing = template.arguments
+    .filter((argument) => argument.required && !args[argument.name])
+    .map((argument) => argument.name);
+
+  if (missing.length > 0) {
+    throw new Error(`Missing required arguments for prompt "${name}": ${missing.join(', ')}`);
+  }
+
+  let text = template.template;
+
+  for (const argument of template.arguments) {
+    const value = args[argument.name] ?? argument.default;
+    if (value !== undefined) {
+      text = text.replace(new RegExp(`\\{\\{${argument.name}\\}\\}`, 'g'), String(value));
+    }
+  }
+
+  return {
+    messages: [
+      {
+        role: 'user',
+        content: {
+          type: 'text',
+          text
+        }
+      }
+    ]
+  };
+}

package/server/resources/analytics-columns-reference.md

@@ -0,0 +1,86 @@
+# Pinterest Ads Analytics Columns Reference
+
+Analytics endpoints require a `columns` list. Pinterest exposes ~185 column names;
+this document covers the ones most useful for marketer workflows. All names below
+are valid values on the v5 analytics endpoints.
+
+## Naming Conventions
+
+- `_1` suffix: paid-only metric (attributed to the ad impression itself)
+- `_2` suffix: paid + earned metric (includes downstream organic activity such as saves/repins of the promoted Pin)
+- `TOTAL_` prefix: conversion totals across attribution types (click + engagement + view)
+- `*_IN_MICRO_DOLLAR`: value in micro-currency of the ad account's currency (1,000,000 = 1 unit)
+- `*_IN_DOLLAR`: value in whole currency units of the ad account's currency
+
+## Default Columns Used by This Server
+
+| Column | Meaning |
+|--------|---------|
+| `SPEND_IN_DOLLAR` | Spend in currency units |
+| `IMPRESSION_2` | Paid + earned impressions |
+| `CLICKTHROUGH_2` | Paid + earned Pin clicks |
+| `CTR_2` | Paid + earned click-through rate |
+| `TOTAL_CONVERSIONS` | Total attributed conversions |
+
+## Common Spend and Delivery Columns
+
+- `SPEND_IN_MICRO_DOLLAR`, `SPEND_IN_DOLLAR`
+- `IMPRESSION_1`, `IMPRESSION_2`, `PAID_IMPRESSION`, `TOTAL_IMPRESSION`
+- `TOTAL_IMPRESSION_USER` (reach), `TOTAL_IMPRESSION_FREQUENCY` (frequency)
+- `CLICKTHROUGH_1`, `CLICKTHROUGH_2`, `TOTAL_CLICKTHROUGH`
+- `OUTBOUND_CLICK_1`, `OUTBOUND_CLICK_2`, `OUTBOUND_CTR_1`
+
+## Efficiency Columns
+
+- `CTR`, `CTR_2`, `ECTR`
+- `CPC_IN_MICRO_DOLLAR`, `ECPC_IN_DOLLAR`, `ECPC_IN_MICRO_DOLLAR`
+- `CPM_IN_DOLLAR`, `CPM_IN_MICRO_DOLLAR`, `ECPM_IN_MICRO_DOLLAR`
+- `ECPE_IN_DOLLAR` (cost per engagement), `COST_PER_LEAD`
+- `COST_PER_OUTBOUND_CLICK_IN_DOLLAR`
+
+## Engagement Columns
+
+- `ENGAGEMENT_1`, `ENGAGEMENT_2`, `TOTAL_ENGAGEMENT`
+- `ENGAGEMENT_RATE`, `EENGAGEMENT_RATE`
+- `REPIN_1`, `REPIN_2`, `REPIN_RATE` (saves)
+
+## Conversion Columns
+
+- `TOTAL_CONVERSIONS`
+- `TOTAL_CHECKOUT`, `TOTAL_CHECKOUT_VALUE_IN_MICRO_DOLLAR`, `CHECKOUT_ROAS`
+- `TOTAL_CLICK_CHECKOUT`, `TOTAL_VIEW_CHECKOUT`, `TOTAL_ENGAGEMENT_CHECKOUT`
+- `TOTAL_SIGNUP`, `TOTAL_SIGNUP_VALUE_IN_MICRO_DOLLAR`
+- `TOTAL_LEAD`, `LEADS`, `TOTAL_PAGE_VISIT`, `PAGE_VISIT_ROAS`
+- `TOTAL_ADD_TO_CART_CONVERSION_RATE`, `TOTAL_CHECKOUT_CONVERSION_RATE`
+- `TOTAL_WEB_SESSIONS`, `WEB_SESSIONS_1`, `WEB_SESSIONS_2`
+
+## Video Columns
+
+- `TOTAL_VIDEO_3SEC_VIEWS`, `TOTAL_VIDEO_MRC_VIEWS`
+- `TOTAL_VIDEO_P25_COMBINED` through `TOTAL_VIDEO_P95_COMBINED`, `TOTAL_VIDEO_P100_COMPLETE`
+- `TOTAL_VIDEO_AVG_WATCHTIME_IN_SECOND`, `VIDEO_LENGTH`
+- `ECPV_IN_DOLLAR` (cost per view), `ECPCV_IN_DOLLAR` (cost per completed view)
+- `PAID_VIDEO_VIEWABLE_RATE`, `VIDEO_SPEND_IN_DOLLAR`
+
+## Dimension / Metadata Columns
+
+Useful for labeling rows in entity-level reports:
+
+- `CAMPAIGN_ID`, `CAMPAIGN_NAME`, `CAMPAIGN_ENTITY_STATUS`, `CAMPAIGN_OBJECTIVE_TYPE`
+- `CAMPAIGN_DAILY_SPEND_CAP`, `CAMPAIGN_LIFETIME_SPEND_CAP`
+- `AD_GROUP_ID`, `AD_GROUP_NAME`, `AD_GROUP_ENTITY_STATUS`, `AD_GROUP_BUDGET_TYPE`
+- `AD_ID`, `AD_NAME`, `PIN_ID`, `PIN_PROMOTION_ID`
+
+## Attribution Windows
+
+Conversion metrics respect the requested attribution windows:
+
+- `click_window_days` (default 30), `engagement_window_days` (default 30), `view_window_days` (default 1)
+- Each accepts `0, 1, 7, 14, 30, 60`
+- `conversion_report_time` controls whether conversions are bucketed by ad action time (default) or conversion time
+
+## Granularity Notes
+
+- `TOTAL` aggregates the full range into one row; other granularities add a `DATE` field per row
+- `HOUR` granularity no longer returns conversion metrics (non-conversion metrics still work)
+- Dates are limited to 90 days back and a 90-day range

package/server/resources/api-reference.md

@@ -0,0 +1,100 @@
+# Pinterest Ads REST API v5 Quick Reference
+
+## Base URL
+
+`https://api.pinterest.com/v5`
+
+## Authentication
+
+- Auth is sent via `Authorization: Bearer <TOKEN>` request header.
+- This server reads a static token from `PINTEREST_ADS_ACCESS_TOKEN`, or refreshes one
+  when `PINTEREST_ADS_CLIENT_ID`, `PINTEREST_ADS_CLIENT_SECRET`, and
+  `PINTEREST_ADS_REFRESH_TOKEN` are all set.
+- Token refresh: `POST /oauth/token` with `Authorization: Basic base64(client_id:client_secret)`
+  and form body `grant_type=refresh_token&refresh_token=<TOKEN>`.
+- Pinterest uses continuous refresh tokens (60-day expiration window). Refresh responses
+  may include a rotated `refresh_token`; this server logs a stderr warning when that
+  happens because it cannot persist the new value itself.
+- Required scopes: `ads:read` for read tools, `ads:write` for mutate.
+
+## Pagination
+
+All list endpoints use bookmark cursors:
+
+- Request params: `page_size` (default 25, max 250) and `bookmark`
+- Response envelope: `{ "items": [...], "bookmark": "<cursor>" | null }`
+- A `null`/absent bookmark means the last page was reached
+
+## Account Discovery
+
+- List accounts: `GET /ad_accounts`
+- Optional param: `include_shared_accounts` (default true)
+- Account fields include: `id`, `name`, `currency`, `country`, `owner{id,username}`, `time_zone`, `permissions`
+
+## Entity Endpoints (by Ad Account)
+
+- Campaigns: `GET /ad_accounts/<AD_ACCOUNT_ID>/campaigns`
+- Ad groups: `GET /ad_accounts/<AD_ACCOUNT_ID>/ad_groups`
+- Ads: `GET /ad_accounts/<AD_ACCOUNT_ID>/ads`
+
+Useful query params (arrays are comma-separated strings):
+
+- `entity_statuses`: `ACTIVE`, `PAUSED`, `ARCHIVED`, `DRAFT`, `DELETED_DRAFT` (API default: `ACTIVE,PAUSED`)
+- `campaign_ids`: all three endpoints
+- `ad_group_ids`: ad_groups and ads endpoints
+- `ad_ids`: ads endpoint only
+- `order`: `ASCENDING` or `DESCENDING` by ID (higher IDs are more recent)
+
+## Analytics Endpoints
+
+- Account: `GET /ad_accounts/<ID>/analytics`
+- Campaigns: `GET /ad_accounts/<ID>/campaigns/analytics` (requires `campaign_ids`)
+- Ad groups: `GET /ad_accounts/<ID>/ad_groups/analytics` (requires `ad_group_ids`)
+- Ads: `GET /ad_accounts/<ID>/ads/analytics` (requires `ad_ids`)
+
+Required params: `start_date`, `end_date` (YYYY-MM-DD, UTC), `columns` (comma-separated), `granularity` (`TOTAL`, `DAY`, `HOUR`, `WEEK`, `MONTH`).
+
+Constraints:
+
+- `start_date` cannot be more than 90 days back from today
+- `end_date` cannot be more than 90 days past `start_date`
+- `HOUR` granularity no longer returns conversion metrics
+
+Optional params: `click_window_days`, `engagement_window_days`, `view_window_days`
+(each one of `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`).
+
+The response is a JSON array of row objects keyed by column name (plus `DATE` for
+non-TOTAL granularities).
+
+## Mutations
+
+Pinterest v5 uses bulk-array request bodies (max 30 items per request):
+
+- Create: `POST /ad_accounts/<ID>/campaigns` (or `/ad_groups`, `/ads`) with an array of creation objects
+- Update: `PATCH` on the same paths with an array of `{ "id": "...", ...changes }`
+- Status change: `PATCH` with `status` set to `ACTIVE`, `PAUSED`, or `ARCHIVED`
+- Response envelope: `{ "items": [{ "data": {...}, "exceptions": [...] }] }` — check `exceptions` per item
+
+Required create fields:
+
+- Campaign: `name`, `objective_type` (`AWARENESS`, `CONSIDERATION`, `WEB_CONVERSION`, `CATALOG_SALES`, `VIDEO_COMPLETION`, `APP_INSTALL`, `SALES`, `LEADS`, `CTV_CONSIDERATION`)
+- Ad group: `name`, `campaign_id`, `billable_event`
+- Ad: `ad_group_id`, `pin_id`, `creative_type`
+
+Notes:
+
+- There is NO delete for campaigns, ad groups, or ads — `ARCHIVED` is the terminal state
+- Archived entities cannot be reactivated
+- Budget and spend cap fields are in micro-currency (1,000,000 = 1 currency unit)
+- `objective_type` can only be updated on draft campaigns
+
+## Error Handling
+
+Errors are JSON `{ "code": <int>, "message": "<text>" }` with an HTTP status
+(400, 401, 403, 404, 429). This server:
+
+- Surfaces errors as `Pinterest Ads API request failed (<status>): <message>`
+- Retries once on HTTP `429`, honoring `Retry-After` when present (fallback: 60s)
+- Does not retry `401` (invalid/expired token)

package/server/resources/index.js

@@ -0,0 +1,65 @@
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+/**
+ * Static list of resource documents exposed by the server.
+ */
+export const RESOURCES = [
+  {
+    uri: 'pinterestads://reference',
+    name: 'Pinterest Ads API Reference',
+    description: 'Core REST API v5 endpoints, query parameters, pagination, and error handling notes for Pinterest Ads workflows',
+    mimeType: 'text/markdown'
+  },
+  {
+    uri: 'pinterestads://analytics-columns',
+    name: 'Pinterest Ads Analytics Columns Reference',
+    description: 'Common analytics column names, attribution window semantics, and micro-currency conventions',
+    mimeType: 'text/markdown'
+  },
+  {
+    uri: 'pinterestads://rate-limits',
+    name: 'Pinterest Ads Rate Limits and Quotas',
+    description: 'Rate limiting behavior, backoff guidance, and operational recommendations',
+    mimeType: 'text/markdown'
+  }
+];
+
+const RESOURCE_FILE_MAP = {
+  'pinterestads://reference': 'api-reference.md',
+  'pinterestads://analytics-columns': 'analytics-columns-reference.md',
+  'pinterestads://rate-limits': 'rate-limits-and-quotas.md'
+};
+
+export function getResourcesList() {
+  return RESOURCES;
+}
+
+/**
+ * Read a resource document by URI.
+ * @param {string} uri
+ * @returns {{ contents: Array<{ uri: string, mimeType: string, text: string }> }}
+ */
+export function readResource(uri) {
+  const filename = RESOURCE_FILE_MAP[uri];
+  if (!filename) {
+    throw new Error(`Unknown resource: ${uri}. Available: ${Object.keys(RESOURCE_FILE_MAP).join(', ')}`);
+  }
+
+  const filePath = join(__dirname, filename);
+  const content = readFileSync(filePath, 'utf8');
+
+  return {
+    contents: [
+      {
+        uri,
+        mimeType: 'text/markdown',
+        text: content
+      }
+    ]
+  };
+}

package/server/resources/rate-limits-and-quotas.md

@@ -0,0 +1,39 @@
+# Pinterest Ads Rate Limits and Quotas
+
+Pinterest enforces per-app, per-user rate limits on REST API v5. Limits are grouped
+by endpoint category (for example ads read vs. ads write) and depend on your app's
+access level — Trial access has much lower limits than Standard access. Exact
+per-category numbers are published at
+https://developers.pinterest.com/docs/reference/ratelimits/ and can change; treat
+HTTP `429` as the authoritative throttling signal.
+
+## What This MCP Server Does
+
+- Treats HTTP `429` as a throttling signal.
+- Reads the `Retry-After` response header when available.
+- Falls back to `60` seconds if `Retry-After` is missing or invalid.
+- Retries throttled requests once.
+
+## Backoff Behavior
+
+`Retry-After` values may be:
+
+- Integer seconds (for example `7`)
+- HTTP date string
+
+The server converts this to milliseconds and sleeps before a single retry.
+
+## Timeout Behavior
+
+- Requests use a default timeout of `30000` ms.
+- Override with `PINTEREST_ADS_REQUEST_TIMEOUT_MS` environment variable.
+- Timeout errors are surfaced as request failures so callers can retry or degrade gracefully.
+
+## Operational Guidance
+
+- Use `page_size` up to 250 to minimize pagination round trips.
+- Set `limit` deliberately on `query` — the server stops paginating once satisfied.
+- Batch analytics pulls by passing multiple ids (`campaign_ids`, `ad_group_ids`, `ad_ids`) per call instead of one call per entity.
+- Keep `columns` narrow; wide column sets are slower to compute.
+- Stagger high-volume jobs across accounts to reduce burst pressure.
+- Token refreshes count against OAuth limits — this server caches the access token until ~5 minutes before expiry.